Metadata-Version: 2.4
Name: atlas-ai-memory
Version: 0.1.0
Summary: Ambient Tracking, Learning, and Structured Memory System — local-first, cross-tool project memory for AI-assisted development
Project-URL: Homepage, https://github.com/whiskeylabs/atlas
Project-URL: Repository, https://github.com/whiskeylabs/atlas
Project-URL: Issues, https://github.com/whiskeylabs/atlas/issues
Project-URL: Documentation, https://github.com/whiskeylabs/atlas#readme
Author-email: Justin Howell <justin@neanthro.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,developer-tools,embeddings,knowledge-management,mcp,memory,project-memory,rag
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: watchdog>=4.0
Provides-Extra: all
Requires-Dist: atlas-memory[api,mcp,vectors]; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.111; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: dev
Requires-Dist: atlas-memory[all]; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == 'mcp'
Provides-Extra: vectors
Requires-Dist: qdrant-client>=1.9; extra == 'vectors'
Description-Content-Type: text/markdown

# 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

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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:

```bash
# 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
