aidimag

AI Dimag — Verified Memory for AI Coding Agents

Your coding agent forgets your codebase. AIDimag doesn't.

Documentation • Why AIDimag? • Getting Started • Use Cases • Benchmarks • AI Dimag Cloud • Pricing

What is AI Dimag?

AI Dimag is a memory system for software engineering — not a general-purpose "AI memory" app. It gives any MCP-compatible agent (Claude, Cursor, Copilot, Windsurf…) a persistent memory of your codebase that survives across sessions — decisions, conventions, gotchas, failed approaches, guardrails, and reusable skills — stored as falsifiable claims with grounding evidence in .aidimag/ next to your code.

The subject of memory is your repository, not your preferences or chat history. Every capability — evidence, git-hook verification, guardrails, pre-commit checks, path-scoped recall, session scratchpad — exists to serve day-to-day development work.

🎯 The Difference: Claim-and-Verify, Not Store-and-Retrieve

Most memory systems store text and retrieve whatever is similar later — a stored fact is assumed true forever. That's dangerous in a codebase, where a confidently-retrieved stale fact is worse than no memory at all.

Every AI Dimag memory carries evidence (a shell check, an anchored commit, a test) that dim verify re-runs against the current repo — automatically, via git hooks, on every pull, checkout, and rebase. Beliefs that stop being true go STALE instead of silently misleading your AI.

✨ Works with Every AI Tool

• MCP tools (Claude, Cursor, etc.) get real-time memory via the MCP server
• Non-MCP tools (Copilot, Windsurf, etc.) get static context files (.cursorrules, CLAUDE.md, AGENTS.md, etc.)

Install

npm install -g aidimag

Requires Node 22+. Ships two equivalent binaries: dim (short) and aidimag.

🚀 Quick Start

cd your-repo
dim init                    # creates .aidimag/, installs additive git hooks
dim bootstrap               # optional: LLM-survey the repo into a starter memory set
dim review                  # approve what enters memory (nothing is stored unreviewed)

dim remember "All DB access goes through src/db/store.ts" -k INVARIANT -p src/db \
  -e "STATIC_CHECK:grep -rL better-sqlite3 src --include=*.ts"
dim recall db access
dim verify                  # re-run all evidence; stale beliefs get flagged
dim brief                   # session-start briefing: in-scope memory, guardrails, gaps

# For non-MCP tools (Copilot, Cursor without MCP, etc.):
dim generate-context --format all --auto   # creates .cursorrules, CLAUDE.md, AGENTS.md, etc.

🔌 Connect to Your AI Agent (MCP)

Add to your agent config (e.g. .mcp.json for Claude Code):

{
  "mcpServers": {
    "aidimag": {
      "command": "npx",
      "args": ["-y", "aidimag", "mcp"],
      "env": { "AIDIMAG_REPO": "/path/to/your/repo" }
    }
  }
}

MCP Tools get memory_search, memory_propose, context_note (live in-chat fact capture), chat_harvest (live, tool-agnostic session harvesting with server-side secret redaction), memory_critique (a second critic grounded in verified memory), session-start briefings, session-end extraction, and more.

Non-MCP Tools: dim generate-context -f all renders verified memory into .cursorrules, CLAUDE.md, AGENTS.md, .windsurfrules, and .github/copilot-instructions.md (--auto keeps them refreshed).

Hermes Agent: dim hermes install registers aidimag as a native Hermes memory provider — one command, no pip, no venv. A single stdlib-only Python bridge delegates to the MCP server: session briefings are injected into the system prompt, recall is prefetched per turn, and session learnings become review-queue proposals (never silent writes). Then: hermes config set memory.provider aidimag.

✨ Key Features

🛡️ Human-Gated Capture

Commits, PRs, AI-chat transcripts (Claude Code, Codex, Copilot, Cursor), and pasted docs are mined into proposals. Nothing enters memory until you approve it in dim review (auto-triaged best-first, approve all --min-score 0.7 for batches).

✅ Verification Lifecycle

STATIC_CHECK / COMMIT_REF / TEST_RESULT / EXEC_TRACE / HUMAN_ATTESTED evidence. Failing evidence flips memories to STALE and auto-drafts a recovery proposal. Confidence decays without re-confirmation.

🔒 Evidence Trust Gate

Shell-command evidence that arrives via team sync is never executed until you inspect and approve it (dim verify --trust).

🔍 Hybrid Semantic Recall

FTS5 keyword + vector KNN (OpenAI, local Ollama, or AWS Bedrock; auto-detected except Bedrock, which is explicit opt-in; works keyword-only with none).

🚦 Guardrails & Skills

Behavioral rules (never / ask-first / always) and step-by-step procedures, enforced by dim check (pre-commit) and memory_critique.

👥 Team Mode, Self-Hosted

dim serve + dim sync: local-first replicas, device-code login, brain-scoped API keys, hashed credentials, cross-machine verification consensus.

📚 Knowledgebase Inbox

Drop design docs / ADRs / PDFs / DOCX into knowledge/ and they're summarized into reviewed, pinned memories.

📝 Scratchpad & Provenance Audit

