Atlas 2.0 — Memoria persistente para agentes de codificación

Atlas da a los agentes de codificación una memoria. Tu IA puede escribir código. Atlas hace que recuerde por qué.

¿Qué es Atlas?

Atlas es una infraestructura de memoria persistente y consciente del repositorio para agentes de codificación autónomos. Utiliza CockroachDB como sistema de registro duradero para la memoria estructurada y semántica, lo que permite a los agentes:

• Recordar entre sesiones — el contexto sobrevive a los reinicios del agente

• Aprender del historial de git — extraer memorias automáticamente de los commits

• Buscar semánticamente — kNN vectorial sobre embeddings de AWS Bedrock

• Transferir el trabajo — transferencia estructurada de contexto entre agentes

• Rastrear decisiones — por qué se tomaron ciertas decisiones y qué alternativas existían

Related MCP server: agent-memory

Arquitectura

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

Características

Sistema de memoria principal

• Seguimiento de sesiones — cada sesión de codificación tiene una línea temporal de memorias + decisiones

• Tipos de memoria — ARCHITECTURE, DECISION, BUG, TODO, WARNING, IMPORTANT_FILE, DEPENDENCY, SECURITY, CONTEXT

• Filtrado por importancia — solo se incrustan las memorias con importancia ≥ 3 (reduce el coste)

• Seguimiento de resolución — los TODOs y BUGs pueden marcarse como resueltos sin eliminarse

Extracción inteligente

• Escáner de repositorios — detecta automáticamente la pila tecnológica a partir de package.json, requirements.txt, go.mod, Cargo.toml

• Extracción de memoria de Git — analiza los mensajes de commit y los cambios de archivos para generar memorias

• Descubrimiento de arquitectura — extrae el diseño del sistema de README.md

• Archivos importantes — identifica archivos críticos (config, schema, manifests)

Búsqueda semántica

• kNN vectorial — impulsado por AWS Bedrock Titan Embeddings v2

• Búsqueda multi-repositorio — buscar en todos los repositorios o restringir a uno

• Filtrado por tipo — filtrar por tipo de memoria

• Registro de auditoría — cada recuperación queda registrada para la observabilidad

Transferencia entre agentes

• Transferencias estructuradas — "Lo que hice / Lo que falló / Lo que sigue"

• Archivos de proyección .atlas/ — respaldo portátil cuando el servidor MCP no está conectado

• Continuar donde lo dejaste — la interfaz muestra el resumen de la última sesión, las tareas abiertas y las decisiones clave

Configuración

1. Requisitos previos

• Node.js 18+

• Cuenta de CockroachDB Cloud (el plan gratuito funciona)

• Cuenta de AWS con acceso a Bedrock (Titan Embeddings v2)

2. Variables de entorno

Crea .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. Configuración de la base de datos

# Install dependencies
npm install

# Apply schema to CockroachDB
npx prisma db push

# Generate Prisma Client
npx prisma generate

4. Configuración del servidor MCP

Añade a tus ajustes de 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. Hook de activación automática (opcional)

Instala el hook SessionStart para que el contexto de Atlas se inyecte automáticamente cada vez que inicies una sesión de Claude Code — sin necesidad de llamar manualmente a atlas_start_session:

bash scripts/install-autofire.sh

Esto escribe un hook SessionStart en ~/.config/claude-code/settings.json. Cuando abres Claude Code en cualquier repositorio que tenga archivos .atlas/ o un ATLAS.md, el contexto se imprime al inicio de la sesión. El hook permanece en silencio para los repositorios que Atlas aún no ha visto.

6. Iniciar la interfaz

npm run dev

Visita http://localhost:3000 para ver el panel de Atlas.

Uso

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

Desde OpenAI Codex / Modo agente de VS Code (entre agentes)

Atlas habla MCP estándar — cualquier agente que soporte el Model Context Protocol puede usarlo. Para Codex en VS Code, añade Atlas a tu .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": "..."
      }
    }
  }
}

Tanto Claude Code como Codex escriben en el mismo clúster de CockroachDB, por lo que las memorias creadas en un agente están inmediatamente disponibles para el otro. El campo agentId en cada sesión y registro de memoria indica qué agente lo escribió.

Desde la interfaz

• Espacio de trabajo (/) — Todos los repositorios con recuento de sesiones, tareas abiertas, último agente

• Repositorio (/repo/[id]) — Widget "Continuar donde lo dejaste", sesiones recientes, tareas abiertas, decisiones clave

• Sesión (/session/[id]) — Línea temporal de la sesión con memorias + decisiones cronológicamente

• Búsqueda (/search) — Búsqueda semántica de memoria en todos los repositorios

Rutas de la API

• GET /api/repositories — Listar todos los repositorios

• GET /api/repositories/[id] — Obtener repositorio por ID con contexto

• POST /api/sessions — Iniciar una nueva sesión

• GET /api/sessions/[id] — Obtener detalles de la sesión

• POST /api/sessions/[id]/handoff — Generar documento de transferencia

• GET /api/memories/search?q=query — Búsqueda semántica

• GET /api/memories/stats — Estadísticas de memoria

Despliegue

Vercel (UI)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Set environment variables in Vercel dashboard

Servidor MCP

El servidor MCP se ejecuta localmente en tu máquina. Cada desarrollador debe configurarlo en sus ajustes de Claude Code.

Para despliegues en equipo, considera:

• Ejecutar el servidor MCP en un servidor de desarrollo compartido

• Usar túneles SSH para conectar Claude Code a un servidor MCP remoto

• Desplegarlo como contenedor con conexión compartida a CockroachDB

Pila tecnológica

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

• Backend — Rutas de API de Next.js, Prisma ORM

• Base de datos — CockroachDB Cloud (compatible con PostgreSQL, soporte vectorial)

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

• MCP — Model Context Protocol (integración con Claude Code)

• Despliegue — Vercel (UI), local/SSH (servidor MCP)

¿Por qué CockroachDB?

• Indexación vectorial — tipo VECTOR nativo con búsqueda por similitud coseno

• SQL distribuido — escalabilidad horizontal sin complejidad de particionado

• Soporte de Prisma — consultas con seguridad de tipos mediante cliente autogenerado

• Plan gratuito — 5 GB de almacenamiento, perfecto para proyectos personales

¿Por qué Atlas 2.0?

Atlas 1.0 era un rastreador de carteras blockchain — producto interesante pero tangencial a la "memoria agéntica".

Atlas 2.0 ES un sistema de memoria agéntica:

• ✅ Memoria estructurada (modelos de CockroachDB: sesiones, memorias, decisiones)

• ✅ Memoria semántica (búsqueda VECTOR + kNN mediante embeddings de AWS Bedrock)

• ✅ Memoria persistente (sobrevive a las sesiones, viaja con el repositorio mediante archivos .atlas/)

• ✅ Multi-agente (MCP para Claude/Codex + SDK para agentes personalizados)

• ✅ Consciente del repositorio (la memoria se limita a proyectos, no solo a cuentas de usuario)

Licencia

MIT