ctxmem gives your project a permanent, searchable memory that lives inside the repo. AI agents (and you) store decisions and recall relevant context on demand, so nothing is forgotten when a chat exceeds the model's context window.

• 🧠 Remembers — decisions, notes, sessions + your code, in a searchable index.
• 🔎 Self-checking — ctxmem ask tells the agent whether memory already knows (HIT / WEAK / MISS) before it answers.
• ♻️ Self-correcting — supersede an outdated decision (--supersedes); recall demotes and flags it (⚠ SUPERSEDED / ⚠ STALE).
• 🤝 Shareable — the memory is a text file committed to git. Commit, your colleague pulls, they get your exact context. Branch-aware for free.
• 📦 Works as a git package — pip install git+https://…, zero required deps.
• 🔒 Fully local — SQLite files in your repo. No cloud, no API keys, no servers.
• 🔍 Search modes — keyword (built-in, default) plus semantic / hybrid (local embeddings, no cloud).

How it works, in one line: a committed, human-readable memory.jsonl is the source of truth; a local, gitignored SQLite index makes it (and your code) instantly searchable. For the full design, see docs/ARCHITECTURE.md.

Install

pip install "git+https://github.com/DoppiaG93/ctxmem.git"   # as a git package
# or, from a clone:  pip install -e .

# optional extras
pip install "ctxmem[mcp]"        # AI-agent server (MCP)
pip install "ctxmem[semantic]"   # semantic search (needs Ollama too)
pip install "ctxmem[all]"        # everything

Requires Python 3.8+ with FTS5 (bundled in virtually every sqlite3 build). The base install has zero third-party dependencies.

Quick start

cd your-project

ctxmem init                                   # creates .ctxmem/
ctxmem hook install                           # auto-sync the index on every commit
ctxmem remember --type decision \
  --title "Auth via JWT" --tags auth,security \
  "We chose stateless JWT over server sessions for horizontal scaling."

ctxmem sync                                   # index memory + your code
ctxmem ask "how do we handle authentication"      # verdict: HIT / WEAK / MISS
ctxmem recall "how do we handle authentication"   # ask in plain language
ctxmem recall "cart" --type symbol            # search only code symbols

Then commit the memory so it's shared:

git add .ctxmem/memory.jsonl .ctxmem/config.json
git commit -m "chore: seed project memory"

Your colleague just git pulls and runs ctxmem recall — the index rebuilds itself from memory.jsonl. For the full onboarding story (agent wiring, handing memory to a teammate), see docs/GUIDE.md.

Commands

Use it from an AI agent

Wire an agent (Codex, GitHub Copilot) to the memory in one command:

ctxmem agent-init --agent all        # write the memory protocol into AGENTS.md + copilot-instructions.md
ctxmem agent-init --agent all --mcp  # also drop a .vscode/mcp.json (MCP server)

This injects a Project Memory Protocol that tells the agent to recall before a task, remember decisions, and sync after changing code — so the memory grows by itself. Full details (CLI vs MCP, requirements, tips) in docs/GUIDE.md → Use it from an AI agent.

Semantic search (Ollama)

Keyword mode is the stable, zero-setup default. Optional semantic and hybrid modes match by meaning using a fully-local embedding model:

pip install "ctxmem[semantic]"
# Option A: install Ollama on the host, then:
ollama pull nomic-embed-text
ctxmem mode semantic
ctxmem doctor                        # verify the whole chain end to end

# Option B: run Ollama in an isolated Lima VM:
cd ollama && task enable             # brings the VM up + switches to semantic

If the backend isn't available, ctxmem automatically falls back to keyword. Setup options, the Lima VM, and ctxmem doctor output are documented in docs/GUIDE.md → Semantic backend.

Why it saves tokens

Instead of pasting whole files into the model, you inject only the relevant recall snippets. Measured on the Django source tree:

Full methodology and reproducible steps: docs/ARCHITECTURE.md → Benchmark.

Documentation

• docs/ARCHITECTURE.md — the problem, the data model, the retrieval pipeline, project structure, search-mode internals, and the benchmark.
• docs/GUIDE.md — full walkthrough, team sharing, the git hook, AI-agent integration (CLI + MCP), and the semantic/Ollama backend.

FAQ

Is my data sent anywhere? No. Everything is local: SQLite files in your repo and, if you enable semantic mode, a local Ollama.

Do I have to use embeddings? No. keyword mode needs nothing and is the default. Semantic is opt-in.

Should I commit index.db? No — it's derived and gitignored. Commit memory.jsonl and config.json.

What if a teammate doesn't have Ollama? ctxmem falls back to keyword automatically; the shared memory still works.

Does it scale to a big repo? Yes. The keyword index is fine for large repos, and semantic mode is incremental — embeddings are cached by content hash (.ctxmem/emb_cache.db), so a sync only re-embeds new or changed text.

Is MCP proprietary? No. MCP is an open protocol with MIT-licensed SDKs; the server runs locally and reads only your repo.

Contributing

Contributions are currently invite-only. The project is developed by a small set of invited collaborators, so unsolicited pull requests are not accepted right now — but bug reports and feature requests are always welcome via GitHub issues. To contribute code, reach out to @DoppiaG93 to be added as a collaborator.

Invited collaborators follow the Git Flow branching model; see the Contributing guide for branch naming, commit conventions, and the release process. Please also review our Code of Conduct. To report a security issue, follow the Security Policy.

License

Released under the MIT License.