Skip to main content
Glama

Atlas 2.0 — 编码代理的持久记忆

Atlas 为编码代理提供记忆。你的 AI 可以编写代码。Atlas 让它记住原因。

什么是 Atlas?

Atlas 是一个持久化、仓库感知的记忆基础设施,专为自主编码代理设计。它使用 CockroachDB 作为结构化记忆和语义记忆的持久记录系统,使代理能够:

  • 跨会话记忆 — 上下文在代理重启后仍然存在

  • 从 Git 历史中学习 — 从提交中自动提取记忆

  • 语义搜索 — 基于 AWS Bedrock 嵌入的向量 kNN 搜索

  • 工作交接 — 代理之间的结构化上下文传递

  • 追踪决策 — 记录选择的原因以及存在的替代方案

Related MCP server: arcane

架构

┌─────────────────────────────────────────────────────────┐
│  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)                      │
└─────────────────────────────────────────────────────────┘

功能特性

核心记忆系统

  • 会话追踪 — 每个编码会话都有记忆和决策的时间线

  • 记忆类型 — ARCHITECTURE、DECISION、BUG、TODO、WARNING、IMPORTANT_FILE、DEPENDENCY、SECURITY、CONTEXT

  • 重要性门控 — 只有重要性 ≥ 3 的记忆才会被嵌入(降低成本)

  • 解决状态追踪 — TODO 和 BUG 可以标记为已解决而无需删除

智能提取

  • 仓库扫描器 — 从 package.json、requirements.txt、go.mod、Cargo.toml 自动发现技术栈

  • Git 记忆提取 — 解析提交消息和文件变更以生成记忆

  • 架构发现 — 从 README.md 提取系统设计

  • 重要文件 — 识别关键文件(配置、模式、清单)

语义搜索

  • 向量 kNN — 由 AWS Bedrock Titan Embeddings v2 驱动

  • 多仓库搜索 — 跨所有仓库搜索或限制为单个仓库

  • 类型过滤 — 按记忆类型过滤

  • 审计日志 — 每次检索都会被记录以便观察

代理交接

  • 结构化交接 — “我做了什么 / 什么失败了 / 下一步做什么”

  • .atlas/ 投影文件 — 当 MCP 服务器未连接时的便携式回退方案

  • 从上次中断处继续 — UI 显示上次会话摘要、未完成任务和关键决策

设置

1. 前提条件

  • Node.js 18+

  • CockroachDB Cloud 账户(免费套餐即可)

  • 具有 Bedrock 访问权限的 AWS 账户(Titan Embeddings v2)

2. 环境变量

创建 .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. 数据库设置

# Install dependencies
npm install

# Apply schema to CockroachDB
npx prisma db push

# Generate Prisma Client
npx prisma generate

4. MCP 服务器设置

添加到你的 Claude Code 设置(~/.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. 自动触发钩子(可选)

安装 SessionStart 钩子,以便每次启动 Claude Code 会话时自动注入 Atlas 上下文 — 无需手动调用 atlas_start_session:

bash scripts/install-autofire.sh

这会将 SessionStart 钩子写入 ~/.config/claude-code/settings.json。当你在任何包含 .atlas/ 文件或 ATLAS.md 的仓库中打开 Claude Code 时,上下文会在会话开始时打印出来。对于 Atlas 尚未见过的仓库,该钩子保持静默。

6. 启动 UI

npm run dev

访问 http://localhost:3000 查看 Atlas 仪表盘。

使用方法

从 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")

从 OpenAI Codex / VS Code Agent Mode(跨代理)使用

Atlas 使用标准 MCP — 任何支持模型上下文协议的代理都可以使用它。对于 VS Code 中的 Codex,将 Atlas 添加到你的 .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": "..."
      }
    }
  }
}

Claude Code 和 Codex 都写入同一个 CockroachDB 集群,因此在一个代理中创建的记忆立即可供另一个代理使用。每个会话和记忆记录上的 agentId 字段追踪是哪个代理写入的。

从 UI 使用

  • 工作区(/) — 所有仓库,显示会话计数、未完成任务、最后使用的代理

  • 仓库(/repo/[id]) — “从上次中断处继续”小部件、最近的会话、未完成任务、关键决策

  • 会话(/session/[id]) — 会话时间线,按时间顺序显示记忆和决策

  • 搜索(/search) — 跨所有仓库的语义记忆搜索

API 路由

  • GET /api/repositories — 列出所有仓库

  • GET /api/repositories/[id] — 按 ID 获取仓库及其上下文

  • POST /api/sessions — 开始新会话

  • GET /api/sessions/[id] — 获取会话详情

  • POST /api/sessions/[id]/handoff — 生成交接文档

  • GET /api/memories/search?q=query — 语义搜索

  • GET /api/memories/stats — 记忆统计

部署

Vercel(UI)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Set environment variables in Vercel dashboard

MCP 服务器

MCP 服务器在你的本地机器上运行。每个开发者需要在其 Claude Code 设置中配置它。

对于团队部署,考虑:

  • 在共享开发服务器上运行 MCP 服务器

  • 使用 SSH 隧道将 Claude Code 连接到远程 MCP 服务器

  • 作为容器部署,使用共享的 CockroachDB 连接

技术栈

  • 前端 — Next.js 14、React、TypeScript、Tailwind CSS

  • 后端 — Next.js API 路由、Prisma ORM

  • 数据库 — CockroachDB Cloud(兼容 PostgreSQL,支持向量)

  • 嵌入 — AWS Bedrock Titan Embeddings v2(1024 维)

  • MCP — 模型上下文协议(Claude Code 集成)

  • 部署 — Vercel(UI)、本地/SSH(MCP 服务器)

为什么选择 CockroachDB?

  • 向量索引 — 原生 VECTOR 类型,支持余弦相似度搜索

  • 分布式 SQL — 无需分片复杂性即可水平扩展

  • Prisma 支持 — 类型安全查询,自动生成客户端

  • 免费套餐 — 5 GB 存储,适合个人项目

为什么选择 Atlas 2.0?

Atlas 1.0 是一个区块链钱包追踪器 — 有趣的产品,但与“代理记忆”无关。

Atlas 2.0 就是一个代理记忆系统:

  • ✅ 结构化记忆(CockroachDB 模型:会话、记忆、决策)

  • ✅ 语义记忆(VECTOR + 基于 AWS Bedrock 嵌入的 kNN 搜索)

  • ✅ 持久记忆(跨会话存活,通过 .atlas/ 文件随仓库移动)

  • ✅ 多代理(用于 Claude/Codex 的 MCP + 用于自定义代理的 SDK)

  • ✅ 仓库感知(记忆限定于项目,而非仅用户账户)

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to store, retrieve, and manage contextual knowledge across sessions using semantic search with PostgreSQL and vector embeddings. Supports memory relationships, clustering, multi-agent isolation, and intelligent caching for persistent conversational context.
      21 npm
      50
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.
      265 PyPI
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides AI coding agents with a persistent memory layer to save, recall, update, and track memories across sessions and repositories using hybrid semantic search.
      5
      MIT