Contextgit
Persistent memory layer for AI agent workflows
Ask AI about Contextgit
Powered by Claude Β· Grounded in docs
I know everything about Contextgit. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ContextGit
Every time you start a new session with an AI coding agent, it starts from zero. It doesn't know what was built yesterday, what decisions were made, or what's left to do. You spend the first 10 minutes of every session re-explaining your project. ContextGit fixes this β it gives your agents a persistent memory layer that survives across sessions, branches, and machines.
Install
npm install -g contextgit
cd your-project
contextgit init
Restart Claude Code (or any MCP client) after running
initfor the MCP server to take effect.
That's it. init registers the MCP server, updates CLAUDE.md with session instructions, and installs Claude Code hooks. Start a new session β the agent calls project_memory_load automatically and picks up exactly where the last session left off.
How it works
ContextGit stores structured context commits alongside your git history. Each commit captures what was done, what was decided, and what questions remain open.
Session 1: Agent builds auth module β saves context commit
Session 2: Agent loads snapshot β knows auth is done β starts on the next task
What the agent sees
When an agent calls project_memory_load, it gets a snapshot like this:
## Project State
Auth module complete. API routes tested. Database schema finalized.
## Current Branch: Context: main
Implementing payment integration. Stripe SDK configured.
## Recent Activity
- [2026-03-20T08:33:44Z] "Payment webhook handler done" by solo via claude-code
- [2026-03-20T07:15:22Z] "Stripe SDK integration" by solo via claude-code
- [2026-03-19T16:42:11Z] "Auth module complete" by solo via claude-code
## Open Threads
- [FREE] Need to add rate limiting to payment endpoints
- [CLAIMED by studio-mcp-agent] Build invoice PDF generation
- [FREE] Decide on webhook retry strategy
## Active Claims
- "Build invoice PDF generation" claimed by studio-mcp-agent (2h TTL)
The agent reads this and knows exactly where the project stands without you saying a word.
MCP tools
These tools are exposed to the agent via MCP. The agent calls them as part of its normal workflow.
| Tool | What it does |
|---|---|
project_memory_load | Load the full project snapshot β what was built, what's decided, open threads, active claims. Call at session start. |
project_memory_save | Save a context commit β what you did, decisions made, open questions. Call before ending a session. |
context_search | Semantic + full-text search over past context commits. |
project_task_claim | Claim a task so other agents skip it. Claims auto-expire after 2 hours. |
project_task_unclaim | Release a claimed task. |
project_memory_branch | Create a context branch for experimental work. |
project_memory_merge | Merge a context branch back into the parent. |
CLI commands
contextgit init # Initialize contextgit in current project
contextgit init --hooks # Initialize with git hooks
contextgit commit "message" # Write a context commit
contextgit status # Show current project state
contextgit search "query" # Search past commits
contextgit claim "task" # Claim a task
contextgit unclaim <id> # Release a claim
contextgit branch <name> # Create a context branch
contextgit merge <id> # Merge a context branch
contextgit serve # Start the REST API server
Architecture
Monorepo with strict dependency ordering:
packages/
core/ β Types, snapshot formatter, embedding service, context engine
store/ β Storage interface, LocalStore (SQLite), RemoteStore, SupabaseStore
mcp/ β MCP server (stdio transport, launched by Claude Code)
cli/ β CLI commands (oclif)
api/ β REST API (Express)
Local storage: SQLite via better-sqlite3. One DB per project at ~/.contextgit/projects/<id>.db.
Remote storage: Optional Supabase (Postgres + pgvector) for cross-machine sync and team use.
Embeddings: Local all-MiniLM-L6-v2 (384 dimensions, no API key needed) for semantic search.
Configuration
Project config lives at .contextgit/config.json:
{
"project": "my-project",
"projectId": "unique-id",
"store": "local",
"agentRole": "solo",
"workflowType": "interactive",
"autoSnapshot": false,
"snapshotInterval": 10,
"embeddingModel": "local"
}
Current status
This is an early-stage tool. It works for solo developers using Claude Code across one or more machines. The core memory layer is solid β context commits, branches, threads, search, and snapshots all work.
Known limitations
- No automatic context merge when git branches are merged (manual
project_memory_mergerequired) - No integration with external boards (Linear, Jira, GitHub Issues)
- Semantic search requires the embedding model to download on first use (~23MB)
License
MIT
