Ataru: a local index for AI agent transcripts, with a Rust search core and a Tauri GUI

The problem Ataru addresses: past agent sessions that nobody can find again

The README states the premise directly: valuable answers often already exist in earlier AI coding sessions, whether a debugging trail, a key command, an architecture trade-off, or context discussed weeks ago. Those artifacts sit in per-agent local transcript files under different formats, and the README argues that memory, directory names and manual scanning are poor ways to relocate them. Ataru's stated goal is not to manage a running agent but to make past work usable again. That framing matters for scoping. This is a retrieval layer over history, not an orchestration tool, not an agent runtime, and not a memory store that writes back into a model's context window. The intended users are people who run Claude CLI, Claude App or Web, and Codex, and who want a single index across those sources. The README's capability table lists unified collection, incremental indexing, Chinese-friendly full-text search, hybrid recall, hierarchical aggregation, context read-back, and agent access as the seven things it does. Each maps to a specific frustration: format drift across sources, rescanning everything on each query, tokenisation that breaks on Chinese text or package names, and truncated summaries that lose the original line.

How the retrieval pipeline is assembled: adapters, Tantivy, an optional vector store

The architecture diagram shows a modular monolith with a public boundary and a core. On the public side sit api (validation, orchestration, fallback), sdk (v2 request and response shapes, stable IDs), and the Turn/Run/Session/Project aggregation layer. On the core side sit source adapters for Claude, Codex and a legacy path, the ingestion and indexing pipeline with manifest, incremental and reconcile stages, and an ai module handling intent, semantic recall and RRF fusion. Local transcript files flow through adapters into ingestion, which writes to two stores: a Tantivy plus Jieba keyword index, and an optional SQLite vector store. The embedding provider is marked as explicit opt-in in the diagram, reached by a dotted edge from the ai module. The api layer then reads raw context (message, line, deep link) and hands it to sdk. Two design choices are visible here. First, the fallback logic lives in api rather than in each client, so degradation from semantic to keyword is a single code path. Second, the Skill is explicitly not a second index: the README says it does not scan ~/.claude or ~/.codex, does not parse JSONL, and does not keep its own cache, and that it does not copy the ranking algorithm. Everything it reports comes from the api contract. That keeps GUI, CLI and Skill behaviour aligned, which is the failure mode the README calls out when it warns against three different behaviours across clients.

Turning it on: the first-run index check and the commands that drive it

The desktop path starts with a download from GitHub Releases. On first use, the README describes a four-step sequence: read the index manifest and schema version; if the index is missing, stale, or in an idle state, start one index build; report progress through the search-index:build event; and only execute queries once the state is ready. The README notes that the index is derived data, that it does not rewrite the original sessions, and that a failed rebuild preserves the last healthy index. For a local development build, the documented commands are git clone --recursive, cd Ataru, pnpm install, then pnpm dev:app, with pnpm dev and pnpm dev:app:no-watch for the modes that skip the Rust auto-restart. For headless or agent use, the README shows Tauri invoke calls: get_search_index_status first, then start_search_index_build with force set to false if the state is not ready, waiting on the search-index:build event until the state is ready or error. The search call is invoke("ataru_search") with a request object carrying query, level, mode and limit, where level is one of turn, run, session or project and mode is one of auto, keyword, semantic or hybrid. Two installable Skills are published as npx lovstudio skills add ataru-indexing and npx lovstudio skills add ataru-search, driven by scripts/ataru_index.py and scripts/ataru_recall.py.

The keyword-only CLI, the 180-second timeout, and a version gate that exists for a reason

The limitations are stated in the README rather than buried. The CLI supports keyword mode only, so a Skill-driven search always returns mode as keyword and semanticAvailable as false; semantic or hybrid recall requires the desktop app. That is a hard boundary, not a configuration gap. The published Skills also refuse to run against an unready index, returning ATARU_INDEX_NOT_READY or ATARU_INDEX_BUILDING rather than reporting an empty result set. This is a deliberate choice to avoid disguising a missing index as zero hits, and it means a headless runner must implement the ensure_index step itself; the desktop search page does it automatically, but the README says an independent Skill or headless runner must do it explicitly. The version gate is the most telling detail. The Skill wrapper parses the binary and requires version 0.41.3 or higher, because older builds fall through CLI arguments into opening a desktop window. That is a real upgrade hazard for anyone pinning an older release. On latency, the README reports that on a corpus of 2705 sessions, 847526 messages and a 6.6GB index, a turn-level query takes roughly 48 seconds, which is why the Skill defaults to a 180-second timeout and 300 seconds for read operations. Those numbers come from the project's own description; treat them as a starting point for your own measurement, not a guarantee, and note that they describe turn-level queries specifically.

