codeatrium 0.1.0__tar.gz

codeatrium-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Test & lint caches
+.pytest_cache/
+.ruff_cache/
+
+# Tool data (local only)
+.codeatrium/
+.logosyncx/
+
+# Claude Code local settings
+.claude/
+
+# Internal docs (local only)
+docs/internal/
+
+# 論文資料（ローカルのみ）
+mem/

codeatrium-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- `loci init` — initialize `.codeatrium/` in project root
+- `loci index` — parse `.jsonl` session logs, split into exchanges, embed with multilingual-e5-small
+- `loci distill` — distill exchanges via `claude --print` into palace objects (exchange_core, specific_context, room_assignments)
+- `loci search` — cross-layer RRF fusion search (BM25 verbatim + HNSW distilled)
+- `loci context` — reverse lookup: code symbol → past conversations
+- `loci show` — fetch verbatim exchange by ref
+- `loci status` — show index state
+- `loci server start/stop/status` — Unix socket embedding server for <0.2s search
+- `loci hook install` — register Claude Code SessionStart/Stop hooks
+- `config.toml` support for distill model and batch limit
+- tree-sitter symbol resolution (Python, TypeScript, Go)
+- Bilingual support (Japanese + English) via multilingual-e5-small

codeatrium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 senna-lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codeatrium-0.1.0/Makefile

@@ -0,0 +1,22 @@
+VENV := .venv/bin
+
+.PHONY: test lint fmt typecheck check hooks
+
+test:
+	$(VENV)/pytest tests/ -v
+
+lint:
+	$(VENV)/ruff check src/ tests/
+
+fmt:
+	$(VENV)/ruff format src/ tests/
+
+typecheck:
+	$(VENV)/pyright src/
+
+check: lint typecheck test
+
+hooks:
+	@echo '#!/bin/sh\nmake check' > .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit
+	@echo "pre-commit hook installed: runs make check before every commit"