dim scratch (and the scratchpad_* MCP tools) hold short-term session notes — TTL-expiring, never synced, never durable memory. dim audit lists memories resting on the weakest ground (agent-authored, evidence-free, stale, or long-unverified) so you can fix them up like a dependency audit for your repo's knowledge.

🎨 Web Dashboard & Extensions

dim ui — run checks, session briefings, bootstrap, harvest, and context generation from the browser — plus VS Code and IntelliJ extensions.

🥊 How It Compares

AI Dimag follows a claim-and-verify model; other memory systems follow store-and-retrieve. The short version:

	Conversational memory layers	Vector-store memory plugins	Hand-maintained context files	AI Dimag
Built for	Chat assistants remembering users	General recall over embedded text	Static instructions for coding agents	Coding agents in a living repo
Unit of memory	Extracted facts / chat summaries	Embedded text chunks	Prose	Falsifiable, typed claims with evidence
How memory gets in	Automatic capture	Automatic embedding	Manual edits	Human-gated review queue
When the code changes	Nothing — stored facts stay "true"	Nothing	File silently rots	Evidence re-runs via git hooks; broken claims flip STALE
Trust model	Write-time label, never re-checked	Similarity ≈ trust	"It's in the file"	Verification status + decaying confidence; trust-ranked retrieval
Enforcement	None — injection only	None	Hope the model reads it	Guardrails + pre-commit dim check + memory_critique
Failure mode	Confidently recalls outdated facts	Retrieves similar, true or not	Instructions drift from reality	Says "this went STALE" instead of guessing

Full comparison: aidimag.com/comparison

vs. named tools

How aiDimag relates to the memory tools people usually ask about. These solve a different problem (remembering users and conversations); aiDimag remembers your repository and proves its memories are still true:

	aiDimag	Mnemosyne	mem0	Letta	Honcho	SuperMemory	Hindsight	ChromaDB
Subject of memory	Your codebase	Chat/agent sessions	User & agent facts	Agent's own context	User/peer reasoning	Personal + agent	Agent memory	— (vector DB)
Local-first	✅ SQLite per repo	✅ SQLite	⚠️ Hybrid	❌ Docker+PG	⚠️ PG+worker	❌ SaaS	✅ SQLite	✅ Embedded
MCP server	✅ Built-in	✅	❌	❌	❌	✅	✅	❌
Verifies memories against code	✅ Evidence re-runs via git hooks	❌	❌	❌	❌	❌	❌	❌
Human-gated writes	✅ Review queue	❌ Auto-capture	❌ Auto	❌	❌	❌	❌	—
Enforcement	✅ Guardrails + pre-commit + critique	❌	❌	❌	❌	❌	❌	❌
Open source	✅ MIT	✅ MIT	✅ Apache 2.0	✅ Apache 2.0	⚠️ AGPL	❌ Proprietary	✅ MIT	✅ Apache 2.0
Published benchmark	Own suite: 100% staleness detection, 0% FP	BEAM 65.2% / LongMemEval 98.9% R@All@5 (self-reported)	LoCoMo	LoCoMo 83.2%	LongMemEval 90.4%	MemoryBench 85.2%	BEAM 73.4% / LongMemEval 94.6%	—

Chat-memory benchmarks (LoCoMo, LongMemEval, BEAM) score recall over conversation histories, so they don't apply to aiDimag — its memory subject is the repo. Instead aiDimag publishes its own reproducible suite (below), including the metric none of the chat benchmarks measure: does memory notice when the code changes?

📊 Benchmarks

Reproducible performance and quality suites live in benchmark/ (npm run bench, npm run bench:quality). Headline results (Apple M4, Node 24, 10,000-memory brain — full tables at aidimag.com/benchmarks):

Metric	Result
FTS keyword search	1.45ms p50
Vector KNN (768-dim, sqlite-vec)	4.15ms p50
Memory writes (transactional, incl. FTS + event log)	~5,400/s
CLI cold start (dim --help)	~41ms p50
Staleness detection (broken claims → STALE, real git fixture)	100% (4/4)
False positives (intact claims wrongly flagged)	0% (0/4)
Retrieval, keyword queries (Recall@1 / MRR, FTS-only)	1.00 / 1.00
Retrieval, paraphrase queries (FTS-only; hybrid closes this gap)	0.25 / 0.27

📖 Documentation

Getting Started Installation Quick Start (5 min) Cloud Sync

Overview Why AIDimag? Use Cases How it Works Comparison CLI Reference MCP Integration Configuration

Guides Team Sync Guardrails Context Files

Full documentation: aidimag.com

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for dev setup, project principles, and the PR checklist. All participation is governed by our Code of Conduct.

💰 License & Pricing

AI Dimag is open source under the MIT License — free for everyone, any team size, forever. Use it, fork it, embed it.

The entire local-first product is free: CLI, MCP server, verification, guardrails, skills, IDE extensions, local dashboard, and self-hosted team sync (dim serve).

Want team sync without running a server? AI Dimag Cloud is an optional managed sync subscription — that's how the project stays funded and open source. See Pricing.

Built by Anup Khanal

Website • Documentation • Cloud • npm • License