Metadata-Version: 2.5
Name: powercontext
Version: 0.1.0
Summary: PowerContext turns human-agent work into handoff-ready context.
Project-URL: Homepage, https://github.com/oceanbase/powercontext
Project-URL: Repository, https://github.com/oceanbase/powercontext
Project-URL: Documentation, https://github.com/oceanbase/powercontext/tree/master/docs/en/docs
Author-email: PowerContext Team <open_oceanbase@oceanbase.com>
License-File: LICENSE
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: rfc8785<1,>=0.1.4
Requires-Dist: typing-extensions<5,>=4.12
Provides-Extra: builtin
Requires-Dist: aiosqlite<1,>=0.22; extra == 'builtin'
Requires-Dist: apscheduler<4,>=3.11; extra == 'builtin'
Requires-Dist: pydantic-ai-slim[anthropic,openai]<3,>=2.27.1; extra == 'builtin'
Requires-Dist: pydantic-settings<3,>=2.7; extra == 'builtin'
Requires-Dist: pyobvector<0.3,>=0.2.28; extra == 'builtin'
Requires-Dist: sqlalchemy[asyncio]<3,>=2; extra == 'builtin'
Requires-Dist: sqlite-vec<0.2,>=0.1.9; extra == 'builtin'
Provides-Extra: cli
Requires-Dist: httpx[socks]<1,>=0.28; extra == 'cli'
Requires-Dist: inquirerpy<1,>=0.3; extra == 'cli'
Requires-Dist: opentelemetry-api<2,>=1.30; extra == 'cli'
Requires-Dist: platformdirs<5,>=4; extra == 'cli'
Requires-Dist: pydantic-settings<3,>=2.7; extra == 'cli'
Requires-Dist: typer<1,>=0.16; extra == 'cli'
Provides-Extra: client
Requires-Dist: httpx[socks]<1,>=0.28; extra == 'client'
Requires-Dist: opentelemetry-api<2,>=1.30; extra == 'client'
Requires-Dist: pydantic-settings<3,>=2.7; extra == 'client'
Provides-Extra: seekdb
Requires-Dist: aiosqlite<1,>=0.22; extra == 'seekdb'
Requires-Dist: apscheduler<4,>=3.11; extra == 'seekdb'
Requires-Dist: pydantic-ai-slim[anthropic,openai]<3,>=2.27.1; extra == 'seekdb'
Requires-Dist: pydantic-settings<3,>=2.7; extra == 'seekdb'
Requires-Dist: pylibseekdb<2,>=1.3.0.post4; (sys_platform == 'linux' or sys_platform == 'darwin') and extra == 'seekdb'
Requires-Dist: pyobvector<0.3,>=0.2.28; extra == 'seekdb'
Requires-Dist: sqlalchemy[asyncio]<3,>=2; extra == 'seekdb'
Requires-Dist: sqlite-vec<0.2,>=0.1.9; extra == 'seekdb'
Provides-Extra: server
Requires-Dist: aiosqlite<1,>=0.22; extra == 'server'
Requires-Dist: apscheduler<4,>=3.11; extra == 'server'
Requires-Dist: fastapi<1,>=0.115; extra == 'server'
Requires-Dist: fastmcp<4,>=3.4; extra == 'server'
Requires-Dist: jinja2<4,>=3.1; extra == 'server'
Requires-Dist: opentelemetry-api<2,>=1.30; extra == 'server'
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == 'server'
Requires-Dist: platformdirs<5,>=4; extra == 'server'
Requires-Dist: prometheus-client<1,>=0.21; extra == 'server'
Requires-Dist: pydantic-ai-slim[anthropic,openai]<3,>=2.27.1; extra == 'server'
Requires-Dist: pydantic-settings<3,>=2.7; extra == 'server'
Requires-Dist: pyobvector<0.3,>=0.2.28; extra == 'server'
Requires-Dist: sqlalchemy[asyncio]<3,>=2; extra == 'server'
Requires-Dist: sqlite-vec<0.2,>=0.1.9; extra == 'server'
Requires-Dist: uvicorn<1,>=0.34; extra == 'server'
Provides-Extra: tracing-otlp
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == 'tracing-otlp'
Description-Content-Type: text/markdown

# PowerContext

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="theme/powercontext/assets/images/powercontext-reverse.png">
  <img alt="PowerContext" src="theme/powercontext/assets/images/powercontext-color.png" width="480" />
</picture>

**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)