codeatrium-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: codeatrium
+Version: 0.1.0
+Summary: Memory palace for AI coding agents — index sessions, recall code context in <0.2s
+Project-URL: Homepage, https://github.com/senna-lang/codeatrium
+Project-URL: Repository, https://github.com/senna-lang/codeatrium
+Project-URL: Issues, https://github.com/senna-lang/codeatrium/issues
+Author-email: senna-lang <senna-lang@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,cli,code-context,coding-agent,conversation-history,developer-tools,memory,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: tree-sitter-go<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-python<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-typescript<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter<0.24.0,>=0.23.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Codeatrium
+
+[![CI](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml/badge.svg)](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codeatrium)](https://pypi.org/project/codeatrium/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A **memory palace** for AI coding agents.
+
+English · [日本語](README.ja.md)
+
+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](https://en.wikipedia.org/wiki/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](https://arxiv.org/abs/2603.13017) for coding agents.
+
+> **Note:** Currently [Claude Code](https://docs.anthropic.com/en/docs/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
+
+<img src="assets/interface.en.svg" alt="Simple Interface" width="800">
+
+## How It Works
+
+<img src="assets/architecture.svg" alt="Codeatrium Architecture" width="800">
+
+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
+
+```bash
+pipx install codeatrium
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Initialize in project root
+loci init
+
+# Install hooks for automatic indexing
+loci hook install
+```
+
+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?** — Choose No to defer to the next session start
+
+## 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
+
+| Command | Description |
+|---------|-------------|
+| `loci init` | Initialize `.codeatrium/` in project root |
+| `loci index` | Index new session logs |
+| `loci distill [--limit N]` | Distill undistilled exchanges via LLM |
+| `loci search "query" --json` | Semantic search (agent-facing) |
+| `loci context --symbol "name" --json` | Code symbol → past conversations |
+| `loci show "<ref>" --json` | Retrieve verbatim conversation |
+| `loci status` | Show index state |
+| `loci server start/stop/status` | Embedding server management |
+| `loci hook install` | Register hooks in Claude Code settings |
+
+## Automation (Claude Code Hooks)
+
+After `loci hook install`, everything runs automatically:
+
+| Hook | Trigger | Command |
+|------|---------|---------|
+| Stop (async) | After every turn | `loci index` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci prime` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci server start` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci distill` |
+
+- **`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
+
+```json
+[
+  {
+    "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`):
+
+```toml
+[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

codeatrium-0.1.0/README.ja.md

@@ -0,0 +1,147 @@
+# Codeatrium
+
+[![CI](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml/badge.svg)](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codeatrium)](https://pypi.org/project/codeatrium/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[English](README.md) · 日本語
+
+AI コーディングエージェントに**記憶の宮殿**を。
+
+Codeatrium は過去の会話を *palace object* に蒸留し、検索可能なインデックスに保存することで、エージェントに長期記憶を与えます。過去の意思決定・実装・コード位置を 0.2 秒で想起できます。
+
+CLI コマンド `loci`（[Method of Loci＝記憶の宮殿](https://ja.wikipedia.org/wiki/%E5%A0%B4%E6%89%80%E6%B3%95)に由来）は**エージェント自身が呼び出す**ことを想定しています。`loci search "..." --json` をプロンプト内から実行します。
+
+アーキテクチャは [arXiv:2603.13017](https://arxiv.org/abs/2603.13017) の会話記憶モデルを、コーディングエージェント向けに拡張したものです。
+
+> **Note:** 現在は [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 専用です。セッションログ形式（`.jsonl`）と蒸留（`claude --print`）が Claude Code に依存しています。
+
+## シンプルなインターフェース
+
+エージェントが使用するコマンドは基本２つ。
+
+- **セマンティック検索** — `loci search "クエリ"` でセマンティック類似度から過去の会話を検索
+- **コードから逆引き** — `loci context --symbol "名前"` で特定のコードシンボルに関する過去の会話を想起
+  - tree-sitter（Python / TypeScript / Go）のシンボル解決により、エージェントは実装意図・背景を把握できる
+
+<img src="assets/interface.ja.svg" alt="Simple Interface" width="800">
+
+## 仕組み
+
+<img src="assets/architecture.svg" alt="Codeatrium Architecture" width="800">
+
+1. **Index** — エージェントのセッションログを exchange（ユーザー発話 + エージェント応答のペア）に分割し、FTS5 でキーワード検索可能にする
+2. **Distill** — LLM（`claude --print`、デフォルトは `claude-haiku-4-5`）が各 exchange を palace object に要約: `exchange_core`（何をしたか）、`specific_context`（具体的な詳細）、`room_assignments`（トピックタグ）。tree-sitter で触れたファイルをシンボルレベル（関数・クラス・メソッド + ファイル + 行 + シグネチャ）に解決
+3. **Search** — 会話原文の BM25 と蒸留済み埋め込みの HNSW を RRF で融合するクロスレイヤー検索
+
+会話原文は埋め込まず、蒸留で濃縮されたテキストのみを `multilingual-e5-small`（384次元）で埋め込むことで、セマンティック検索の精度と埋め込みコストを両立しています。埋め込みモデルは **Unix ソケットサーバー**で常駐し、初回以降の検索は **0.2 秒以内**で返ります。
+
+## インストール
+
+```bash
+pipx install codeatrium
+```
+
+Python 3.11 以上が必要です。
+
+## クイックスタート
+
+```bash
+# プロジェクトルートで初期化
+loci init
+
+# 自動インデックスのフックをインストール
+loci hook install
+```
+
+`loci init` を実行すると、過去のセッションログが検出された場合に以下の質問が表示されます:
+
+> [!IMPORTANT]
+> 途中からこのツールを導入する場合、すでに大量の exchange が蓄積されています。全件蒸留すると `claude --print` (Haiku) のトークンが大量に消費されるため、まずは `Skip all` か `Distill last 50` で始めることを推奨します。
+
+1. **Min chars threshold** — exchange の最小文字数フィルタ（デフォルト: 50文字）。この閾値で蒸留の母数（対象 exchange 数）が決まります。値を大きくすると短い会話が除外され蒸留対象が減り、小さくするとほぼ全ての会話が蒸留対象になりトークン消費が増えます。
+2. **既存 exchange の扱い** — 過去のセッションをどこまで蒸留するか選択:
+   - Skip all（過去のセッション蒸留なし）
+   - Distill last 50（直近の履歴のみ）
+   - Distill all（全件、トークン消費あり）
+   - Custom（件数を指定）
+3. **蒸留を今すぐ実行するか** — No を選ぶと次回セッション開始時に自動実行されます
+
+## エージェント向けインストラクション
+
+エージェントへのインストラクションは自動挿入されるので手動で書く必要はありません:
+
+- **`loci init`** — `CLAUDE.md` にマーカー付きセクション（`<!-- BEGIN CODEATRIUM -->...<!-- END CODEATRIUM -->`）を挿入。
+- **`loci prime`** — SessionStart Hook で毎セッション開始時にコマンドの使い方をコンテキストウィンドウに動的注入
+
+## CLI コマンド
+
+| コマンド | 説明 |
+|---------|------|
+| `loci init` | プロジェクトルートに `.codeatrium/` を初期化 |
+| `loci index` | 新しいセッションログをインデックス |
+| `loci distill [--limit N]` | 未蒸留の exchange を LLM で蒸留 |
+| `loci search "クエリ" --json` | セマンティック検索（エージェント向け） |
+| `loci context --symbol "名前" --json` | コードシンボル → 過去の会話 |
+| `loci show "<ref>" --json` | 会話原文を取得 |
+| `loci status` | インデックス状態を表示 |
+| `loci server start/stop/status` | 埋め込みサーバー管理 |
+| `loci hook install` | Claude Code の設定にフックを登録 |
+
+## 自動化（Claude Code フック）
+
+`loci hook install` 後、すべて自動で動作します:
+
+| フック | トリガー | コマンド |
+|--------|---------|---------|
+| Stop (async) | 毎ラリー後 | `loci index` |
+| SessionStart | 起動時 / `/clear` / `/resume` / `compact` | `loci prime` |
+| SessionStart | 起動時 / `/clear` / `/resume` / `compact` | `loci server start` |
+| SessionStart | 起動時 / `/clear` / `/resume` / `compact` | `loci distill` |
+
+- **`loci index`** — 毎ラリー後に非同期で実行。セッション途中でも差分のみインデックスするので高速
+- **`loci distill`** — セッション開始時に未蒸留の exchange を `claude --print` で蒸留。ユーザーの Claude Code で Haiku を呼び出します（デフォルト: `claude-haiku-4-5`）
+- **`loci server start`** — 埋め込みモデル（約500MB）をメモリに常駐させ、以降の検索を 0.2 秒以内に
+
+## 検索出力
+
+```json
+[
+  {
+    "exchange_core": "pool_size=5 でコネクションプールを追加した",
+    "specific_context": "pool_size=5, max_overflow=10",
+    "rooms": [
+      { "room_type": "concept", "room_key": "db-pool", "room_label": "DB コネクションプーリング" }
+    ],
+    "symbols": [
+      { "name": "create_pool", "file": "src/db.py", "line": 42, "signature": "def create_pool(...)" }
+    ],
+    "verbatim_ref": "~/.claude/projects/.../session.jsonl:ply=42"
+  }
+]
+```
+
+## 設定
+
+`.codeatrium/config.toml`（`loci init` で生成）:
+
+```toml
+[distill]
+model = "claude-haiku-4-5-20251001"   # 蒸留に使うモデル（デフォルト）
+batch_limit = 20                       # 1回あたりの蒸留上限
+
+[index]
+min_chars = 50                         # この文字数未満の exchange をスキップ
+```
+
+## Acknowledgments
+
+Palace object モデル、room ベースのトピックグルーピング、BM25+HNSW 融合検索は以下の論文に基づいています:
+
+> *Structured Distillation for Personalized Agent Memory*
+> (arXiv:2603.13017)
+
+
+## ライセンス
+
+MIT

codeatrium-0.1.0/README.md

@@ -0,0 +1,147 @@
+# Codeatrium
+
+[![CI](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml/badge.svg)](https://github.com/senna-lang/Codeatrium/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codeatrium)](https://pypi.org/project/codeatrium/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A **memory palace** for AI coding agents.
+
+English · [日本語](README.ja.md)
+
+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](https://en.wikipedia.org/wiki/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](https://arxiv.org/abs/2603.13017) for coding agents.
+
+> **Note:** Currently [Claude Code](https://docs.anthropic.com/en/docs/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
+
+<img src="assets/interface.en.svg" alt="Simple Interface" width="800">
+
+## How It Works
+
+<img src="assets/architecture.svg" alt="Codeatrium Architecture" width="800">
+
+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
+
+```bash
+pipx install codeatrium
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Initialize in project root
+loci init
+
+# Install hooks for automatic indexing
+loci hook install
+```
+
+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?** — Choose No to defer to the next session start
+
+## 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
+
+| Command | Description |
+|---------|-------------|
+| `loci init` | Initialize `.codeatrium/` in project root |
+| `loci index` | Index new session logs |
+| `loci distill [--limit N]` | Distill undistilled exchanges via LLM |
+| `loci search "query" --json` | Semantic search (agent-facing) |
+| `loci context --symbol "name" --json` | Code symbol → past conversations |
+| `loci show "<ref>" --json` | Retrieve verbatim conversation |
+| `loci status` | Show index state |
+| `loci server start/stop/status` | Embedding server management |
+| `loci hook install` | Register hooks in Claude Code settings |
+
+## Automation (Claude Code Hooks)
+
+After `loci hook install`, everything runs automatically:
+
+| Hook | Trigger | Command |
+|------|---------|---------|
+| Stop (async) | After every turn | `loci index` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci prime` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci server start` |
+| SessionStart | startup / `/clear` / `/resume` / `compact` | `loci distill` |
+
+- **`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
+
+```json
+[
+  {
+    "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`):
+
+```toml
+[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