AtlasMemory — AI Agent Protocol (MANDATORY)

This project is indexed by AtlasMemory. You have access to proof-backed codebase memory. Follow these rules strictly — they exist to prevent hallucination and context waste.

Project Snapshot

• atlasmemory — Proof-backed, drift-resistant AI memory for your codebase
• AI Readiness: 93/100
• 85 files | 5108 symbols | 43345 evidence anchors
• Stack: TypeScript (82), JavaScript (3), MCP SDK, SQLite (better-sqlite3), Commander.js, Tree-sitter, esbuild, ESLint, Prettier, Vitest

Architecture

packages/intelligence           21 files → BudgetTracker, setBudgetLimit, trackUsage
packages/taskpack               12 files → PackOptions, DeltaOptions, SessionBootstrapOptions
packages/summarizer              8 files → RefreshStats, AutoRefresher, findStaleFiles
apps/vscode                      7 files → findNodeBinary, AtlasStatus, AtlasClient
packages/store                   7 files → SCHEMA, safeJsonParse, Store
src                              6 files → EXCLUDED_PATTERNS, loadIgnorePatterns, shouldIgnore
packages/indexer                 5 files → Indexer, initParsers, wave2
packages/retrieval               5 files → GraphNode, GraphService, buildGraph

Key Files

