ctxmemory 0.1.0

Persistent memory for AI coding agents

ContextKit

Persistent memory for AI coding agents. Stop re-explaining your codebase every session.

AI coding agents such as Claude Code, Codex, Cursor, and Copilot reset completely between sessions. You lose time re-explaining architecture, conventions, forbidden patterns, and past bugs. ContextKit gives your repo a shared, evolving project brain.

How it works

1. ctx init sets up a .ctx/ brain in your repo.
2. ctx add adds memories manually, or ctx watch extracts them automatically.
3. ctx inject claude generates a fresh agent instruction file.
4. Every new session starts with project-specific context.

Install

pip install ctxmemory

Quickstart

cd your-project
pip install ctxmemory
ctx init
ctx add "We use Zod for all validation. Never use Yup." --type pattern
ctx add "Never mutate state directly - always use the store actions." --type forbidden
ctx inject claude

Commands

Command	Description	Key options
ctx init	Create .ctx/, markdown files, and the SQLite index	None
ctx add <content>	Add a memory manually	--type, --tags
ctx list	List stored memories	--type, --tags, --limit
ctx remove <id>	Remove a memory by partial id	None
ctx inject <agent>	Generate an agent-specific context file	--task, --file, --force
ctx watch	Extract memory candidates from recent activity	--since
ctx status	Show totals, recent memories, and generated files	None
ctx search <query>	Search memories by content and tags	--limit
ctx export	Export all memories as markdown or JSON	--format, --output

Supported agents

Agent	File generated
Claude Code	CLAUDE.md
Codex	AGENTS.md
Cursor	.cursor/rules
GitHub Copilot	.github/copilot-instructions.md
OpenCode	AGENTS.md

Project brain layout

.ctx/
  brain.db
  decisions.md
  patterns.md
  forbidden.md
  bugs.md
  context.md
  .gitignore

The markdown files are the source of truth. The SQLite database is a fast index for lookup and relevance.

Auto-extraction (ctx watch)

ctx watch uses the Anthropic API to review recent git activity, Claude session logs, or a manual session summary and suggest memories to add to your project brain.

Set ANTHROPIC_API_KEY before using automatic extraction:

export ANTHROPIC_API_KEY=sk-ant-...

ContextKit resolves configuration in this order:

1. ANTHROPIC_API_KEY
2. .env in the project root
3. ~/.contextkit/config.toml

Example global config:

[anthropic]
api_key = "sk-ant-..."

[watch]
default_since_minutes = 60
auto_approve_threshold = 0.9

[inject]
max_memories = 20

Typical workflow

pip install ctxmemory
ctx init
ctx add "We use FastAPI, not Flask. Never suggest Flask." --type forbidden --tags "framework"
ctx add "All API responses use APIResponse in core/response.py." --type pattern --tags "api,response"
ctx inject codex
ctx status
ctx search auth
ctx watch --since 480

License

MIT

Author

Built by Anas Nafees
LinkedIn: https://www.linkedin.com/in/anas-nafees/

Package name note

The product name is ContextKit, but the PyPI distribution name is ctxmemory because contextkit is already taken on PyPI. The installed CLI command remains:

ctx