ATLAS

Ambient Tracking, Learning, and Structured Memory System

A local-first, cross-tool, structured project memory system. ATLAS stores decisions, facts, architecture notes, blockers, and more — queryable by any AI tool via MCP, REST API, or CLI.

Why ATLAS?

AI coding assistants forget everything between sessions. ATLAS gives them (and you) a persistent, structured memory that tracks what matters: decisions and their rationale, system architecture, active blockers, team preferences, rejected alternatives, and more.

• Local-first — all data lives in ~/.atlas/ (SQLite + optional Qdrant vectors)
• Cross-tool — works with Claude Code, Cursor, and any MCP-compatible tool
• Structured — 12 memory types with confidence scores, relationships, and temporal validity
• Searchable — hybrid FTS5 + semantic vector search with Reciprocal Rank Fusion
• Self-maintaining — automatic decay engine archives stale memories, contradiction detection flags conflicts

Quick Start

# Install
pip install -e "."

# Initialize for your project
cd your-project
atlas init

# Store a memory
atlas remember "Chose PostgreSQL for the order service — need ACID for financial data" \
  --type decision --confidence 0.95 --tags "database,orders"

# Search memories
atlas recall "database choice"

# See project context
atlas context

Memory Types

Type	Description
decision	A choice made between alternatives
fact	Verifiable statement about the project/system
event	Something that happened (deployment, incident, meeting)
observation	A noticed pattern or metric
blocker	Something preventing progress
architecture	How the system is built/structured
preference	Team/project convention or preference
rejection	Alternative explicitly rejected and why
task_state	Current progress on an ongoing task
user	User role, expertise, and preferences
feedback	Guidance on approach — corrections and confirmations
reference	Pointers to external resources (dashboards, docs, trackers)

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   CLI        │  │  MCP Server │  │  REST API   │  │ Web Inspector│
│  (Click)     │  │  (11 tools) │  │  (FastAPI)  │  │  (SPA)      │
└──────┬───────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                 │                │                │
       └─────────────────┴────────────────┴────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   Service Layer    │
                    │                   │
                    │  Hybrid Search    │  FTS5 + Qdrant + RRF
                    │  Extraction       │  LLM-powered (Ollama)
                    │  Contradiction    │  Conflict detection
                    │  Decay Engine     │  Strategic forgetting
                    │  Claude Sync      │  Memory/transcript import
                    │  File/Git Watch   │  Automatic capture
                    │  Team Sync        │  .atlas/ export/import
                    └─────────┬─────────┘
                              │
               ┌──────────────┴──────────────┐
               │                             │
        ┌──────┴──────┐              ┌───────┴──────┐
        │   SQLite    │              │    Qdrant    │
        │   + FTS5    │              │   (vectors)  │
        └─────────────┘              └──────────────┘

Interfaces

CLI

The primary user interface. Full command list:

atlas init                    # Initialize project
atlas remember CONTENT        # Store a memory
atlas recall QUERY            # Hybrid search (FTS5 + vectors)
atlas list                    # List active memories
atlas show ID                 # Full memory details
atlas supersede ID CONTENT    # Replace a memory, keep history
atlas forget ID               # Archive a memory
atlas context                 # Project context summary
atlas decisions               # Active decisions and rationale
atlas timeline                # Chronological event history
atlas contradictions          # Unresolved conflicts
atlas status                  # Memory statistics

# Ingestion
atlas scan                    # Extract memories from git history
atlas import FILE             # Import from markdown/JSON/text
atlas extract TEXT --store    # LLM extraction from text

# Claude Code Integration
atlas sync-claude             # Import Claude Code memory files
atlas watch-claude            # Watch Claude memory dirs for changes
atlas ingest-transcripts      # Extract memories from Claude Code transcripts

# Maintenance
atlas gc                      # Archive decayed memories
atlas analyze                 # Show decay scores
atlas reindex                 # Rebuild vector index

# Team
atlas sync-export             # Export .atlas/ for team sharing
atlas sync-import             # Import .atlas/ from team

# Servers
atlas serve                   # REST API + web inspector (port 5700)
atlas mcp                     # MCP server (stdio transport)

MCP Server

11 tools for Claude Code, Cursor, and other MCP-compatible AI tools:

• atlas_recall — Search memories (hybrid)
• atlas_remember — Store a memory
• atlas_update — Modify existing memory
• atlas_supersede — Replace with history
• atlas_context — Load project context
• atlas_decisions — Active decisions
• atlas_blockers — Active blockers
• atlas_timeline — Event history
• atlas_entities — Named entities and relationships
• atlas_contradictions — Unresolved conflicts
• atlas_decay_analysis — Memories at risk of archival

REST API

FastAPI server with OpenAPI docs at /docs:

GET  /api/v1/projects/{project}/recall?q=QUERY
POST /api/v1/projects/{project}/remember
GET  /api/v1/projects/{project}/memories
GET  /api/v1/projects/{project}/context
GET  /api/v1/projects/{project}/decisions
GET  /api/v1/projects/{project}/contradictions

Web Inspector

Single-page dark-themed UI at http://localhost:5700 — search, filter, browse, and inspect memories with no build step required.

Search

ATLAS uses hybrid search combining two strategies with Reciprocal Rank Fusion:

1. FTS5 (always available) — full-text keyword search on content, summary, and tags
2. Qdrant vectors (optional) — semantic similarity via nomic-embed-text embeddings

RRF merging applies recency boost (newer memories rank higher) and confidence weighting to produce the final ranking.

Claude Code Integration

ATLAS can sync bidirectionally with Claude Code's built-in memory system:

# One-shot import of all Claude Code memory files
atlas sync-claude

# Watch for new/changed memory files in real-time
atlas watch-claude

# Extract memories from conversation transcripts
atlas ingest-transcripts

Memory files at ~/.claude/projects/*/memory/*.md are parsed (YAML frontmatter + markdown body), mapped to ATLAS types, and deduplicated on re-import.

Transcript ingestion reads JSONL files from ~/.claude/projects/, extracts user/assistant exchanges, and runs them through the LLM extraction pipeline with incremental cursor tracking.

Stack

Component	Technology
Database	SQLite + FTS5
Vectors	Qdrant (cosine similarity)
Embeddings	Ollama (nomic-embed-text)
LLM Extraction	Ollama (qwen2.5:7b)
CLI	Click + Rich
API	FastAPI + Uvicorn
MCP	MCP SDK (stdio)
Web	Vanilla JS + HTML/CSS
File Watching	Watchdog
Git Analysis	GitPython

Development

# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

Optional services

Vector search and LLM extraction require local services:

# Qdrant (vector database)
docker run -p 6333:6333 qdrant/qdrant

# Ollama (embeddings + extraction)
ollama pull nomic-embed-text
ollama pull qwen2.5:7b

ATLAS degrades gracefully — it works with just SQLite/FTS5 if Qdrant or Ollama aren't available.

License

MIT