Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
update readme
  • Loading branch information
Alanxtl committed Aug 20, 2026
commit ff9bf5d91d7567c5b4e637fac7dcd62cfedff9d9
154 changes: 97 additions & 57 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,97 +1,137 @@
# PowerContext

**PowerContext is PowerMem 2.0, the upgraded version of [PowerMem](https://www.powermem.ai/).**
**Not only memory**

[![PyPI version](https://img.shields.io/pypi/v/powercontext)](https://pypi.org/project/powercontext/)
[![License Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/74cF8vbNEs)

PowerContext gives agents durable, project-scoped context. A later session can recover a decision, outcome, current state, or next step without relying on chat history. PowerContext includes a local Server, SQLite storage, an async Python client, a Core SDK, a CLI, a Codex plugin, and a DeepSeek Harness plugin.
*[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*

PowerContext is the upgraded version of [PowerMem](https://www.powermem.ai/) and a context runtime for human-agent
collaboration. It turns shared work into project context that can be understood, handed off, and continued.

## Install for Codex or DeepSeek Harness
## Core capabilities

Prerequisites:
| Capability | Core value |
| --- | --- |
| Memory extraction and management | Explicitly record decisions, constraints, outcomes, state, and next steps worth reusing over time; with a generation model configured, Memory can also be extracted from Sources. Revisions and retirements preserve history |
| Bounded request-time recall | Before an agent handles a request, generate one schema-validated, cited `PreparedContext` based on project scope, relevance, and a byte budget; recall failures do not block the original task |
| Handoff | Organize the objective, verified progress, blockers, next step, and evidence into an inspectable work package so another session, task, model, or agent host can continue from a clear state |
| Sources and evidence lineage | Preserve the original sources of knowledge and link Memory and Artifacts with exact citations; capturing a prompt creates only a Source and does not directly turn it into Memory |
| Experience and Skill governance | A model or caller can only submit a Candidate; an immutable revision is created only after Review, and a Skill must still be exported explicitly—it cannot approve, install, or execute itself |
| Local and service deployment | Use SQLite directly for local development, choose OceanBase for team deployments, and integrate with existing systems through HTTP/OpenAPI, MCP, authentication, and OpenTelemetry |

- macOS or Linux;
- [uv](https://docs.astral.sh/uv/getting-started/installation/);
- Codex CLI and/or DeepSeek Harness (`dsh`).
## Benchmarks

```bash
uv tool install "powercontext[cli,server]==0.0.1"
powercontext --version
```
### [LoCoMo](https://github.com/snap-research/locomo)

The version command should print `0.0.1`. Configure the matching host plugin from the same release tag:
| Metric | PowerContext | [PowerMem](https://www.powermem.ai/benchmark) | Full-context baseline |
| --- | ---: | ---: | ---: |
| Accuracy | **90.78%** (1,398/1,540) | 87.79% | 52.9% |
| Search p95 latency | **1.38 s** | 1.44 s | 17.12 s |
| Answer tokens per question | **~1.65k** | ~0.9k | 26k |

```bash
powercontext setup codex --source oceanbase/powercontext --ref v0.0.1
powercontext setup dsh --source oceanbase/powercontext --ref v0.0.1
```
The PowerContext result covers all 1,540 scored questions across the benchmark's 10 conversations. See the
[LoCoMo evaluation details](benchmark/locomo/README.md) for dataset selection, retrieval, judging, latency, token, and
Artifact boundaries.

Start the local service in a terminal:
### [SWE-bench Pro public v2](https://github.com/scaleapi/SWE-bench_Pro-os)

```bash
powercontext server run
```
In a paired evaluation over all **731 tasks** in
[SWE-bench Pro public v2](https://github.com/scaleapi/SWE-bench_Pro-os), enabling PowerContext increased the task
resolution rate from **82.35%** to **86.73%**, an improvement of **4.38 percentage points**.

The Server listens on `http://127.0.0.1:8000` by default and stores its SQLite database in the platform-specific user data directory. Keep this process running while using PowerContext. In another terminal, verify the package, Server,
and Codex integration:
The evaluation ran in a Codex environment, with both the PowerContext OFF and ON groups using the `gpt-5.6-sol`
model.

```bash
powercontext doctor
powercontext doctor codex
powercontext doctor dsh
```
| Result | PowerContext OFF | PowerContext ON | Change |
| --- | ---: | ---: | ---: |
| Resolved tasks | 602 / 731 | **634 / 731** | **+32** |
| Resolution rate | 82.35% | **86.73%** | **+4.38 percentage points** |

Runtime or database failures make the Server not ready. A configured inference failure is reported as degraded without removing the Server from traffic; the separate Codex and DeepSeek Harness commands do not affect Server health.
[SWE-bench Pro public v2 evaluation details](evaluation/README.md).

Start a new Codex session after setup. Open `/hooks` once and approve the PowerContext hook if Codex asks for trust.
---

See the [Codex quickstart](docs/en/docs/tutorials/codex-quickstart.md) for a first cross-session workflow.
## Plugins

## Choose an interface
PowerContext provides official plugins and installation guides for Codex, Claude Code, and DeepSeek Harness. All
three integrations use the same scoped data and history-preserving contracts through PowerContext Server; the
plugins do not start or embed the Server.

| Interface | Use it for |
| --- | --- |
| Codex plugin | Restore relevant project memory and explicitly remember, revise, or retire entries while coding |
| DeepSeek Harness plugin | Restore relevant project memory and explicitly remember, revise, or retire entries in DeepSeek Harness |
| Hermes plugin | Restore relevant project memory and explicitly remember, revise, or retire entries in Hermes. See [Hermes integration](./integrations/hermes/README.md) for more details |
| CLI | Install the plugin, run or connect to the Server, inspect content, and diagnose an installation |
| Python client | Call the Server's Source and Memory API from an application |
| Core SDK | Embed PowerContext contracts or supply custom adapters in a Python system |
| HTTP and MCP | Integrate a non-Python process or an agent host with the running Server |
### Official integrations

<table>
<tr>
<td align="center" width="120"><img src="https://github.com/openai.png?size=120" alt="Codex" width="48" height="48" /><br /><sub><b>Codex</b></sub></td>
<td align="center" width="120"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /><br /><sub><b>Claude Code</b></sub></td>
<td align="center" width="120"><img src="https://github.com/deepseek-ai.png?size=120" alt="DeepSeek Harness" width="48" height="48" /><br /><sub><b>DeepSeek Harness</b></sub></td>
<td align="center" width="120"><img src="https://github.com/NousResearch/hermes-agent/blob/main/website/static/img/logo.png?raw=true&size=120" alt="Hermes Agent" width="48" height="48" /><br /><a href="integrations/hermes/README.md"><sub><b>Hermes Agent</b></sub></a></td>
</tr>
</table>

The [interface reference](docs/en/docs/reference/interfaces.md) explains the ownership boundary between these
surfaces. Installation, configuration, and troubleshooting live under [`docs/en/docs/`](docs/en/docs/index.md).
## Quick start

## Python projects
You need macOS or Linux, Python 3.11 or newer, [`uv`](https://docs.astral.sh/uv/), and Codex CLI.

Add only the role the project imports:
### 1. Install PowerContext and the plugins

```bash
uv add "powercontext[client]==0.0.1"
uv tool install "powercontext[cli,server]==0.0.2"

# Choose one or more integrations.
powercontext setup codex --source oceanbase/powercontext --ref v0.0.2
powercontext setup claude-code --source oceanbase/powercontext --ref v0.0.2
powercontext setup dsh --source oceanbase/powercontext --ref v0.0.2
```

Available extras are `builtin`, `client`, `server`, `cli`, and `tracing-otlp`. The CLI always includes Server-backed content commands; installing the `server` role also makes local Server process management available.
The first command installs the CLI and local Server in an isolated environment. The subsequent setup commands
install the corresponding plugins from the matching repository tag. Run setup again to refresh an existing
installation.

## Benchmarks
### 2. Start and verify the local Server

### [LOCOMO](https://github.com/snap-research/locomo)
Keep the Server running in one terminal:

| Metric | PowerContext | [PowerMem](https://www.powermem.ai/benchmark) | Full-context baseline |
| --- | ---: | ---: | ---: |
| Accuracy | **90.78%** (1,398/1,540) | 87.79% | 52.9% |
| Search p95 latency | **1.38 s** | 1.44 s | 17.12 s |
| Answer tokens / question | **~1.65 k** | ~0.9 k | 26 k |
```bash
powercontext server run
```

In another terminal, verify the service and plugin:

```bash
powercontext doctor
powercontext doctor codex # or: claude-code / dsh
```

The PowerContext results come from a full 1,540-question run across all 10 LOCOMO conversations.
By default, the Server listens on `127.0.0.1:8000`, exposes Streamable HTTP MCP at `/mcp`, and persists data in a
local SQLite database. Explicit Memory operations work without configuring an inference provider.

## Development

Repository contributors can install the locked environment and hooks with `make install`. Use `make test`,
`make check`, and `make docs-test` before opening a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full
workflow and [`docs/en/development/`](docs/en/development/core-protocol.md) for implementation guides.
Install the locked development environment and hooks:

```bash
make install
```

Run the main validation commands before opening a pull request:

```bash
make check
make test
make docs-test
```

After changing `openapi/powercontext.yaml`, run `make contract-test`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
complete workflow and [`docs/en/development/`](docs/en/development/core-protocol.md) for implementation guides.

## Community

Questions and feedback are welcome in [Discord](https://discord.com/invite/74cF8vbNEs). Use
[GitHub Issues](https://github.com/oceanbase/powercontext/issues) for reproducible defects and focused feature
requests.

## License

Expand Down