AtlasMemory

The Problem

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

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, tested on a real 83-file Tauri + React project

"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

How enrichment works: AtlasMemory uses Claude CLI or OpenAI Codex (running locally on your machine) to analyze each file and add semantic tags — "authentication", "middleware", "error handling", etc. Requires an active Claude or OpenAI subscription with CLI access. If neither is installed, it falls back to AST-based descriptions — or your AI agent can enrich files directly via the upsert_file_card MCP tool.

Via MCP: Your AI agent can enrich files directly. Just paste this prompt 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 also 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

Supported Languages

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

MCP Tools (28 total)

Core — tools your AI agent uses every session:

Configuration

AtlasMemory works with zero configuration. Optional settings:

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:

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

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.

1. AI says: "handleLogin validates credentials" → linked to auth.ts:42-58 [hash:5cde2a1f]

2. If someone edits auth.ts lines 42-58, the hash changes

3. AtlasMemory marks the claim as DRIFT DETECTED

4. 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:

1. Searches for relevant files (FTS5 + graph ranking)

2. Scores each file by relevance to your objective

3. Uses a greedy algorithm to fit the most relevant context into your budget

4. Priority order: objectives > folder summaries > file cards > flow traces > code snippets

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

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

• 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