autoctxd

Persistent, local memory for Claude Code.

Every Claude Code session starts from scratch. You re-explain your project, re-state decisions you already made, re-describe what you were in the middle of. autoctxd fixes that — silently, locally, with zero API cost.

• 100% local, zero API cost — pure heuristics, no LLM calls, nothing leaves your machine
• Captures every tool use automatically through Claude Code hooks
• Injects the right ~600 tokens of context into each new session
• Tracks architectural decisions separately — they never get forgotten
• Detects work patterns across sessions
• Active Guard — flags actions that contradict past decisions, before you make them

Why autoctxd?

| | autoctxd | Mem0 / memori (cloud) | Plain CLAUDE.md | |---|---|---|---| | Where your code context lives | Your disk | Their servers | A static file you maintain | | Cost per session | $0 | API calls billed | $0 | | Captures automatically | Yes (hooks) | Via SDK calls | No — you write it | | Active recall during reasoning | Yes (7 MCP tools) | Yes | No | | Flags decision contradictions | Yes (Active Guard) | No | No | | Works offline | Yes | No | Yes | | Cross-session patterns / hotspots | Yes | Limited | No | | Setup | One command | Account + API key | Edit a file |

Built specifically for the Claude Code workflow — hooks, MCP, and a local dashboard, not a generic SDK you bolt onto something.

How it works

  Session 1                                  Session 2 (days later)
  ─────────                                  ─────────────────────
  You work on auth refactor    ───┐          ┌──► Claude already knows:
  Claude uses Edit/Write/Bash     │          │    • "Migrated from jwt to iron-session"
                                  ▼          │    • Hot files: auth/session.ts
                            ┌──────────┐     │    • Last session left the login route
                            │ SQLite   │     │      half-wired (blocked)
                            │ LanceDB  │─────┘
                            └──────────┘     no re-explaining needed

Two integration modes, use either or both:

1. Passive (hooks, Claude Code only) — injects context at session start.

| Hook | What it does | |---|---| | PreToolUse | Builds context block from past sessions and injects it | | PostToolUse | Classifies and stores each tool use as an observation | | Stop | Compresses the session, extracts decisions, detects patterns, generates embeddings |

2. Active (MCP server, works everywhere) — Claude/Cursor/Windsurf/Cline query memory during reasoning via 7 tools:

| Tool | What it enables | |---|---| | recall_decisions | Look up past architectural decisions for a project | | recall_unfinished | Surface blockers from past sessions | | search_memory | Semantic + FTS search across all your coding memory | | get_project_history | Recent session summaries | | check_intent | Active Guard — flags actions that contradict past decisions | | record_feedback | Learns from "useful/irrelevant/wrong" signals | | record_decision | Persists decisions made in-conversation (never forgotten) |

See docs/INTEGRATIONS.md for setup in each editor.

Nothing leaves your machine.

Install

One-command install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex

That's it — installs Bun if missing, clones the repo into ~/.claude/autoctxd, installs deps, initializes the DB, and registers the three hooks in your existing settings.json (preserving anything already there).

Verify with autoctxd doctor. Uninstall cleanly with bun run scripts/uninstall-hooks.ts.

From npm

npm install -g autoctxd

Requires Bun on your PATH. If you don't have Bun, autoctxd will print install instructions on first run, or use the one-command installer above which handles Bun for you.

Manual install

If you prefer step-by-step, requires Bun and Claude Code:

cd ~/.claude
git clone https://github.com/autoctxd/autoctxd.git
cd autoctxd
bun install
bun run src/cli/index.ts init
bun run scripts/install-hooks.ts   # merges hooks into settings.json
bun run src/cli/index.ts doctor    # verify

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "bun run ~/.claude/autoctxd/src/hooks/pre-tool-use.ts"
      }]
    }],
    "PostToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "bun run ~/.claude/autoctxd/src/hooks/post-tool-use.ts"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "bun run ~/.claude/autoctxd/src/hooks/stop.ts"
      }]
    }]
  }
}

Restart Claude Code. The next session starts collecting. The one after that starts getting context.

CLI

# What has autoctxd learned about you?
bun run src/cli/index.ts stats

# Every decision you've made across projects
bun run src/cli/index.ts decisions

# Hybrid search (semantic + full-text) across everything
bun run src/cli/index.ts search "race condition async"

# Drill into one session
bun run src/cli/index.ts show session <session-id>

# Patterns detected in your workflow
bun run src/cli/index.ts patterns

# Export a project's memory to markdown
bun run src/cli/index.ts export ./my-app > context.md

# Re-run the classifier on old observations (after classifier improvements)
bun run src/cli/index.ts reclassify

# Token accounting: what autoctxd has saved you
bun run src/cli/index.ts metrics

# Launch the local web dashboard
bun run src/cli/index.ts dashboard
# → http://localhost:4589

# Health check your install
bun run src/cli/index.ts doctor

Dashboard

