Atlas
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 generate4. 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 dashboardMCP 服务器
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent engineering memory designed to follow developers across coding agents.
Persistent memory for AI agents. Search, store, and recall across sessions.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm50MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.265 PyPIMIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent cognitive memory for AI coding agents, enabling them to recall architecture decisions, coding preferences, and project facts across sessions.68MIT
- AlicenseNot gradedqualityBmaintenanceProvides AI coding agents with a persistent memory layer to save, recall, update, and track memories across sessions and repositories using hybrid semantic search.5MIT