Dot

Plan in one AI tool. Build in another. Nothing gets lost.
Dot is the local-first plan & decision layer that makes your AI tools interoperable —
with a memory of your codebase underneath, and a decision log you can actually read.

---

Your AI tools don't talk to each other.

You plan a feature with Claude Code. The plan is good. Then you open VS Code to build it with Copilot - and Copilot has never heard of it. So you re-explain. Tomorrow, a fresh session, you re-explain again. Every tool now ships its own memory, but each one is a silo: what Claude learns, Copilot will never know.

Dot is the layer that carries your work across tools. A local daemon holds the active plan, the architectural decisions, and a ranked memory of your codebase - and every agent reads and writes the same store, through MCP, AGENTS.md, a VS Code extension, or one curl.

The flagship move: finish planning in Claude Code → the plan lands in Dot automatically (or via one dot_handoff call) → open any other tool and it starts building from that exact plan. No re-explaining. That's the whole point.

Local. Private. Model-agnostic. Open source. No code leaves your machine - embeddings are generated locally, storage is SQLite (+ ChromaDB) on disk.

What Dot gives you that per-tool memory can't

• Cross-tool plan handoff. A structured, durable "active plan" object that one tool writes and every other tool picks up. New plan supersedes old; the handoff survives restarts, sessions, and tool switches.
• A decision log you can read and commit. Native tool memories are opaque blobs. Dot renders yours as DECISIONS.md - what was decided, what was rejected, and why - diffable in git, reviewable in a PR.
• One memory, every agent. Claude Code, Copilot, Cursor, Codex, a CI agent, a curl one-liner - same context, same store, kept locally.
• A forgetting curve keeps it sharp. Memories decay with age but are reinforced on use, so what stays relevant survives and stale noise fades. Plans never decay.

Install

Requires Python 3.11+. Everything runs locally - no account, no API key, no cloud.

pip install dot-context            # local semantic embeddings via ONNX, no torch
dot --version

Want the full ML stack (sentence-transformers on torch, plus ChromaDB vector search)? Install the ml extra - same model weights, so no re-indexing needed:

pip install "dot-context[ml]"

For development, clone and install in editable mode:

git clone https://github.com/Aryan-MP/dot-context-engine.git
cd dot-context-engine && pip install -e ".[dev]"

How it works

Three layers make up the brain:

• dot-memory is the long-term memory. It mines architectural decisions from commit messages and AI conversations, stores them with a forgetting curve (stale memories decay, frequently used ones are reinforced), and lets any agent write new decisions back via the API. This is the part that makes Dot a second brain and not just a search index.
• dot-indexer is the working memory of your code. It chunks code by function/class (not fixed token windows), extracts docstrings, imports, and TODO/decided to… comments, and embeds everything locally.
• dot-context is recall. It assembles context ranked by semantic similarity, file proximity, recency, and edit frequency, fills a token budget greedily, and formats it for whichever agent is asking (Claude XML, concise Copilot, markdown, or raw JSON).

Quick start

cd your-project
dot init                          # index the project; wires git hooks + Claude Code (when detected)
dot daemon start                  # keep watching in the background

dot ask "how does auth middleware work?"
dot inject "refactoring the billing module" --fmt claude | pbcopy
dot status
dot dashboard                     # web UI at http://localhost:7337/ui

Your first 5 minutes

A quick health check before you wire Dot into every tool. From your project root:

dot init && dot daemon start
dot status                         # expect: files indexed > 0, daemon running
dot ask "where is X handled?"      # real files, even without exact keywords
dot memory add "Chose JWT over sessions for the stateless API"
dot memory list                    # your decision is captured

If dot ask returns the right files and dot memory list shows your decision, the core loop works. Now prove the shared part below.

Anything off? dot doctor checks Python, the ML stack, the port, git, and the daemon, and tells you exactly what to fix.

The handoff: plan in one tool, build in another

This is the flagship flow. Plan a feature in Claude Code - Dot captures the plan automatically as Claude works (a TodoWrite hook mirrors its live todo list), or Claude calls dot_handoff explicitly when planning is done. Then, from anywhere:

dot plan show           # the exact plan, verbatim - in a new terminal, tomorrow, any tool

Open VS Code and the extension's sidebar shows the active plan; #dotContext gives it to Copilot Chat. Cursor and Codex read it through MCP and AGENTS.md. No tool needed re-explaining. Handing off manually works from any shell too:

dot handoff --label "billing refactor" --file plan.md   # or pipe it in

A new plan supersedes the old one, plans never decay, and every tool reading from Dot sees the same one. That's the tool boundary crossed.

One memory, every agent

Decisions work the same way - what one agent learns, every agent knows:

# Monday - while pairing with Claude Code, a decision is recorded (by the agent, or you):
curl -X POST http://127.0.0.1:7337/memory -H 'content-type: application/json' \
  -d '{"content": "Chose Postgres advisory locks over Redis for job dedup, one less service to run", "kind": "decision"}'

# Tuesday - a different tool, a fresh session, asks the same question:
curl 'http://127.0.0.1:7337/context?query=how%20do%20we%20dedup%20jobs&fmt=raw'
# surfaces the advisory-locks decision, the reasoning, and the code around it.

And unlike per-tool auto-memory, the log is yours to read:

dot memory export --md    # writes DECISIONS.md - decisions, rejected alternatives,
                          # the active plan and its lineage. Commit it, diff it, review it.