Where Ataru is the wrong tool, and what a different approach looks like

If you need semantic recall from a script, a CI job, or an agent that cannot open a GUI, Ataru's CLI path will not serve you: keyword only, with semanticAvailable reported as false. If your corpus is small enough that grep over transcript files returns an answer in under a second, the indexing pipeline, the manifest, the schema-version check and the rebuild cost are overhead you are paying for nothing. If you need memory that is written back into a live agent's context automatically, Ataru does not do that; the README is explicit that it does not manage running agents. A different approach in the same problem space is a hosted memory service that stores conversation turns in a remote vector database and exposes a retrieval API. The difference is not just deployment. A hosted vector store typically makes semantic similarity the primary retrieval path, which means embeddings must be generated for every stored turn, either at write time or on a schedule. Ataru inverts that: Tantivy plus Jieba keyword search is the default, embeddings are an explicit opt-in edge in the architecture diagram, and when semantic recall is unavailable or times out, the api layer degrades to keyword with ATARU_*_FALLBACK warnings preserved in the response. The trade-off is that Ataru's default recall quality depends on lexical matching, including for Chinese text where Jieba segmentation is doing the work, while a vector-first system depends on embedding quality and on the cost of generating and storing vectors. Ataru also keeps raw context reachable through stable IDs and line numbers; a vector store that returns only a chunk and a similarity score gives you less to navigate back to.

Index maintenance, schema versions and the Apache-2.0 terms

The maintenance surface is the index itself. Because the manifest carries a schema version and the first-run check treats a mismatched or stale index as a trigger for a build, a schema change in a new release means a rebuild rather than a silent misread. The README states that ingestion supports incremental catch-up after new messages are written, so routine operation should not require a full rescan, and that a failed rebuild leaves the previous healthy index in place. The project also ships a Skill for estimating semantic index cost, which suggests embedding spend is a real consideration when the vector path is enabled. Release cadence is visible in the metadata: v0.41.6 arrived on 2026-08-24, one day after v0.41.5 and two days after v0.41.4. That is a fast patch rhythm, and combined with the 0.41.3 version gate in the Skill wrapper, it means pinning a version and checking it deliberately is worth the effort. On licensing, the repository is Apache-2.0. That permits commercial use and modification and includes an express patent grant, with the usual obligations around preserving notices and stating changes. It is not legal advice; if you plan to redistribute a modified Ataru or embed the search core in a product, read the licence text and your own counsel's guidance rather than this summary.

Who should adopt Ataru, and what to check before you do

Adopt it if you run Claude or Codex locally, your session history has grown past the point where you can find things by remembering which project directory it was in, and you want the retrieval to stay on the machine by default with semantic recall as an opt-in rather than a requirement. The four-level aggregation is the feature most likely to decide it for you: being able to collapse the same hit across Turn, Run, Session and Project granularity, then jump back to the original message and line number through a stable ID, is a different workflow from reading truncated snippets. Do not adopt it if your access path is headless and you need semantic or hybrid results, or if a 48-second turn-level query on a multi-gigabyte index is beyond your patience threshold, since the desktop path is where semantic recall lives. Before committing, verify three things against your own environment. Check that the binary reports 0.41.3 or higher, because the Skill wrapper gates on that and older builds open a window instead of running the CLI. Confirm which transcript directories the Claude, Codex and legacy adapters actually read on your platform, since the README names the sources but the paths are not enumerated in the material available here. And run one full build on your own corpus to see the real index size and query latency, because the published 2705-session, 847526-message, 6.6GB figures describe the maintainers' corpus, not yours.

Editorial conclusion

Ataru fits engineers who already accumulate Claude or Codex session files and want to re-find a past fix, command or design decision without leaving the machine. It does not fit anyone who needs semantic recall from a headless runner, since the JSON CLI is keyword only and the Skill reports semanticAvailable as false, nor anyone unwilling to wait on index builds: the README cites about 48 seconds for a turn-level query over 2705 sessions and 847526 messages. Before adopting, verify the binary reports at least 0.41.3, confirm which local transcript directories the source adapters actually read on your platform, and measure a rebuild on your own corpus rather than trusting the published figure.

Official sources

1. License: Apache-2.0
2. lovstudio/Ataru on GitHub
3. Project website
4. README
5. Releases