# ContextPocket

**Persistent local project memory for AI coding agents.**

> Your coding agent forgets. ContextPocket remembers.

ContextPocket gives Codex, Claude Code, Cursor, and other MCP-compatible coding agents a small, durable memory beside each repository. It keeps architecture decisions, preferences, known issues, failed approaches, and unfinished tasks available across sessions without turning your project into a cloud knowledge base.

**Local by default. No account. No telemetry. No LLM API key. No vector database.**

<p align="center"><img src="assets/contextpocket-demo.svg" alt="ContextPocket terminal demo" width="100%"></p>

## Why ContextPocket?

A new coding-agent session often starts with the same expensive conversation:

- Which framework did we choose?
- Which approach already failed?
- What constraints must not be violated?
- What bug is still open?
- What should I continue next?

ContextPocket stores only the durable answers.

```text
Session 1
You: "Use SQLite. Keep this project local-first. Do not add LangChain."
Agent -> ContextPocket: saves three durable memories

...three days later...

Session 2
Agent -> ContextPocket: reads project context
Agent: "I know this project uses SQLite, stays local-first, and avoids LangChain."
```

## What it stores

Five deliberately small memory types:

| Type | Example |
| --- | --- |
| `decision` | Use SQLite instead of PostgreSQL |
| `preference` | Avoid LangChain in this repository |
| `issue` | Windows packaging fails on non-ASCII paths |
| `task` | Add drag-and-drop PDF import |
| `note` | Authentication code lives under `src/auth/` |

Memories also have importance, tags, lifecycle state, source, timestamps, and an optional `supersedes` link for replacing an old decision without erasing history.

## Quick start

### 1. Clone and install

Core CLI only:

```bash
python -m pip install -e .
```

CLI + MCP support:

```bash
python -m pip install -e ".[mcp]"
```

For isolated global CLI installation, `pipx` or `uv tool` also work with a Git checkout or a future PyPI release.

### 2. Initialize a repository

```bash
cd your-project
contextpocket init
```

This creates local storage under:

```text
.contextpocket/
  config.toml
  context.db
```

If the directory is a Git repository, ContextPocket adds `/.contextpocket/` to `.git/info/exclude` so local memory is not normally committed.

### 3. Save durable context

```bash
contextpocket remember \
  "Use SQLite because the project must stay local-first." \
  --title "Database choice" \
  --type decision \
  --importance 5 \
  --tag architecture \
  --tag database
```

### 4. Search it later

```bash
contextpocket search "database"
```

### 5. Rehydrate a new agent session

```bash
contextpocket summary
```

Example output:

```markdown
# Project Context

## Important Decisions
- **Database choice** — Use SQLite because the project must stay local-first.

## Preferences & Constraints
- **Dependency policy** — Do not add LangChain.

## Open Issues
- **Windows packaging** — Non-ASCII install paths still fail.
```

## CLI

```text
contextpocket init [path]
contextpocket status
contextpocket remember <content> [options]
contextpocket search <query>
contextpocket list
contextpocket show <id>
contextpocket update <id> [options]
contextpocket resolve <id>
contextpocket archive <id>
contextpocket summary [--output FILE]
contextpocket export FILE.json
contextpocket doctor
```

Run `contextpocket <command> --help` for command-specific options.

## MCP

Install the optional MCP extra, initialize the target project, and configure the host to launch:

```text
contextpocket-mcp
```

from that repository's working directory. If a host cannot set `cwd`, set:

```text
CONTEXTPOCKET_PROJECT=/absolute/path/to/project
```

Available MCP tools:

- `memory_add`
- `memory_search`
- `memory_list`
- `memory_get`
- `memory_resolve`
- `project_context`

Available resources:

- `contextpocket://project/summary`
- `contextpocket://project/decisions`
- `contextpocket://project/issues`

See [`docs/mcp-setup.md`](docs/mcp-setup.md) for the configuration shape and agent guidance.

## Memory quality matters more than memory quantity

ContextPocket is **not** a transcript archive and does not automatically ingest your repository.

Save things that will still matter in another session:

- architecture decisions
- implementation constraints
- durable user/team preferences
- failed approaches worth avoiding
- known bugs and risks
- unfinished tasks

Do not save:

- raw terminal logs
- whole source files
- every command executed
- casual conversation
- duplicate facts
- secrets

See [`docs/memory-policy.md`](docs/memory-policy.md).

## Search without embeddings

v0.1.0 uses SQLite FTS5 plus importance/lifecycle filtering. The deterministic core needs no model download, vector service, embedding API, or internet connection.

This is intentional. Semantic search may become an **optional** future capability, but simple installation and predictable behavior come first.

## Memory lifecycle

Project truth changes. ContextPocket keeps history without feeding stale decisions back to the agent:

```text
active -> resolved
active -> superseded
active -> archived
```

When replacing a decision, save the new memory with `--supersedes <old-id>`. The old record becomes `superseded`; the new one becomes the active context.

## Privacy

ContextPocket core makes no network requests and includes no telemetry or account system. Common credential patterns are rejected before persistence.

Secret detection is defense in depth, not encryption. v0.1.0 does **not** encrypt `context.db` at rest. Anyone with filesystem access to the database may be able to read it.

See [`docs/privacy.md`](docs/privacy.md) and [`SECURITY.md`](SECURITY.md).

## Architecture

```mermaid
flowchart TD
    A[Codex / Claude Code / Cursor] -->|MCP stdio| B[MCP adapter]
    C[CLI] --> D[Memory service]
    B --> D
    D --> E[Memory rules]
    D --> F[Repository]
    F --> G[(SQLite + FTS5)]
```

The MCP layer is intentionally an adapter. Storage and business rules work independently of the MCP SDK.

See [`docs/architecture.md`](docs/architecture.md).

## Development

```bash
python -m pip install -e ".[dev]"
pytest
python scripts/smoke_test.py
```

To exercise the real MCP adapter too:

```bash
python -m pip install -e ".[dev,mcp]"
pytest
```

CI covers Python 3.10–3.13 on Ubuntu, Windows, and macOS.

## Project status

`v0.1.0` is an alpha release focused on one job: reliable local project memory.

Not in v0.1.0:

- cloud sync
- accounts or teams
- web dashboard
- desktop GUI
- repository-wide code indexing
- automatic embeddings
- vector databases
- LLM-generated summaries

The narrow scope is intentional.

## Contributing

Bug reports, docs fixes, tests, and focused improvements are welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a PR.

## License

MIT — see [`LICENSE`](LICENSE).