What it looks like

(illustrations - run the Quick start above to see the real thing in under a minute)

dot status	dot dashboard	VS Code extension

New here? Read the story: Your AI tools have amnesia. I built them a shared memory.
Full walkthrough with experiments (terminal + VS Code): docs/getting-started.md
Deep technical internals: docs/internals.md
Prerequisites from zero: docs/foundations.md

CLI

command	what it does
dot init	initialize Dot (+ git hook, CLAUDE.md, AGENTS.md, Cursor/Claude MCP)
dot doctor	diagnose your setup - Python, ML stack, port, git, daemon health
dot handoff	hand off a plan for other tools to build from
dot plan show	print the active handoff plan
dot status	what Dot knows about the current project
dot ask "…"	query your codebase in natural language
dot inject [query]	print assembled context - pipe it anywhere
dot memory list/add/export/delete	browse and manage captured decisions
dot memory export --md	write the committable DECISIONS.md decision log
dot memory share/pull	share memories with your team via a committed file
dot capture	scan Claude Code transcripts for decisions (opt-in)
dot import [file]	import exported or team-shared memories
dot sync	force re-index
dot forget "pattern"	remove memories matching a pattern
dot mcp	run the MCP server (Claude Code wires this automatically)
dot dashboard	open the web UI
dot daemon run/start/stop/install-service	control the daemon (launchd/systemd)

REST API (localhost:7337)

GET  /status                 daemon health + project stats
GET  /context?query=&file=&fmt=claude|copilot|markdown|raw
POST /memory                 capture a decision        GET /memory   browse
POST /memory/conversation    extract decisions from an AI transcript
DELETE /memory/{id}          forget
GET  /graph                  dependency graph JSON
POST /ask                    natural-language codebase query
POST /sync                   force re-index

Integrations

Every integration is just another agent plugging into the same brain: read context, write decisions back.

• Claude Code - dot init adds a CLAUDE.md section, a SessionStart hook that injects context at the start of every session, MCP tools (dot_context, dot_remember, dot_handoff, dot_status), and a TodoWrite hook that mirrors Claude's live plan into Dot automatically.
• VS Code / Copilot - install Dot - AI Context Memory from the VS Code Marketplace. It shows the active plan and "what Dot knows about this file" in a sidebar, registers Dot as a Language Model tool for Copilot Chat (#dotContext), and offers one-click decision capture.
• Cursor - dot init registers the Dot MCP server in .cursor/mcp.json (auto-detected when .cursor/ exists, or --cursor).
• Codex / Windsurf / Aider / Zed / anything that reads AGENTS.md - dot init adds a Dot section to AGENTS.md teaching every agent to check the active plan, pull context, and record decisions.
• Anything else - curl localhost:7337/context?query=...&fmt=raw.

FAQ: why not just AGENTS.md + an MCP memory server?

Fair question - both exist and both are good. Dot uses both rather than competing with them: dot init writes your AGENTS.md section, and Dot speaks MCP. What the free baseline doesn't give you:

• A plan handoff object. AGENTS.md is static instructions; MCP memory servers store loose facts. Neither models "here is the plan, verbatim, supersede the old one, never let it decay, inject it into every tool until it's replaced."
• A curated, legible decision log. Auto-memories are model-written blobs you're told not to fully trust. DECISIONS.md is reviewable, diffable, committable.
• A product surface. The VS Code sidebar shows the plan and decisions for the file you're in; the daemon watches, indexes, decays, and dedupes continuously.

And tools like Graphify (codebase knowledge graphs) are complementary, not competing: they map your code; Dot carries your plans and decisions across tools.

Development

make install     # editable install with dev extras
make test        # pytest
make lint        # ruff
make dashboard   # build the web UI into dashboard/dist (served at /ui)
make extension   # compile the VS Code extension

Embeddings run in tiers: sentence-transformers (the [ml] extra) when installed, otherwise fastembed (a default dependency - ONNX, same model weights, no torch), otherwise a deterministic hashing embedder so the pipeline still works (and tests run) on any machine. ChromaDB and tree-sitter remain optional extras with SQLite brute-force search and heuristic parsing as fallbacks.

See docs/getting-started.md for the full walkthrough and test experiments, docs/internals.md for the complete technical deep dive (architecture, algorithms, math, and trade-offs), and docs/integrations.md for tool wiring.

Roadmap

Dot already works. The interesting part is where it is going:

• Agent Notebook. Today agents can write decisions back to Dot when asked. Next, they do it on their own: when an agent finishes a task or makes a call, Dot captures a summary and folds it into memory and into the instruction files each tool reads at startup. Your agents keep their own notes, and the next session begins already knowing.
• Memory graph. Right now memories are a flat, ranked list. Next they become a graph with typed links (supersedes, relates-to, caused-by), so Dot can answer not just what you decided but what replaced it, and why. Institutional memory you can trace.
• Hybrid retrieval. Shipped. Retrieval now fuses semantic search with BM25 keyword scoring (SQLite FTS5) via reciprocal-rank fusion, with a hard boost for exact symbol-name matches - looking up one specific function or flag is as reliable as asking a vague question.

Have a view on what matters most? Open an issue.

Contributing

We welcome bug reports, feature ideas, and pull requests. See CONTRIBUTING.md for guidelines.

License

MIT