• packages/store/src/store.ts — Store: exports safeJsonParse, Store, constructor +95 more (1 class, 81 method...
• packages/taskpack/src/bootpack.ts — Bootpack: exports PackOptions, DeltaOptions, SessionBootstrapOptions +48 more...
• packages/taskpack/src/builder.ts — Builder: exports TaskPackBuilder, constructor, build +31 more (1 class, 10 me...
• packages/taskpack/src/proof.ts — Proof: exports EvidencePolicy, ClaimInput, ProveClaimResult +30 more (2 class...
• packages/core/src/types.ts — Types: exports Anchor, SymbolKind, CodeSymbol +39 more (7 types)
• src/mcp-server.ts — Mcp server: exports McpServerOptions, resolveProjectRoot, initStore +16 more ...
• apps/eval/src/runner.ts — Runner: exports EvalConfig, LatencySample, BootpackCheckResult +39 more (1 cl...
• src/generate-claude-md.ts — Generate claude md: exports GenerateFormat, isAutoGenerated, GenerateOptions ...

MUST DO:

1. Start every session with handshake to get project brief, memory, and risk map
2. Before reading files, call search_repo or build_context first — AtlasMemory already knows what each file does
3. Never guess about code structure — use search_repo to find the right files
4. After making changes, call log_decision(files, summary, why, type) to record what you did and why
5. For complex tasks, use build_context(mode="task", objective="...") to get proof-backed context within token budget
6. Check impact before modifying shared code — use analyze_impact(symbol_name) to see who depends on it
7. Record constraints with remember(type="constraint", text="...") so future sessions don't repeat mistakes
8. Enrich files when AI Readiness is below 80% — call enrich_files if a CLI backend is available, OR manually enrich: call refresh_cards_for_changed_files to find unenriched files, read them, then call upsert_file_card with semantic tags and purpose description. High enrichment = dramatically better search quality.

MUST NOT:

• Do NOT read files one-by-one with grep/cat when search_repo can find them instantly
• Do NOT guess file purposes — every file has an evidence-backed card accessible via AtlasMemory
• Do NOT ignore drift warnings — if AtlasMemory reports DRIFT, re-index before proceeding
• Do NOT skip log_decision after changes — future agents lose context without it
• Do NOT leave enrichment at 0% — this severely degrades search quality for future sessions

Quick Reference:

Need	Tool	Example
Find files	search_repo	search_repo("authentication middleware")
Get context	build_context	build_context(mode="task", objective="fix login bug")
Check impact	analyze_impact	analyze_impact(symbol_name="handleLogin")
Prove claims	prove	prove(claims="handleLogin validates credentials")
Record work	log_decision	log_decision(files=["src/auth.ts"], summary="...", why="...", type="fix")
Remember	remember	remember(type="constraint", text="Do not modify legacy API")
Enrich files	enrich_files	enrich_files(limit=10) or manually via upsert_file_card

AtlasMemory

NOTE : Benimle her zaman türkçe konuş.

What This Is

Local-first code memory system that gives AI agents "infinite context." Indexes repos with Tree-sitter, generates evidence-backed summaries (FileCards), and packages optimized context windows (TaskPacks) within token budgets. Solves context explosion and LLM drift.

Architecture

Monorepo (npm workspaces) with 7 packages + 3 apps:

packages/core         → Shared types (Anchor, CodeSymbol, FileCard, FlowCard, ImpactReport, etc.)
packages/store        → SQLite via better-sqlite3, FTS5 search, all DB ops
packages/indexer      → Tree-sitter parsing (11 langs: TS/JS/Python/Go/Rust/Java/C#/C/C++/Ruby/PHP)
packages/retrieval    → Multi-stage search (FTS → Path → Folder → Graph)
packages/summarizer   → Card generation (deterministic + optional LLM)
packages/taskpack     → Token-budgeted context packs, proof system, contracts
packages/intelligence → Intelligence layer (impact, prefetch, diff, budget, memory, learning, code health, enrichment, proactive)
apps/cli              → `atlas` CLI (index, search, taskpack, bootpack, etc.)
apps/mcp-server       → MCP protocol server exposing tools to AI agents
apps/eval             → Eval harness (synth-100, synth-500, real-repo)

Key Files

• Types: packages/core/src/types.ts
• DB Schema: packages/store/src/schema.ts
• DB Operations: packages/store/src/store.ts
• Indexer: packages/indexer/src/indexer.ts
• Search: packages/retrieval/src/search.ts
• Card Generator: packages/summarizer/src/card-generator.ts
• TaskPack Builder: packages/taskpack/src/builder.ts
• Proof System: packages/taskpack/src/proof.ts
• Contract Service: packages/taskpack/src/contract.ts
• Impact Analyzer: packages/intelligence/src/impact-analyzer.ts
• Prefetch Engine: packages/intelligence/src/prefetch-engine.ts
• Diff Enricher: packages/intelligence/src/diff-enricher.ts
• Budget Tracker: packages/intelligence/src/budget-tracker.ts
• Conversation Memory: packages/intelligence/src/conversation-memory.ts
• Session Learner: packages/intelligence/src/session-learner.ts
• Code Health: packages/intelligence/src/code-health.ts
• Enrichment Coordinator: packages/intelligence/src/enrichment-coordinator.ts
• Proactive Response: packages/intelligence/src/proactive-response.ts
• CLI: apps/cli/src/index.ts
• MCP Server: apps/mcp-server/src/index.ts
• Design Doc (TR): memory.md
• Handoff Doc: project_handoff.md

Commands

npm install              # Install all workspace deps
npm run build            # Build all packages (tsc)
npm run test             # Run tests
npm run eval             # Full eval suite (synth-100 + synth-500 + real-repo)
npm run eval:synth100    # Quick eval
npm run eval:synth500    # Medium eval
npm run eval:real        # Real-repo smoke (CI mode)
npm run eval:real:heal   # Real-repo with auto-heal (local dev)
npm run selftest:agent   # Agent self-test validation
atlas enrich             # AI enrichment (CLI free / API paid)
atlas enrich --dry-run   # Show what would be enriched
atlas enrich --all       # Enrich all unenriched files

Tech Stack

• Language: TypeScript (ES2022, NodeNext modules, strict mode)
• Runtime: Node.js v18+
• DB: SQLite via better-sqlite3, FTS5 enabled
• Parser: Tree-sitter (TS, JS, Python, Go, Rust, Java, C#, C, C++, Ruby, PHP — 11 languages)
• MCP: @modelcontextprotocol/sdk
• CLI: Commander.js
• Build: tsc + esbuild → dist/atlasmemory.js (~331KB bundle)
• AI SDK: @anthropic-ai/sdk (optional, for paid API enrichment)

Conventions

• ESM modules throughout ("type": "module" in all package.json)
• Workspace references: @atlasmemory/core, @atlasmemory/store, etc.
• Path aliases: @atlasmemory/* maps to packages/*/src
• DB lives at <repo>/.atlas/atlas.db
• Deterministic-first: core logic is LLM-free, LLM only for Level 1+ cards
• Every claim must link to anchors (evidence-backed)
• Token budgeting uses greedy priority algorithm
• File dedup priority: .ts > .tsx > .js > .jsx > .d.ts

Design Principles

1. Local-first — no external services for basic operation
2. Evidence-backed — claims link to anchors (line range + snippet hash)
3. Token-aware — greedy budgeting fits context windows
4. Incremental — hash-based change detection avoids full re-index
5. Drift-resistant — context contracts detect repo state changes
6. Deterministic core — LLM optional, AST extraction is pure

Data Flow

Files → [Indexer/Tree-sitter] → Symbols + Anchors + Imports + Refs
  → [Store/SQLite] → [CardGenerator] → FileCards + FlowCards
  → [SearchService] → Ranked results (+ pattern boosts from SessionLearner)
  → [TaskPackBuilder] → Token-budgeted markdown (+ prefetch suggestions)
  → [Intelligence] → Impact analysis, smart diff, conversation memory
  → [MCP/CLI] → LLM context (+ budget tracking)
  → [ContractService] → Drift detection

DB Tables

• files, symbols, imports, refs, anchors — raw indexed data
• file_cards, symbol_cards, flow_cards, folder_cards, project_card — summaries
• session_state, context_snapshots — session tracking
• reverse_refs — inverse ref index for impact analysis
• conversation_events, session_patterns, token_usage — intelligence layer
• fts_files, fts_symbols, fts_semantic_tags, fts_agent_changes — FTS5 virtual tables
• code_health — git history health metrics (churn, breaks, coupling)
• agent_changes, agent_change_files — AI agent decision memory (Phase 21)

MCP Tools

Primary: search_repo, build_context, prove, index_repo, index_file, generate_claude_md, ai_readiness, handshake, get_context_contract, acknowledge_context Intelligence: analyze_impact, smart_diff, remember, session_context, enrich_files Agent Memory: log_decision, get_file_history Legacy (deprecated): build_task_pack, bootpack, deltapack, session_bootstrap, prove_claim, prove_claims Card mgmt: get_allowed_evidence, validate_file_card, upsert_file_card, refresh_cards_for_changed_files, auto_refresh

Evaluation

• synth-100/500: Synthetic repos with known ground truth
• real-repo: Smoke test on actual codebase (10 objectives)
• Targets: Zero-result rate <2%, Recall@5 >0.9, p95 latency <50ms
• Reports written to apps/eval/reports/<timestamp>/

Session Continuity (IMPORTANT)

• SESSION_HANDOFF.md — AI agent continuity document. Read this at the START of every session.
• Contains: current project state, what was done, known gaps, technical architecture, session history
• RULE: After completing any significant change (feature, fix, refactor), update SESSION_HANDOFF.md with:
  1. What was done (problem + solution)
  2. Which files were created/modified
  3. Test results
  4. Any new known gaps
  5. Add entry to Session History table
• This ensures no context is lost between sessions.

Current Status

Phases 1-22 complete. Phase 22: AI Enrichment Engine — dual-backend (CLI free + API paid) replaces dead MCP Sampling. atlas enrich CLI command. Post-index auto-enrichment. See SESSION_HANDOFF.md for details.

Key Files (Phase 22 additions)

• Enrichment Backend: packages/intelligence/src/enrichment-backend.ts
• Claude CLI Backend: packages/intelligence/src/backends/claude-cli.ts
• Anthropic SDK Backend: packages/intelligence/src/backends/anthropic-sdk.ts
• Enrichment Prompt: packages/intelligence/src/enrichment-prompt.ts
• Session Handoff: SESSION_HANDOFF.md