Atlas 2.0 — Persistent Memory for Coding Agents

Atlas gives coding agents a memory. Your AI can write code. Atlas makes it remember why.

What is Atlas?

Atlas is a persistent, repository-aware memory infrastructure for autonomous coding agents. It uses CockroachDB as a durable system of record for both structured and semantic memory, enabling agents to:

• Remember across sessions — context survives agent restarts

• Learn from git history — auto-extract memories from commits

• Search semantically — vector kNN over AWS Bedrock embeddings

• Hand off work — structured context transfer between agents

• Track decisions — why choices were made, what alternatives existed

Related MCP server: agent-memory

Architecture

┌─────────────────────────────────────────────────────────┐
│  Claude Code / Codex / Cursor (MCP Client)             │
└────────────────┬────────────────────────────────────────┘
                 │ MCP Protocol
┌────────────────▼────────────────────────────────────────┐
│  Atlas MCP Server (10 tools)                           │
│  - atlas_start_session                                 │
│  - atlas_save_memory                                   │
│  - atlas_record_decision                               │
│  - atlas_scan_repository                               │
│  - atlas_extract_git_memories                          │
│  - atlas_search_memory                                 │
│  - atlas_end_session                                   │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│  Atlas Memory Layer                                     │
│  - writer.ts  (session lifecycle, memory persistence)  │
│  - retrieval.ts (11 query functions)                   │
│  - embedder.ts (AWS Bedrock Titan v2, 1024d vectors)  │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│  CockroachDB Cloud (Source of Truth)                   │
│  - Structured memory (Prisma models)                   │
│  - Semantic memory (VECTOR + kNN)                      │
└─────────────────────────────────────────────────────────┘

Features

Core Memory System

• Session tracking — every coding session has a timeline of memories + decisions

• Memory types — ARCHITECTURE, DECISION, BUG, TODO, WARNING, IMPORTANT_FILE, DEPENDENCY, SECURITY, CONTEXT

• Importance gating — only memories with importance ≥ 3 are embedded (reduces cost)

• Resolution tracking — TODOs and BUGs can be marked resolved without deletion

Intelligent Extraction

• Repository scanner — auto-discovers tech stack from package.json, requirements.txt, go.mod, Cargo.toml

• Git memory extraction — parses commit messages and file changes to generate memories

• Architecture discovery — extracts system design from README.md

• Important files — identifies critical files (config, schema, manifests)

Semantic Search

• Vector kNN — powered by AWS Bedrock Titan Embeddings v2

• Multi-repo search — search across all repositories or restrict to one

• Kind filtering — filter by memory type

• Audit log — every retrieval is logged for observability

Agent Handoff

• Structured handoffs — "What I Did / What Failed / What's Next"

• .atlas/ projection files — portable fallback when MCP server isn't connected

• Pick up where you left off — UI surfaces last session summary, open tasks, key decisions

Setup

1. Prerequisites

• Node.js 18+

• CockroachDB Cloud account (free tier works)

• AWS account with Bedrock access (Titan Embeddings v2)

2. Environment Variables

Create .env:

# CockroachDB connection string
DATABASE_URL="postgresql://user:password@cluster.cockroachlabs.cloud:26257/defaultdb?sslmode=require"

# AWS Bedrock (for embeddings)
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your-key"
AWS_SECRET_ACCESS_KEY="your-secret"

3. Database Setup

# Install dependencies
npm install

# Apply schema to CockroachDB
npx prisma db push

# Generate Prisma Client
npx prisma generate

4. MCP Server Setup

Add to your Claude Code settings (~/.config/claude-code/settings.json):

{
  "mcpServers": {
    "atlas": {
      "command": "node",
      "args": ["/path/to/atlas-2/mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "...",
        "AWS_SECRET_ACCESS_KEY": "..."
      }
    }
  }
}

5. Auto-Fire Hook (optional)

Install the SessionStart hook so Atlas context is injected automatically every time you start a Claude Code session — no manual atlas_start_session call needed:

bash scripts/install-autofire.sh

This writes a SessionStart hook to ~/.config/claude-code/settings.json. When you open Claude Code in any repo that has .atlas/ files or an ATLAS.md, the context is printed at session start. The hook stays silent for repos Atlas hasn't seen yet.

6. Start the UI

