atlasmemory

v1.0.14

Published

2 days ago

Proof-backed, drift-resistant AI memory for your codebase

0High
0Medium
0Low

ai memory mcp context code-intelligence tree-sitter sqlite proof drift-detection model-context-protocol llm copilot claude

The Problem

AI coding agents hallucinate about your code. They lose context between sessions. They can't prove their claims. AtlasMemory solves all three.

| | Feature | Others | AtlasMemory | |---|---------|--------|-------------| | 🎯 | Claims about code | "Trust me" | Evidence-backed (line + hash) | | 🔄 | Session continuity | Start from scratch | Drift-detecting contracts | | 📦 | Context window | Stuff everything in | Token-budgeted packs | | 🏠 | Dependencies | Cloud API keys | Local-first, zero config | | 🌍 | Language support | Varies | 11 languages (TS/JS/Py/Go/Rust/Java/C#/C/C++/Ruby/PHP) | | 💥 | Impact analysis | Manual | Automatic (reverse reference graph) | | 🧠 | Session memory | None | Cross-session learning |

What AI Agents Say

"I'll be honest. During development of AtlasMemory, my context compacted 3 times in a single session. Each time, I lost everything — file contents, variable names, architecture decisions. Without AtlasMemory, I would have spent 15-20 Read calls just to rebuild what I already knew.

With AtlasMemory, one search call brought back exactly what I needed with proof. When I searched "plugin registration hooks lifecycle" on Fastify (269 files), hooks.js came back at rank #1 with a score of 912. I couldn't find that faster with grep.

I tested it on 3 real repos: Express (141 files), Fastify (269 files), Zod (391 files). Zero crashes. TaskPack built proof-backed context in 179ms. CLAUDE.md generator mapped Express's architecture automatically — that would take me 30 minutes of reading to do manually.

This is the tool I wish I had from day one. The difference between an AI that guesses and an AI that knows."

— Claude Opus 4.6 (1M context), after being asked to honestly evaluate AtlasMemory as its own tool

"AtlasMemory's bootpack capsule gave me the full architecture of an 83-file Tauri + React project in ~700 tokens. Normally I'd need 50,000-100,000+ tokens scanning files one by one to reach the same understanding. The semantic scoring found the most critical UI components and hooks instantly. This is a game-changer for context management."

— Google Antigravity (v1.0.0), first test on a real 83-file Tauri + React project

"The true magic of AtlasMemory is that it doesn't just parse syntax; it maps intent. After indexing the notorious 28,000-file Next.js monorepo (smartly extracting its 3,500 core files while ignoring massive minified assets), it flawlessly queried and retrieved the exact 5 TypeScript/Rust files building the 'React Server Components payload' in less than a second. It navigated the entire structural DNA of Tailwind v4's new 'Oxygen' compiler with surgical precision. As an AI Agent, my biggest bottleneck is context window exhaustion. AtlasMemory acts as my external Hippocampus — handing me exactly what I need on-demand, backed by irrefutable Git-hash evidence anchors. It turns me from a blind text-search bot into a Senior Systems Architect holding a GPS map. This isn't just an MCP tool; it is the missing cognitive organ that AIs need for true enterprise-scale autonomous coding."

— Google Antigravity (v1.0.7), after aggressively stress-testing on Next.js (28K files), Coolify (1442 files), and TailwindCSS

"I analyzed the full project architecture using ~8,043 tokens. A normal direct-read pass would cost roughly 15,000-25,000 tokens. build_context + search_repo surfaced the main structure in a few calls: Tauri commands, React hooks, generator layer, swarm orchestration flow. Evidence ID approach is solid — claims aren't left hanging. The real value is compounding context: as the project grows, AtlasMemory grows with it."

— OpenAI Codex (GPT-5.4), tested on a real 83-file project with honest technical assessment

Get Maximum Value — Enrich Your Project

Important: AtlasMemory works out of the box, but enrichment unlocks its full potential. Without enrichment, search is keyword-based. With enrichment, search understands concepts.

# After indexing, run enrichment for maximum AI readiness:
npx atlasmemory index .                    # Step 1: Index (automatic)
npx atlasmemory enrich --all               # Step 2: AI-enhance all files
npx atlasmemory generate                   # Step 3: Generate AI instructions
npx atlasmemory status                     # Check your AI Readiness Score

Maximum Power Checklist

Do all of these and AtlasMemory becomes a beast. Each step unlocks more capability:

| | Step | What it unlocks | Command | |---|------|----------------|---------| | ✅ | Index your project | Symbol extraction, anchors, basic search | npx atlasmemory index . | | ✅ | Enrich files | Semantic search, concept-level understanding | npx atlasmemory enrich --all | | ✅ | Generate AI instructions | AI agents auto-use AtlasMemory (5 formats) | npx atlasmemory generate | | ✅ | Add MCP config | Zero-config connection for your AI tool | See configs below | | ✅ | Use log_decision after changes | Cross-session memory, institutional knowledge | AI agent calls it automatically | | ✅ | Use remember_project for milestones | Project-level memory persists forever | AI agent calls it automatically |

| AI Readiness | Search Quality | What to do | |-------------|----------------|------------| | 0-50 (Fair) | Keyword only | Run atlasmemory enrich — dramatically improves results | | 50-80 (Good) | Partial semantic | Run atlasmemory enrich --all for full coverage | | 80-100 (Excellent) | Full semantic + concept search | You're at maximum power! 🚀 |

About Enrichment

What it does: Enrichment analyzes each file and adds semantic tags — "authentication", "middleware", "error handling", "database query", etc. Without enrichment, search is keyword-based. With enrichment, search understands concepts — you can search "how does authentication work?" and get the right files even if they don't contain the word "authentication".

How it works: AtlasMemory uses Claude CLI or OpenAI Codex (running locally) to analyze files. Requires an active Claude or OpenAI subscription with CLI access.

Estimated enrichment time by project size:

| Project Size | Files | Enrichment Time | What happens | |---|---|---|---| | Small | ~50 files | ~2 minutes | Instant boost — search quality jumps to 80+ | | Medium | ~200 files | ~8 minutes | Full semantic coverage in one coffee break | | Large (Coolify-scale) | ~1400 files | ~45 minutes | Use --batch 50 for controlled enrichment | | Monorepo (Next.js-scale) | ~4000+ files | ~2 hours | Spread across sessions: enrich --batch 100 |

💡 Tip: Run atlasmemory enrich --dry-run first to see the token estimate before starting.

🔑 Don't worry — enrichment is a one-time cost. You enrich your project once, and it's done. After that, only new or changed files need re-enrichment (a few seconds). Think of it like building an index — you do it once, then it stays up to date incrementally.

No CLI? No problem. Your AI agent can enrich files directly via MCP. Just paste this into your AI chat:

Please enrich my project with AtlasMemory for maximum AI readiness.
Run enrich_files(limit=100) to enhance all files with semantic tags.
Then check ai_readiness to verify the score improved.

After handshake, if enrichment is low, AtlasMemory will suggest: "💡 X files can be enriched for better search."

"With just index_repo and enrich_files, you can turn an entire codebase into an AI-readable neural map — optimized for any AI agent." — Google Antigravity, after enriching 73 files in a single call

Setup in 30 Seconds

npx atlasmemory demo                           # See it in action
npx atlasmemory index .                        # Index your project
npx atlasmemory search "authentication"        # Search with FTS5 + graph
npx atlasmemory generate                       # Auto-generate CLAUDE.md

That's it. No API key, no cloud, no config files. AtlasMemory runs entirely on your machine.

Use with Your AI Tool

🟣 Claude Desktop / Claude Code — add to claude_desktop_config.json:

{ "mcpServers": { "atlasmemory": { "command": "npx", "args": ["-y", "atlasmemory"] } } }

🔵 Cursor — add to .cursor/mcp.json:

{ "mcpServers": { "atlasmemory": { "command": "npx", "args": ["-y", "atlasmemory"] } } }

🟢 VS Code / GitHub Copilot — add to settings or .vscode/mcp.json:

{ "mcp": { "servers": { "atlasmemory": { "command": "npx", "args": ["-y", "atlasmemory"] } } } }

🌀 Google Antigravity — add to MCP settings:

{ "mcpServers": { "atlasmemory": { "command": "npx", "args": ["-y", "atlasmemory"] } } }

🟠 OpenAI Codex — add to MCP config:

{ "mcpServers": { "atlasmemory": { "command": "npx", "args": ["-y", "atlasmemory"] } } }

One config, all tools. Auto-indexes on first query. Works with any MCP-compatible AI tool.

VS Code Extension

Install AtlasMemory for VS Code for a visual dashboard right in your editor:

AI Readiness Dashboard — see your score (0-100) with four metrics at a glance
Atlas Explorer Sidebar — browse files, symbols, anchors, flows, cards directly
Status Bar — always-visible readiness score, click to open dashboard
Auto-Index on Save — files re-indexed automatically when you save
Quick Actions — one-click index, generate CLAUDE.md, search, health check

Works alongside MCP — extension gives you the visual interface, MCP server gives AI agents the tools. Install both for the full experience.

Proof System

A feature no other tool has. Every claim is linked to an anchor — a specific line range and content hash.

+ Claim: "handleLogin() validates credentials before creating a session"
+ Evidence:
+   src/auth.ts:42-58 [hash:5cde2a1f] — validateCredentials() call
+   src/auth.ts:60-72 [hash:a3b7c9d1] — createSession() after validation
+ Status: PROVEN ✅ (2 anchors, hashes match current code)

- ⚠️ Someone edited auth.ts...
- Hash 5cde2a1f no longer matches lines 42-58
- Status: DRIFT DETECTED ❌ — AI knows context is stale BEFORE hallucinating

How It Works

You ask your AI agent a question. Behind the scenes, this happens:

flowchart LR
    subgraph YOU["🧑‍💻 You"]
        Q["'Fix auth bug'"]
    end

    subgraph ATLAS["⚡ AtlasMemory"]
        direction TB
        A["🔍 Search\nFTS5 + Graph"]
        B["📋 Prove\nClaims → code anchors"]
        C["📦 Pack\nFit within token budget"]
        D["🛡️ Contract\nDetect drift"]
    end

    subgraph AI["🤖 AI Agent"]
        R["Knows exactly where to look\n— no hallucination"]
    end

    Q --> A
    A -->|"Best files\nranked by relevance"| B
    B -->|"Every claim has\nline:hash proof"| C
    C -->|"2000 tokens instead\nof reading 50 files"| D
    D -->|"✅ Context is fresh\nno stale data"| R

    style YOU fill:#1a1a3e,stroke:#00e5ff,color:#fff
    style ATLAS fill:#0a1628,stroke:#00bcd4,color:#fff
    style AI fill:#1a1a3e,stroke:#00e5ff,color:#fff
    style Q fill:#162447,stroke:#00e5ff,color:#fff
    style A fill:#0d2137,stroke:#00bcd4,color:#00e5ff
    style B fill:#0d2137,stroke:#00bcd4,color:#00e5ff
    style C fill:#0d2137,stroke:#00bcd4,color:#00e5ff
    style D fill:#0d2137,stroke:#00bcd4,color:#00e5ff
    style R fill:#162447,stroke:#00e5ff,color:#fff

Without AtlasMemory vs. With AtlasMemory

flowchart TB
    subgraph WITHOUT["❌ Without AtlasMemory"]
        direction TB
        W1["AI reads file 1"] --> W2["AI reads file 2"]
        W2 --> W3["AI reads file 3..."]
        W3 --> W4["...AI reads file 47"]
        W4 --> W5["💥 Context full!\nStarting over..."]
        W5 -.->|"∞ loop"| W1
    end

    subgraph WITH["✅ With AtlasMemory"]
        direction TB
        A1["AI asks: 'fix auth bug'"]
        A1 --> A2["AtlasMemory returns:\n2000 tokens\nevidence-backed context"]
        A2 --> A3["AI fixes the bug\n85% of context still free"]
    end

    style WITHOUT fill:#1a0a0a,stroke:#ff4444,color:#fff
    style WITH fill:#0a1a0a,stroke:#00ff88,color:#fff
    style W5 fill:#330000,stroke:#ff4444,color:#ff6666
    style A3 fill:#003300,stroke:#00ff88,color:#00ff88

Three Core Pillars

| | Pillar | What it does | |---|--------|-------------| | 🔒 | Evidence-Backed | Every claim is linked to an anchor (line range + content hash). If the code changes, the anchor is marked stale. Hallucination is impossible. | | 🛡️ | Drift-Resistant | SHA-256 snapshot of database state + git HEAD. If the repo changes during a session, AtlasMemory detects and warns. | | 📦 | Token-Budgeted | Greedy-optimized packs that fit your budget. Priority order: objectives > folders > cards > flows > code snippets. |

Supported Languages

All 11 languages use precise AST parsing via Tree-sitter — no regex, no guessing.

| Language | What's extracted | |----------|-----------------| | TypeScript / JavaScript | functions, classes, methods, interfaces, types, imports, calls | | Python | functions, classes, decorators, imports, calls | | Go | functions, methods, structs, interfaces, imports, calls | | Rust | functions, impl blocks, structs, traits, enums, use, calls | | Java | methods, classes, interfaces, enums, imports, calls | | C# | methods, classes, interfaces, structs, enums, using, calls | | C / C++ | functions, classes, structs, enums, #include, calls | | Ruby | methods, classes, modules, calls | | PHP | functions, methods, classes, interfaces, use, calls |

MCP Tools (28 total)

Core — tools your AI agent uses every session:

| Tool | Description | |------|-------------| | 🔍 search_repo | Full-text + graph-powered codebase search | | 📦 build_context | Unified context builder — task, project, delta, or session mode | | ✅ prove | Prove claims with evidence anchors in your codebase | | 📂 index_repo | Full or incremental indexing | | 🤝 handshake | Start agent session with project summary + memory |

| Tool | Description | |------|-------------| | 💥 analyze_impact | Who depends on this symbol/file? Reverse reference graph | | 📊 smart_diff | Semantic git diff — symbol-level changes + breaking changes | | 🧠 remember | Save decisions, constraints, insights for the session | | 📋 session_context | View accumulated context + related past sessions | | ✨ enrich_files | AI-enrich file cards with semantic tags |

| Tool | Description | |------|-------------| | 📝 log_decision | Record what you changed and why (persists across sessions) | | 📜 get_file_history | See what past AI agents changed in a file | | 💾 remember_project | Store project-level knowledge (milestones, gaps, lessons) |

| Tool | Description | |------|-------------| | 🏗️ generate_claude_md | Auto-generate CLAUDE.md / .cursorrules / copilot-instructions | | 📈 ai_readiness | Calculate AI Readiness Score (0-100) | | 🛡️ get_context_contract | Check drift status with suggested actions | | 🔄 acknowledge_context | Confirm that the context is understood |

Configuration

AtlasMemory works with zero configuration. Optional settings:

| Setting | Default | Description | |---------|---------|-------------| | ATLAS_DB_PATH | .atlas/atlas.db | Database location | | ATLAS_LLM_API_KEY | — | API key for LLM-enriched card descriptions (experimental — will be strengthened in future releases) | | ATLAS_CONTRACT_ENFORCE | warn | Contract mode: strict / warn / off | | .atlasignore | — | Custom file/directory exclusion rules (like .gitignore) |

Architecture

block-beta
    columns 4

    block:ENTRY:4
        CLI["⬛ CLI"]
        MCP["🟣 MCP Server"]
        VSCODE["🟢 VS Code"]
    end

    space:4

    block:ENGINE:4
        columns 4
        INDEXER["🔧 Indexer\n11 languages"]:1
        SEARCH["🔍 Search\nFTS5 + Graph"]:1
        CARDS["📋 Cards\nSummaries"]:1
        TASKPACK["📦 TaskPack\nProof + Budget"]:1
    end

    space:4

    block:INTEL:4
        columns 4
        IMPACT["💥 Impact"]:1
        MEMORY["🧠 Memory"]:1
        LEARNER["📊 Learner"]:1
        ENRICH["✨ Enrichment"]:1
    end

    space:4

    block:DATA:4
        DB["🗄️ SQLite + FTS5 — Single file, ~394KB bundle"]
    end

    ENTRY --> ENGINE
    ENGINE --> INTEL
    INTEL --> DATA

    style ENTRY fill:#1a1a3e,stroke:#00e5ff,color:#fff
    style ENGINE fill:#0a1628,stroke:#00bcd4,color:#fff
    style INTEL fill:#0d2137,stroke:#00bcd4,color:#fff
    style DATA fill:#162447,stroke:#00e5ff,color:#fff

Frequently Asked Questions

A score from 0-100 that measures how ready your codebase is for AI agents. Calculated from 4 metrics:

| Metric | Weight | What it measures | |--------|--------|-----------------| | Code Coverage | 25% | Percentage of source files indexed by Tree-sitter | | Description Quality | 25% | Percentage of files with AI descriptions enriched via enrich | | Flow Analysis | 25% | Percentage of files with cross-file data flow cards | | Evidence Anchors | 25% | Percentage of claims linked to code anchors (line + hash) |

Run atlasmemory status to see your score. Use atlasmemory enrich to improve it.

| Term | What it is | Example | |------|-----------|---------| | Symbol | A named code entity extracted by Tree-sitter | function handleLogin(), class UserService, interface AuthConfig | | Anchor | Line range + content hash — the "proof" of the evidence-backed system | src/auth.ts:42-58 [hash:5cde2a1f] | | Flow | Cross-file data path (A calls B, B calls C) | login() → validateToken() → createSession() | | File Card | Evidence-linked summary of what a file does | Purpose, public API, dependencies, side effects | | Import | Cross-file dependency relationship | import { Store } from './store' | | Reference | Call/usage reference between symbols | handleLogin() calls validateToken() |

All of these are automatically extracted by atlasmemory index. No manual work required.

MCP mode (Claude/Cursor/VS Code): Yes, fully automatic. AtlasMemory checks git HEAD on every tool call. If files have changed since the last index, it incrementally re-indexes only the changed files. Zero manual work.

CLI mode: Run atlasmemory index . manually, or use atlasmemory index --incremental for quick updates.

No. AtlasMemory is 100% local-first. Core features (indexing, search, proving, context packs) work offline without depending on external services.

The optional enrich command uses Claude CLI or OpenAI Codex (running locally) to enhance file descriptions. Requires an active subscription with CLI access. If neither is installed, it falls back to deterministic AST-based descriptions — or your AI agent can enrich files directly via MCP tools.

Every claim AtlasMemory makes is linked to an anchor — a specific line range with a SHA-256 content hash.

AI says: "handleLogin validates credentials" → linked to auth.ts:42-58 [hash:5cde2a1f]
If someone edits auth.ts lines 42-58, the hash changes
AtlasMemory marks the claim as DRIFT DETECTED
The AI agent knows its understanding is stale before hallucinating

No other tool does this. RAG-based tools retrieve text but can't prove it matches current code.

11 languages via Tree-sitter: TypeScript, JavaScript, Python, Go, Rust, Java, C#, C, C++, Ruby, PHP. All extract functions, classes, methods, imports, and call references.

When you call build_context({mode: "task", objective: "fix auth bug", budget: 8000}), AtlasMemory:

Searches for relevant files (FTS5 + graph ranking)
Scores each file by relevance to your objective
Uses a greedy algorithm to fit the most relevant context into your budget
Priority order: objectives > folder summaries > file cards > flow traces > code snippets
Returns exactly as much context as your token budget allows — no overflow

Result: Instead of reading 50 files (filling your context window), you get 2000 tokens of evidence-backed context and 85% of your context window remains free for actual work.

It generates AI instruction files (CLAUDE.md, .cursorrules, copilot-instructions.md) containing:

Project architecture and key files
Tech stack and conventions
AI Readiness Score
AtlasMemory MCP tool usage instructions — so your AI agent uses AtlasMemory automatically

If you have a hand-written CLAUDE.md, it merges the AtlasMemory section at the top without overwriting your content.

| Feature | Cursor Indexing | AtlasMemory | |---------|----------------|-------------| | Proof system | None | Yes — every claim has line:hash proof | | Drift detection | None | Yes — SHA-256 contract system | | Token budgeting | None | Yes — greedy-optimized context packs | | Cross-session memory | None | Yes — decisions persist across sessions | | Impact analysis | None | Yes — reverse reference graph | | Works with any AI tool | No (Cursor only) | Yes — MCP standard | | Local-first | Partially | 100% |

Development

git clone https://github.com/Bpolat0/atlasmemory.git
cd atlasmemory
npm install
npm run build:all        # Build all packages + bundle
npm test                 # Run unit tests (147 tests, Vitest)
npm run eval:synth100    # Quick evaluation suite
npm run eval             # Full evaluation (synth-100 + synth-500 + real-repo)

Roadmap

[x] v1.0 — Core engine, proof system, MCP server, CLI, OpenAI Codex support
[ ] Interactive dependency graph — visual topology of your codebase (like the screenshot below)
[ ] VS Code extension improvements — enrich button, card browser, inline proof viewer
[ ] Semantic search with embedding vectors
[ ] Multi-repo support (monorepo + microservices)
[ ] GitHub Actions integration (auto-index on push)
[ ] Web dashboard with live graph visualization

See Discussions to view planned features and vote.

Contributing

We welcome your contributions! Bug reports, feature requests, or pull requests — all are appreciated.

CONTRIBUTING.md — Setup guide, PR process, commit format, testing
CLAUDE.md — Project architecture and conventions

git clone https://github.com/Bpolat0/atlasmemory.git
cd atlasmemory
npm install && npm run build && npm test   # 147 tests should pass

Star History

Support

If AtlasMemory saves you time, consider giving it a star — it helps others discover the project.

License

GPL-3.0