lociaction 0.1.0__tar.gz

lociaction-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Test & lint caches
+.pytest_cache/
+.ruff_cache/
+
+# Tool data (local only)
+.lociaction/
+.logosyncx/
+
+# Claude Code local settings
+.claude/
+
+# Internal docs (local only, not part of the public OSS repo)
+docs/internal/
+docs/design/
+.strata/
+
+# OS
+.DS_Store

lociaction-0.1.0/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- `loci eval gate` (issue #37) is a CI regression gate for symbol-recall.
+  It builds a tiny synthetic git+`code_edges` fixture (no network, no
+  embeddings, no dogfood corpus) and fails if MRR@10 drops more than an
+  absolute 0.01 against committed `src/lociaction/eval/baseline.json`.
+  Keyword-recall (BM25/HNSW/RRF) remains out of scope.
+
+- `loci status` now surfaces the most recent distill per-row failure
+  (`exchange_id`, message, timestamp) from `meta` when one has been
+  recorded; the field/section is omitted when nothing failed.
+
+- `loci recall --file X --branch Y --json` (issue #33) is a session-start
+  warmup that merges code-anchored `context` lookup with `search_combined`
+  into one deduplicated response (`exchange_core` / `specific_context` /
+  `verbatim_ref`). `--file` and `--branch` are independent AND filters.
+  Ranking applies an opt-in exponential recency decay
+  (`search_combined(..., recency_half_life_days=)`, default half-life 14 days
+  on `loci recall` only; existing `search()`/`context()` ranking is unchanged)
+  using `code_edges.ts` with `conversations.started_at` as fallback.
+
+- `loci gc` (issue #30) snapshots the database, removes only orphaned
+  palace/vector and exchange/session records, retains bounded `.bak` archives,
+  and compacts the database with `VACUUM`.
+
+- `loci hook install`/`uninstall --harness omp-pi|opencode|grok` now write real
+  native hooks (issue #40): `OmpPiHooks`/`OpenCodeHooks` generate a marker-owned
+  `~/.omp/agent/extensions/lociaction.ts` / `~/.config/opencode/plugins/lociaction.ts`
+  plugin file (`DedicatedFileWriter`), and `GrokHooks` merges into a dedicated
+  `~/.grok/hooks/lociaction.json` (`MergedJsonHookWriter`, shared with the new
+  `CodexHooks`). All three previously always failed via `FallbackHooks`, which
+  remains the safety net for unrecognized harnesses.
+
+### Changed
+- Database schema v14 removes unused `vec_exchanges`, obsolete
+  `code_touches.symbol_name`/`resolved_by`, and duplicate `symbols` storage.
+  Existing live legacy symbol relations migrate to `code_symbols` plus
+  `code_edges` before the old table is dropped.
+
+- Lifecycle event → loci command mapping (`Stop`→`index`, `SessionStart`→
+  `server start`/`distill`/`prime`, compact→`prime`) is now a single source of
+  truth: `lociaction.adapters.harness.lifecycle.lifecycle_commands(harness,
+  batch_limit)`. `ClaudeHooks`/`CodexHooks`/`GrokHooks`/`OmpPiHooks`/
+  `OpenCodeHooks` all derive their commands from it instead of re-deriving
+  the mapping per harness (`lociaction.hooks.install_hooks`/`uninstall_hooks`
+  keep their Claude-specific JSON-merge/idempotency logic, only the command
+  strings themselves are now sourced from the shared helper). One observable
+  side effect: Claude's `Stop` hook now runs `loci index --harness claude`
+  instead of the previous bare `loci index` (which implicitly swept every
+  detected harness on each Claude turn), matching the scoping Codex already had.
+- `DedicatedFileWriter` uninstall only ever deletes files carrying its own
+  `LOCIACTION_HOOK_MARKER`; files without the marker (other tools' extensions/
+  plugins sharing the same auto-discovered directory) are left untouched on
+  both install (no clobber) and uninstall (no delete).
+
+### Fixed
+
+- `loci search`'s KNN→filter ordering and branch matching (issue #18):
+  - `search_hnsw_palace` cut the sqlite-vec KNN candidate pool to exactly
+    `limit` *before* applying the `min_exchanges`/`branch` filters, so a
+    branch- or activity-filtered query could silently drop to zero results
+    even when relevant matches existed just outside the initial top-K. The
+    candidate pool is now widened adaptively: it starts at `limit * 5`, and
+    if filtering leaves fewer than `limit` results while unexplored candidates
+    remain in `vec_palace`, the pool doubles and the query retries (bounded by
+    a `2000`-candidate hard cap so worst-case ANN cost stays finite even under
+    a highly selective filter). The final result count is still enforced with
+    an outer `LIMIT`.
+  - `search_bm25`/`search_hnsw_palace`'s `branch` filter interpolated the
+    user-supplied branch string into a `LIKE '%...%'` pattern unescaped, so
+    literal `%`/`_` in the query were interpreted as SQL wildcards (e.g.
+    `main` incorrectly matching `maintenance`/`feat/main-x`). Wildcard
+    characters are now escaped (new `lociaction.utils.escape_like`) and the
+    clause carries an explicit `ESCAPE '\\'`; substring matching on
+    non-wildcard input is unchanged.
+- Embedding server lifecycle races (issue #16): `loci server start` now serializes
+  the check→spawn→ready-wait sequence behind a process-wide `server.lock`
+  (`fcntl.flock`), eliminating double-spawn/orphaning under concurrent sessions.
+  `run_server` pings an existing socket before binding and refuses to clobber a
+  live server. `loci server status` is now strictly read-only and never deletes
+  a busy-but-unresponsive socket. `Embedder` serializes `model.encode` calls
+  across threads (`SentenceTransformer` inference is not thread-safe). The
+  embedder server now removes its PID file on idle-timeout/stop, not just the
+  socket.
+
+## [0.3.0] - 2026-06-12
+
+### Added
+
+- Branch linking: exchanges are linked to their git branch at index time.
+- `loci search "query" --branch NAME` — branch-filtered semantic search.
+- `loci context --branch NAME` — reverse lookup from a git branch to past conversations (includes undistilled exchanges).
+- `loci context --full` flag; the default output is now lighter.
+- `loci hook uninstall` — remove lociaction hooks from `settings.json`.
+- SQLite hardening: WAL mode, `busy_timeout`, and a `user_version`-based migration framework.
+- Distillation transactions with `distill_status` and version tracking, plus new indexes.
+
+### Changed
+
+- `loci prime` output rewritten around agent-action triggers with concrete examples.
+- Distillation uses a flock-based lock; embeddings are serialized with `tobytes`.
+- Hook registration writes `settings.json` atomically.
+- Indexing is incremental and reports config errors explicitly.
+
+### Fixed
+
+- Silent data loss in the distillation pipeline; code reverse-lookup works again.
+- Embedding server can no longer double-start; socket protocol hardened and connection leaks fixed.
+- Ply coordinate drift and WAL sidecar file permissions.
+- `loci prime` exits silently when `.lociaction/` is absent; resolving `.lociaction/` from a parent directory now notifies on stderr.
+
+## [0.2.0] - 2026-04-21
+
+### Added
+
+- `loci init --no-hooks` flag to skip automatic Claude Code hook registration.
+- `EmbedderSetupError` exception for environment-level embedder failures (distinguishes them from per-row errors).
+- SVG banner at the top of the README (`assets/banner.svg`, generated via Freeze).
+- `scripts/generate-banner.sh` to regenerate the banner from the live CLI output.
+
+### Changed
+
+- `loci init` now registers Claude Code hooks automatically at the end of setup — previously required a separate `loci hook install` step. Use `--no-hooks` to opt out.
+- Interactive prompts re-prompt on invalid input instead of silently falling back to a default. The "run distillation now?" prompt now accepts `y`/`n`/`yes`/`no` in addition to `1`/`2`.
+- Custom exchange counts are range-validated (`1..total`) and custom `min_chars` requires `>= 0`.
+- Startup banner uses the pagga half-block font with a blue vertical gradient.
+
+### Fixed
+
+- `loci init` cleans up `.lociaction/` automatically if the execution phase fails or is interrupted (`KeyboardInterrupt`), so re-running is safe.
+- A single corrupt `.jsonl` no longer aborts the whole indexing loop — it logs a warning and continues.
+- `git_root()` catches `FileNotFoundError` when the `git` binary is missing.
+- `parse_exchanges` returns `[]` for missing files instead of raising.
+- Distillation failures from `sentence_transformers` import issues (e.g. numpy/pyarrow binary mismatch) now print a single friendly message with remediation hints instead of a full traceback followed by per-row error spam.
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- `loci init` — initialize `.lociaction/` 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

lociaction-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.

lociaction-0.1.0/Makefile

@@ -0,0 +1,25 @@
+VENV := .venv/bin
+
+# ruff: prefer the project venv, fall back to `uvx ruff` when no venv is present
+RUFF := $(shell [ -x .venv/bin/ruff ] && echo .venv/bin/ruff || echo "uvx ruff")
+
+.PHONY: test lint fmt typecheck check hooks
+
+test:
+	$(VENV)/pytest tests/ -v
+
+lint:
+	$(RUFF) check src/ tests/
+
+fmt:
+	$(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"

lociaction-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: lociaction
+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/lociaction
+Project-URL: Repository, https://github.com/senna-lang/lociaction
+Project-URL: Issues, https://github.com/senna-lang/lociaction/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: tomli-w>=1.0.0
+Requires-Dist: tree-sitter-c-sharp==0.23.0
+Requires-Dist: tree-sitter-go<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-java<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-python<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-ruby<0.24.0,>=0.23.0
+Requires-Dist: tree-sitter-rust<0.23.3,>=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
+
+# Lociaction
+
+<p align="center">
+  <a href="https://github.com/senna-lang/lociaction/actions/workflows/ci.yml"><img src="https://github.com/senna-lang/lociaction/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/lociaction/"><img src="https://img.shields.io/pypi/v/lociaction" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">English · <a href="README.ja.md">日本語</a></p>
+
+An AI coding agent recalls everything it has done through two recall primitives — `loci search` and `loci context` — plus `loci recall`, a session-start convenience command that fuses both. The agent reaches for the right call without hesitation, and restores past decisions, conversations, and exact code locations in under 0.2 seconds.
+
+The CLI command `loci` is designed to be **called by the agent itself** — running `loci search "..." --json` from within a prompt. *(The name comes from the [Method of Loci](https://en.wikipedia.org/wiki/Method_of_loci) — the memory-palace technique. Under the hood, conversations are distilled into "palace objects"; see [How It Works](#how-it-works). The architecture extends the conversational memory model from [arXiv:2603.13017](https://arxiv.org/abs/2603.13017) for coding agents.)*
+
+> **Harnesses:** Claude Code, Codex CLI, Oh My Pi, OpenCode, and Grok session logs are indexed into the same exchange, code-touch, symbol, search, context, and `show` contracts. Distillation is a separate, independent choice — `loci distill` runs the same configured client (`claude-cli`, `codex-cli`, `gemini-cli`, `grok-cli`, `opencode-cli`, `omp-cli`, a local Ollama model, or any OpenAI-compatible endpoint) against every undistilled exchange regardless of which harness produced it.
+
+## Minimal Interface
+
+The recall interface is built from two primitives, plus one composite:
+
+- **`loci search "query"`** — semantic search over past conversations
+- **`loci context`** — reverse lookup, by code symbol (`--symbol "name"`) or git branch (`--branch "name"`)
+  - tree-sitter symbol resolution (Python / TypeScript / Go / Rust / Java / C# / Ruby) lets agents understand implementation intent before editing
+  - `--branch "name"` recalls what was done and discussed on a specific git branch (also available as `loci search "query" --branch "name"`)
+- **`loci recall --file PATH --branch NAME`** — session-start warmup: merges `context` + `search`, recency-ranked, with `--file`/`--branch` combinable as AND filters
+
+That's deliberate. The user here is the agent, and an agent handed a 50-tool palette hesitates, mis-picks, and burns tokens just deciding which to call. With a surface this small — and no MCP tool schemas sitting resident in the context window — the agent reaches for the right call the first time, every time. *(When the full transcript is needed, `loci show "<exchange-id>"` expands a search result to its stored verbatim source.)*
+
+Touching a symbol means recalling what was decided about it — `loci context` reverse-looks-up the exact code location, signature, and the conversation behind it.
+
+## 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** — The configured distill client (default `claude --print` with `claude-haiku-4-5`; see [Configuration](#configuration) for the other five CLI backends and local-model options) 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 lociaction
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Initialize in project root. This creates `.lociaction/` and adds the shared
+# agent reminder to AGENTS.md.
+loci init
+```
+
+`loci init` creates the project-local database, writes the common `AGENTS.md` instruction section, and installs Claude Code hooks unless `--no-hooks` is supplied. Every other supported harness (Codex, Grok, Oh My Pi, OpenCode) also has full native lifecycle hook support — register it explicitly with `loci hook install --harness <name>`. If init fails partway through, `.lociaction/` 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 consumes real tokens against whichever distill client you choose (Claude Haiku by default — see step 4 below for the other options). We recommend starting with `Skip all` or `Distill last 50`.
+
+1. **Min chars threshold** — Minimum character filter applied at index time (default: 50). Shorter exchanges are skipped entirely, which also shrinks the pool of distillation candidates. Higher values exclude short conversations and reduce token usage; lower values include nearly everything. (Distillation applies a separate `min_chars` of 100 — see [Configuration](#configuration).)
+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.
+
+`loci init` also asks once, regardless of past session history:
+
+4. **Distill client selection** — If [`qwen2.5-7b-memory-distiller`](https://huggingface.co/sennaLLMLearner/qwen2.5-7b-memory-distiller) (a Qwen2.5-7B fine-tuned specifically for this task, SFT + ORPO on WildChat-1M) isn't pulled yet, `loci init` first offers to `ollama pull` it (~4.7GB, requires [Ollama](https://ollama.com)). It then lists every *Ready* distill client actually detected on the machine — `claude-cli`, `codex-cli`, `gemini-cli`, `grok-cli`, `opencode-cli`, `omp-cli`, plus the just-pulled `ollama-ft` — and prompts you to pick one (`claude-cli` is recommended by default when present). Only CLIs actually on `PATH` show up; none of this depends on which harness you're currently working in — see the [Configuration](#configuration) note on that. Pass `--no-local-distiller` to skip the Ollama pull offer, or `--distill-client <id>` to select non-interactively (exits with an error if that client isn't Ready — it never silently falls back to another one). If no client is Ready, distillation is left unconfigured; run `loci distill --setup` later.
+
+Invalid input on any prompt re-prompts instead of silently falling back to a default.
+
+## Agent Instructions
+
+`loci init` installs the marker section (`<!-- BEGIN LOCIACTION -->...<!-- END LOCIACTION -->`) in **`AGENTS.md`**, the common instruction source for every supported harness. `loci prime` injects full command usage into a session context when native lifecycle support is available.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `loci init [--distill-client ID]` | Initialize `.lociaction/`, write common `AGENTS.md` instructions, and install Claude hooks (`--no-hooks` to skip, `--no-local-distiller` to skip the Ollama pull offer, `--distill-client` to pick the distill client non-interactively) |
+| `loci index [--harness all\|claude\|codex\|opencode\|omp-pi\|grok]` | Index new session logs; the default indexes every detected harness |
+| `loci distill [--limit N] [--setup]` | Distill undistilled exchanges via the configured client; `--setup` re-runs discover/select and saves the choice |
+| `loci gc` | Snapshot `memory.db` to `.bak`, remove only orphaned palace/vector/session records, retain the current backup plus three archives, then run `VACUUM` |
+| `loci search "query" --json` | Semantic search (agent-facing); add `--branch NAME` to filter by git branch |
+| `loci context --symbol "name" --json` | Code symbol → past conversations (lightweight; add `--full` for verbatim text) |
+| `loci context --branch "name" --json` | Git branch → past conversations (includes undistilled exchanges) |
+| `loci recall --file PATH --branch NAME --json` | Session-start warmup: merge context+search, recency-ranked; `--file`/`--branch` AND-combinable |
+| `loci show "<exchange-id>" --json` | Retrieve a stored exchange by its primary ID |
+| `loci status` | Show index state |
+| `loci prime` | Inject command usage into the session context |
+| `loci server start/stop/status` | Embedding server management |
+| `loci hook install --harness NAME` | Install native lifecycle hooks for one of the five supported harnesses |
+| `loci hook uninstall --harness NAME` | Remove native lociaction lifecycle hooks |
+
+## Harness Lifecycle
+
+| Harness | Transcript source | Native lifecycle |
+|---------|-------------------|-------------------|
+| Claude Code | Project JSONL | `~/.claude/settings.json` |
+| Codex CLI | Global rollout JSONL filtered by recorded cwd | `~/.codex/hooks.json` |
+| Grok | Project streaming JSONL | `~/.grok/hooks/lociaction.json` |
+| Oh My Pi | Project JSONL | `~/.omp/agent/extensions/lociaction.ts` |
+| OpenCode | Local session SQLite | `~/.config/opencode/plugins/lociaction.ts` |
+
+Every supported harness has full native lifecycle integration — no fallback/manual-instructions path exists for any of these five. Turn end maps to `loci index`, session start to `loci server start` + `loci distill` + `loci prime`. Compact handling differs slightly: Claude Code and Codex CLI fold compact into the same session-start trio (their matcher includes `compact`); Grok and OpenCode run only `loci prime` on compact; Oh My Pi has no compact-equivalent event to hook into. `loci hook install/uninstall --harness NAME` manages any of these and never touches another harness's settings.
+
+## 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",
+    "git_branch": "feature/db-pool"
+  }
+]
+```
+
+## Configuration
+
+`.lociaction/config.toml` (generated by `loci init`):
+
+```toml
+[distill]
+client = "claude-cli"                  # Distillation backend — see the full id list below
+model = "claude-haiku-4-5-20251001"    # Model for distillation (client-specific default if omitted)
+batch_limit = 20                       # Max distillations per hook run
+min_chars = 100                        # Skip distillation for exchanges shorter than this
+
+[index]
+min_chars = 50                         # Skip indexing exchanges shorter than this
+```
+
+There are two `min_chars` settings: `[index] min_chars` controls what gets indexed at all, while `[distill] min_chars` further skips distillation (the LLM cost) for short exchanges that were already indexed.
+
+`client` is independent of the harness you're actually working in — `loci distill` runs the one configured client against every undistilled exchange regardless of whether it came from Claude Code, Codex, Grok, OpenCode, or Oh My Pi (see [Harness Lifecycle](#harness-lifecycle)). Valid ids: `claude-cli`, `codex-cli`, `gemini-cli`, `grok-cli`, `opencode-cli`, `omp-cli`, `ollama-ft`, `openai-compat`. The legacy `provider = "claude" | "openai"` + `base_url` form is still read for backward compatibility, but `client` is what `loci init` and `loci distill --setup` write and is the recommended way to configure this by hand too.
+
+### Distilling with a local LLM
+
+Distillation is a small per-exchange structured-extraction task, so a local model is usually good enough. Any OpenAI-compatible endpoint (Ollama, LM Studio, llama.cpp-server, vLLM) works by setting `client = "openai-compat"` with `model` and `base_url` — no new dependencies, no API key (the `Authorization` header is never sent, so this is local-only):
+
+```toml
+[distill]
+client = "openai-compat"
+model = "qwen2.5:7b"
+base_url = "http://localhost:11434/v1"   # Ollama
+# base_url = "http://localhost:1234/v1"  # LM Studio
+```
+
+`openai-compat` requires both `model` and `base_url` to be set — resolving fails otherwise. (If you're pointing this at Ollama's default port with the bundled fine-tuned model, use `client = "ollama-ft"` instead — it already knows the model and endpoint, see [`loci init`](#quick-start).)
+
+`loci init` offers to set this up for you automatically with [`qwen2.5-7b-memory-distiller`](https://huggingface.co/sennaLLMLearner/qwen2.5-7b-memory-distiller), a model fine-tuned specifically for this task (see the prompt above) — no manual config needed if you accept it.
+
+### Distilling with another coding-agent CLI
+
+If you already have [Codex CLI](https://developers.openai.com/codex/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Grok CLI](https://x.ai), [OpenCode](https://opencode.ai), or [Oh My Pi](https://github.com/can1357/oh-my-pi) installed and authenticated, any of them can run distillation instead of `claude --print` — no extra config beyond selecting the client:
+
+```toml
+[distill]
+client = "codex-cli"     # or "gemini-cli", "grok-cli", "opencode-cli", "omp-cli"
+# model = "gpt-5-codex"  # optional override; omit to use the CLI's own configured default
+```
+
+`codex exec --output-schema` and `grok -p --json-schema` constrain the response to the palace-object schema directly (`structuredOutput` unwraps in one step for grok, no wrapper at all for codex). `gemini --prompt --output-format json`, `opencode run --format json`, and `omp -p --mode json` have no schema-constrained mode, so the palace object is parsed out of their free-text/event-stream output the same way `claude --print`'s `result` field is unwrapped. `loci distill --setup` detects all five automatically (PATH presence only, like `claude-cli`) and lists them alongside the other ready clients.
+
+## 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