*[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*

</div>

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.

## Quick start

You need macOS or Linux, Python 3.11 or newer, [`uv`](https://docs.astral.sh/uv/), and at least one supported agent
host.

### 1. Install PowerContext and integrations

```bash
uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"

# Choose one or more integrations. Every setup command installs from the master branch.
powercontext setup codex --source oceanbase/powercontext --ref master
powercontext setup claude-code --source oceanbase/powercontext --ref master
powercontext setup dsh --source oceanbase/powercontext --ref master
powercontext setup hermes --source oceanbase/powercontext --ref master
powercontext setup openclaw --source oceanbase/powercontext --ref master
powercontext setup opencode --source oceanbase/powercontext --ref master
powercontext setup pi --source oceanbase/powercontext --ref master
powercontext setup workbuddy --source oceanbase/powercontext --ref master

# Or install several hosts in one pass.
powercontext setup select --host codex --host claude-code --host opencode \
  --source oceanbase/powercontext --ref master
```

The first command installs the CLI and local Server from the latest `master` revision in an isolated environment.
Every setup command installs its integration from the same `master` revision. Run setup again to refresh an existing
integration.

### 2. Start and verify the local Server

Keep the Server running in one terminal:

```bash
powercontext server run
```

In another terminal, verify the service and plugin:

```bash
powercontext doctor
powercontext doctor integrations
powercontext doctor codex  # Replace codex with the host you installed.
```

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.

## Core capabilities

| 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 |

## Benchmarks

### [LoCoMo](https://github.com/snap-research/locomo)

![LOCOMO benchmark comparison showing PowerContext accuracy, search latency, and answer token usage against PowerMem and a full-context baseline](docs/assets/locomo-benchmark-comparison.svg)

### [SWE-bench Pro public v2](https://github.com/scaleapi/SWE-bench_Pro-os)

![SWE-bench Pro public v2 comparison showing an increase from 82.35% with PowerContext off to 86.73% with PowerContext on](docs/assets/swe-bench-pro-public-v2-comparison.svg)

The evaluation ran in a Codex environment, with both the PowerContext OFF and ON groups using the `gpt-5.6-sol`
model.

---

## Integrations

PowerContext provides official integrations and installation guides for Codex, Claude Code, DeepSeek Harness, Hermes
Agent, Pi Coding Agent, OpenClaw, OpenCode, WorkBuddy, Bub, Pydantic AI, LangChain, and LangGraph. These integrations
use the same scoped data and history-preserving contracts through PowerContext Server; the host integrations do not
start or embed the Server.

### Official integrations

<table>
<tr>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-codex.md"><img src="https://github.com/openai.png?size=120" alt="Codex" width="48" height="48" /><br /><sub><b>Codex</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-claude-code.md"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /><br /><sub><b>Claude Code</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-dsh.md"><img src="https://github.com/deepseek-ai.png?size=120" alt="DeepSeek Harness" width="48" height="48" /><br /><sub><b>DeepSeek Harness</b></sub></a></td>
<td align="center" width="120"><a href="integrations/hermes/README.md"><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 /><sub><b>Hermes Agent</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-pi.md"><img src="https://github.com/earendil-works.png?size=120" alt="Pi Coding Agent" width="48" height="48" /><br /><sub><b>Pi Coding Agent</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-openclaw.md"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /><br /><sub><b>OpenClaw</b></sub></a></td>
</tr>
<tr>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-opencode.md"><img src="https://github.com/anomalyco.png?size=120" alt="OpenCode" width="48" height="48" /><br /><sub><b>OpenCode</b></sub></a></td>
<td align="center" width="120"><a href="integrations/workbuddy/README.md"><img src="docs/assets/workbuddy.svg" alt="WorkBuddy" width="48" height="48" /><br /><sub><b>WorkBuddy</b></sub></a></td>
<td align="center" width="120"><a href="integrations/bub/README.md"><img src="https://github.com/bubbuild.png?size=120" alt="Bub" width="48" height="48" /><br /><sub><b>Bub</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-pydantic-ai.md"><img src="https://github.com/pydantic.png?size=120" alt="Pydantic AI" width="48" height="48" /><br /><sub><b>Pydantic AI</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-langchain.md"><img src="https://github.com/langchain-ai.png?size=120" alt="LangChain" width="48" height="48" /><br /><sub><b>LangChain</b></sub></a></td>
<td align="center" width="120"><a href="docs/en/docs/how-to/configure-langgraph.md"><img src="https://github.com/langchain-ai.png?size=120" alt="LangGraph" width="48" height="48" /><br /><sub><b>LangGraph</b></sub></a></td>
</tr>
</table>

Python agent applications can use the [LangChain middleware](docs/en/docs/how-to/configure-langchain.md), the
[LangGraph node and tools adapter](docs/en/docs/how-to/configure-langgraph.md), the
[Pydantic AI middleware](docs/en/docs/how-to/configure-pydantic-ai.md), or the
[Bub plugin](integrations/bub/README.md).

## Development

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

PowerContext is licensed under the [Apache License 2.0](LICENSE).
