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.

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.

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

Related MCP server: io.github.silversurfer562/memdocs

What it stores

Five deliberately small memory types:

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:

python -m pip install -e .

CLI + MCP support:

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

cd your-project
contextpocket init

This creates local storage under:

.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

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

contextpocket search "database"

5. Rehydrate a new agent session

contextpocket summary

Example output:

# 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

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:

contextpocket-mcp

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

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

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:

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 and SECURITY.md.

Architecture

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.

Development

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

To exercise the real MCP adapter too:

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 before opening a PR.

License

MIT — see LICENSE.