Metadata-Version: 2.5
Name: powercontext
Version: 0.0.1
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
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.14.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'
Provides-Extra: cli
Requires-Dist: httpx[socks]<1,>=0.28; 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: 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.14.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: 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

PowerContext is PowerMem 2.0, the upgraded version of [PowerMem](https://www.powermem.ai/). It 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, and
a Codex plugin.

PowerContext can be installed directly from its Git URL. Users need read access to that URL, but they do not need to
clone the repository or run commands from its working tree.

## Install for Codex

Prerequisites:

- macOS or Linux;
- [uv](https://docs.astral.sh/uv/getting-started/installation/);
- Codex CLI;
- read access to `oceanbase/powercontext`.

Install the tool and configure the Codex plugin:

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

You do not need to create or manage a repository checkout. Start the local service in a terminal:

```bash
powercontext server run
```

In another terminal, verify the package and Server dependencies, then the optional Codex integration:

```bash
powercontext doctor
powercontext doctor codex
```

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 command does not affect Server health.

Start a new Codex session after installation. Open `/hooks` once and approve the PowerContext hook if Codex asks for
trust. The default database is persistent and requires no configuration.

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

## Choose an interface

| Interface | Use it for |
| --- | --- |
| Codex plugin | Restore relevant project memory and explicitly remember, revise, or retire entries while coding |
| 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 |

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

## Python projects

Add only the role the project imports:

```bash
uv add "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"
```

Available extras are `builtin`, `client`, `server`, and `cli`. The CLI always includes Server-backed content commands;
installing the `server` role also makes local Server process management available.

## Benchmarks

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

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

The PowerContext results come from a full 1,540-question run across all 10 LOCOMO conversations.

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

## License

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