Running autoctxd dashboard launches a local web UI at http://localhost:4589:

• Metric cards: sessions, observations, decisions, projects, context hit rate, avg explore calls, tokens saved
• Activity timeline of every observation across all projects
• Architectural decision feed with alternatives and rationale
• Decision chains — automatically detected sequences like mysql → postgres → sqlite across sessions
• Pattern panel (tool preferences, work focus, hotspots, TDD vs fix-first, peak coding hours)
• Hybrid search (semantic + full-text) with project filter

Everything read-only, everything local. No accounts, no network.

Debug mode

Set AUTOCTXD_DEBUG=1 to log every hook invocation to data/debug.log:

AUTOCTXD_DEBUG=1 claude  # then tail data/debug.log

You'll see what was injected, why, and timings.

What gets captured

Each PostToolUse becomes an observation, classified as one of:

bug_fix · refactor · new_feature · config · research · test · decision · blocked · deploy · other

The classifier is pure heuristics. Scores each observation 0–10 for importance. Critical files (auth, payment, migration, schema) get boosted. Docs/readmes get demoted.

Decisions are first-class. Every bun add, npm install, cargo add becomes a stack decision. Every "switched from X to Y" becomes an architectural decision. These never get compressed away.

Patterns emerge after 3+ sessions in the same project: tool preferences, work-type focus, file hotspots, TDD vs. fix-first workflows, peak coding hours.

What gets injected

At session start, autoctxd assembles a context block from:

• Architectural decisions on this project (all of them, always)
• Recent session highlights (top 3 sessions by recency)
• Semantically similar past sessions (cross-project if relevant)
• Hot files (modified 3+ times recently)
• Your patterns in this project

Format is compact — targets ~600-800 tokens so it doesn't crowd your context window.

Privacy

Everything stays in ~/.claude/autoctxd/data/. Delete the folder to wipe all memory. No telemetry, no cloud, no network calls during operation.

For sensitive projects, drop a .autoctxd-ignore file at the project root. Patterns follow a .gitignore-style subset — a single * opts the whole project out. See SECURITY.md for the full threat model and the list of what does/doesn't get persisted.

Embedding providers

Pick the right trade-off for your machine and threat model. TF-IDF is the default — zero install pain, deterministic, fast. Upgrade when you want richer retrieval.

| Provider | Dim | Latency | Discrimination | Setup | |---|---:|---:|---:|---| | tfidf (default) | 128 | 0.1 ms | gap 0.170, 92% wins | nothing — built in | | minilm | 384 | 4.5 ms | gap 0.621, 100% wins | autoctxd embeddings switch minilm --yes (~25MB model download on first use) | | ollama | 768 | varies | run bun run benchmark:embeddings on your box | Requires Ollama running locally with ollama pull nomic-embed-text |

Numbers from scripts/benchmark-embeddings.ts over 12 dev-text pairs (anchor / paraphrase / unrelated). "Wins" is the share of pairs where the model puts the paraphrase closer to the anchor than the unrelated text. Higher = better.

# What's active and what's available?
autoctxd embeddings list
autoctxd embeddings status

# Switch — re-embeds everything you've stored, automatically
autoctxd embeddings switch minilm --yes

# Or pin via env (no persistence)
AUTOCTXD_EMBEDDING=minilm autoctxd ...

The cache is partitioned by provider, so switching back is cheap. @xenova/transformers is an optionalDependency — if bun install fails to fetch it, MiniLM is just unavailable and TF-IDF keeps working.

Stack

| Component | Tech | |---|---| | Runtime | Bun | | Structured DB | SQLite + FTS5 (full-text search) | | Vector DB | LanceDB (dim adapts to active provider) | | Embeddings | TF-IDF (default) · MiniLM-L6-v2 via transformers.js · Ollama (any embedding model) | | Classification | Keyword + tool/file heuristics |

Roadmap

• [x] Local web dashboard
• [x] Decision chains across sessions
• [x] Token savings metrics
• [x] One-command installer for all platforms
• [x] Health-check doctor
• [x] Integration test suite
• [x] MCP server mode — Claude queries memory actively, not just at session start
• [x] Active Guard — flags actions that contradict past decisions
• [x] Feedback loop — system learns what's useful to each user
• [x] Multi-editor — Cursor, Windsurf, Cline, Claude Desktop, Claude Code
• [x] Pluggable embeddings — TF-IDF default, MiniLM and Ollama opt-in
• [x] .autoctxd-ignore — gitignore-style opt-out for sensitive projects
• [ ] Codebase awareness — integrate git blame + AST analysis
• [ ] Predictive context — surface what you'll need next based on patterns

Testing

bun test                           # 75 tests, isolated temp DB
bun run benchmark:embeddings       # cross-provider quality + latency
bun run typecheck                  # tsc --noEmit

Coverage spans the classifier, compressor, decision extractor, decision chains, ignore matcher, embedding providers, and an end-to-end integration flow. Tests never touch your real memory.

License

MIT.