Codeatrium

A memory palace for AI coding agents.

English · 日本語

Codeatrium distills past conversations into palace objects and stores them in a searchable index, giving agents long-term memory. Past decisions, implementations, and code locations can be recalled in under 0.2 seconds.

The CLI command loci (from Method of Loci) is designed to be called by the agent itself — running loci search "..." --json from within a prompt.

The architecture extends the conversational memory model from arXiv:2603.13017 for coding agents.

Note: Currently Claude Code only. Session log format (.jsonl) and distillation (claude --print) depend on Claude Code.

Simple Interface

Agents use two core commands:

• Semantic search — loci search "query" retrieves past conversations by semantic similarity
• Reverse lookup from code — loci context --symbol "name" recalls past conversations about a specific code symbol
  • tree-sitter symbol resolution (Python / TypeScript / Go) lets agents understand implementation intent before editing

How It Works

1. Index — Splits agent session logs into exchanges (user utterance + agent response pairs) and indexes them with FTS5 for keyword search
2. Distill — An LLM (claude --print, default claude-haiku-4-5) summarizes each exchange into a palace object: exchange_core (what was done), specific_context (concrete details), room_assignments (topic tags). tree-sitter resolves touched files to symbol level (function/class/method + file + line + signature)
3. Search — Cross-layer search fusing BM25 on verbatim text with HNSW on distilled embeddings via RRF

Raw conversations are not embedded — only the condensed distilled text is embedded with multilingual-e5-small (384-dim), balancing semantic search quality with embedding cost. The embedding model runs as a Unix socket server, keeping search latency under 0.2 seconds after the first load.

Installation

pipx install codeatrium

Requires Python 3.11+.

Quick Start

# Initialize in project root (also registers Claude Code hooks)
loci init

loci init now handles everything in one step — database setup, existing session detection, and Claude Code hook registration. Pass --no-hooks to skip hook registration. If init fails partway through, .codeatrium/ is cleaned up automatically so re-running is safe.

When running loci init, if past session logs are detected, you'll be prompted with:

[!IMPORTANT] When adopting this tool mid-project, a large number of exchanges may already exist. Distilling all of them will consume significant claude --print (Haiku) tokens. We recommend starting with Skip all or Distill last 50.

1. Min chars threshold — Minimum character filter for exchanges (default: 50). This controls how many exchanges become distillation candidates. Higher values exclude short conversations and reduce token usage; lower values include nearly everything.
2. Handling existing exchanges — Choose how much past history to distill:
   • Skip all (no past session distillation)
   • Distill last 50 (recent history only)
   • Distill all (everything — high token cost)
   • Custom (specify a number)
3. Run distillation now? — Accepts 1/2/y/n/yes/no. Choose No to defer to the next session start.

Invalid input on any prompt re-prompts instead of silently falling back to a default.

Agent Instructions

Agent instructions are injected automatically — no manual setup required:

• loci init — Inserts a marker section (<!-- BEGIN CODEATRIUM -->...<!-- END CODEATRIUM -->) into CLAUDE.md
• loci prime — Dynamically injects command usage into the context window at every session start via SessionStart Hook

CLI Commands

Automation (Claude Code Hooks)

After loci init (or loci hook install), everything runs automatically:

• loci index — Runs asynchronously after every turn. Indexes only new exchanges, so it's fast even mid-session
• loci distill — Distills undistilled exchanges at session start via claude --print. Calls Haiku through the user's Claude Code (default: claude-haiku-4-5)
• loci server start — Keeps the embedding model (~500MB) resident in memory for sub-0.2s search latency

Search Output

[
  {
    "exchange_core": "Added connection pool with pool_size=5",
    "specific_context": "pool_size=5, max_overflow=10",
    "rooms": [
      { "room_type": "concept", "room_key": "db-pool", "room_label": "DB connection pooling" }
    ],
    "symbols": [
      { "name": "create_pool", "file": "src/db.py", "line": 42, "signature": "def create_pool(...)" }
    ],
    "verbatim_ref": "~/.claude/projects/.../session.jsonl:ply=42"
  }
]

Configuration

.codeatrium/config.toml (generated by loci init):

[distill]
model = "claude-haiku-4-5-20251001"   # Model for distillation (default)
batch_limit = 20                       # Max distillations per hook run

[index]
min_chars = 50                         # Skip exchanges shorter than this

Acknowledgments

The palace object model, room-based topic grouping, and BM25+HNSW fusion search are based on:

Structured Distillation for Personalized Agent Memory (arXiv:2603.13017)

License

MIT