Metadata-Version: 2.4
Name: dot-context
Version: 0.1.0
Summary: Dot - plan in one AI tool, build in another. A local-first plan & decision layer that makes your AI tools interoperable, with a shared codebase memory underneath.
Author: Dot Contributors
License: MIT
Project-URL: Homepage, https://github.com/Aryan-MP/dot-context-engine
Keywords: ai,context,memory,daemon,copilot,claude,embeddings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: watchdog>=4.0
Requires-Dist: GitPython>=3.1
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: APScheduler>=3.10
Requires-Dist: pydantic>=2.6
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.7
Requires-Dist: fastembed>=0.3
Provides-Extra: ml
Requires-Dist: chromadb>=0.5; extra == "ml"
Requires-Dist: sentence-transformers>=2.7; extra == "ml"
Provides-Extra: treesitter
Requires-Dist: tree-sitter>=0.21; extra == "treesitter"
Requires-Dist: tree-sitter-language-pack>=0.4; extra == "treesitter"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Provides-Extra: all
Requires-Dist: dot-context[dev,ml,treesitter]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="branding/app-icon.png" width="96" alt="Dot">
</p>

<h1 align="center">Dot</h1>

<p align="center">
  <strong>Plan in one AI tool. Build in another. Nothing gets lost.</strong><br>
  Dot is the local-first plan &amp; decision layer that makes your AI tools interoperable —<br>
  with a memory of your codebase underneath, and a decision log you can actually read.
</p>

<p align="center">
  <a href="https://pypi.org/project/dot-context/"><img src="https://img.shields.io/pypi/v/dot-context?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://github.com/Aryan-MP/dot-context-engine/releases"><img src="https://img.shields.io/github/v/release/Aryan-MP/dot-context-engine?include_prereleases&label=release" alt="Release"></a>
  <a href="https://marketplace.visualstudio.com/items?itemName=AryanMangod.dot-context-memory"><img src="https://img.shields.io/visual-studio-marketplace/v/AryanMangod.dot-context-memory?label=VS%20Code%20extension" alt="VS Code Marketplace"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/Aryan-MP/dot-context-engine/actions/workflows/ci.yml"><img src="https://github.com/Aryan-MP/dot-context-engine/actions/workflows/ci.yml/badge.svg" alt="Tests"></a>
</p>

---

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

```bash
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:

```bash
pip install "dot-context[ml]"
```

For development, clone and install in editable mode:

```bash
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

```bash
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:

```bash
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*:

```bash
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:

```bash
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:

```bash
# 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"}'
```

```bash
# 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*:

```bash
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 |
|---|---|---|
| ![CLI status](docs/assets/screenshots/screenshot-cli.png) | ![Dashboard](docs/assets/screenshots/screenshot-dashboard.png) | ![Extension](docs/assets/screenshots/screenshot-extension.png) |


New here? Read the story: [Your AI tools have amnesia. I built them a shared memory.](https://medium.com/@aryanmp2003/your-ai-tools-have-amnesia-i-built-them-a-shared-memory-5ed617e89bc8)  
Full walkthrough with experiments (terminal + VS Code): [docs/getting-started.md](docs/getting-started.md)  
Deep technical internals: [docs/internals.md](docs/internals.md)  
Prerequisites from zero: [docs/foundations.md](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](https://marketplace.visualstudio.com/items?itemName=AryanMangod.dot-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

```bash
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](docs/getting-started.md) for the full
walkthrough and test experiments, [docs/internals.md](docs/internals.md)
for the complete technical deep dive (architecture, algorithms, math, and
trade-offs), and [docs/integrations.md](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](https://github.com/Aryan-MP/dot-context-engine/issues).

## Contributing

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

## License

MIT