npm run dev

Visit http://localhost:3000 to see the Atlas dashboard.

Usage

From Claude Code

# Start a session (auto-fired if you installed the hook, otherwise call manually)
atlas_start_session(repoPath="/home/user/my-project", repoName="my-project", agentId="claude-code")

# Scan repository for tech stack and architecture
atlas_scan_repository(repoPath="/home/user/my-project", repoId="...")

# Extract memories from git history
atlas_extract_git_memories(sessionId="...", repoId="...", repoPath="/home/user/my-project")

# Save a memory
atlas_save_memory(sessionId="...", repoId="...", kind="ARCHITECTURE", content="Uses Next.js 14 with App Router", importance=4)

# Record a decision
atlas_record_decision(sessionId="...", repoId="...", title="Use Prisma over Drizzle", rationale="Team familiarity", alternatives=["Drizzle", "TypeORM"])

# Search memories
atlas_search_memory(query="how does authentication work?", repoPath="/home/user/my-project")

# Generate ATLAS.md (portable session-start primer, no MCP needed)
atlas_generate_atlas_md(repoPath="/home/user/my-project")

# Reconstruct project timeline
atlas_reconstruct_timeline(repoPath="/home/user/my-project", since="2026-01-01")

# End session
atlas_end_session(sessionId="...", summary="Added user authentication", repoPath="/home/user/my-project")

From OpenAI Codex / VS Code Agent Mode (Cross-Agent)

Atlas speaks standard MCP — any agent that supports the Model Context Protocol can use it. For Codex in VS Code, add Atlas to your .vscode/mcp.json:

{
  "servers": {
    "atlas": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/atlas-2/mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "...",
        "AWS_SECRET_ACCESS_KEY": "..."
      }
    }
  }
}

Both Claude Code and Codex write to the same CockroachDB cluster, so memories created in one agent are immediately available to the other. The agentId field on each session and memory record tracks which agent wrote it.

From the UI

• Workspace (/) — All repositories with session count, open tasks, last agent

• Repository (/repo/[id]) — "Pick Up Where You Left Off" widget, recent sessions, open tasks, key decisions

• Session (/session/[id]) — Session timeline with memories + decisions chronologically

• Search (/search) — Semantic memory search across all repositories

API Routes

• GET /api/repositories — List all repositories

• GET /api/repositories/[id] — Get repository by ID with context

• POST /api/sessions — Start a new session

• GET /api/sessions/[id] — Get session details

• POST /api/sessions/[id]/handoff — Generate handoff document

• GET /api/memories/search?q=query — Semantic search

• GET /api/memories/stats — Memory statistics

Deployment

Vercel (UI)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Set environment variables in Vercel dashboard

MCP Server

The MCP server runs locally on your machine. Each developer needs to configure it in their Claude Code settings.

For team deployments, consider:

• Running the MCP server on a shared development server

• Using SSH tunneling to connect Claude Code to remote MCP server

• Deploying as a container with shared CockroachDB connection

Tech Stack

• Frontend — Next.js 14, React, TypeScript, Tailwind CSS

• Backend — Next.js API routes, Prisma ORM

• Database — CockroachDB Cloud (PostgreSQL-compatible, vector support)

• Embeddings — AWS Bedrock Titan Embeddings v2 (1024d)

• MCP — Model Context Protocol (Claude Code integration)

• Deployment — Vercel (UI), local/SSH (MCP server)

Why CockroachDB?

• Vector indexing — native VECTOR type with cosine similarity search

• Distributed SQL — horizontal scalability without sharding complexity

• Prisma support — type-safe queries with auto-generated client

• Free tier — 5 GB storage, perfect for personal projects

Why Atlas 2.0?

Atlas 1.0 was a blockchain wallet tracer — interesting product but tangential to "agentic memory."

Atlas 2.0 IS an agentic memory system:

• ✅ Structured memory (CockroachDB models: sessions, memories, decisions)

• ✅ Semantic memory (VECTOR + kNN search via AWS Bedrock embeddings)

• ✅ Persistent memory (survives sessions, travels with repo via .atlas/ files)

• ✅ Multi-agent (MCP for Claude/Codex + SDK for custom agents)

• ✅ Repository-aware (memory is scoped to projects, not just user accounts)

License

MIT