thimiko: Instructions file for Claude Code

thimiko — agent guide

Layered, searchable memory over local Codex, Claude Code, GitHub Copilot, Gemini CLI, Cursor, and OpenCode chat history. See ARCHITECTURE.md for the layer/interface design before changing structure.

Commands

uv sync                          # create .venv + uv.lock
uv run thimiko build              # full rebuild of the index (default: %LOCALAPPDATA%\thimiko\thimiko.sqlite)
uv run thimiko update [--prune]   # incremental: only changed/new files; --prune drops deleted files' sessions
uv run thimiko search "query"     # BM25 ranked search; JSON by default (--text for humans, --days N for recency)
uv run thimiko list [-v]          # supported sources + roots; -v adds indexed/on-disk chat counts
uv run thimiko mcp                # launch the MCP server over stdio

--db PATH overrides the index location on any subcommand.

Invariants (don't break these)

• Never merge providers' raw schemas — normalize into the canonical Session/Event model only. See ARCHITECTURE.md.
• Every Event carries a Provenance (source file + line). Never lose that link — it's how get_turn/get_session point back to the raw record.
• Only ordinary user/assistant Messages are searchable. Hidden reasoning, tool calls/results, and attachments stay out of the default search corpus.
• FTS5 (documents_fts) is kept in sync via triggers on documents, not a manual reindex step — if you touch SqliteStore, insert/delete through documents, don't write to documents_fts directly.
• Store, Retriever, and ChatSource are ABCs for a reason: code above a layer must depend only on the interface (e.g. cli.py/mcp.py never import sqlite3 directly).
• Provider databases are inputs, never index targets. In particular, opencode.db must only be opened read-only as a source; --db always names Thimiko's separate derived SQLite index.
• Capture ChatSource.fingerprint() before parsing and record that exact value. OpenCode combines its main database and WAL so concurrent writes remain visible to the next update.