Nekyia

What it does ​

The context you need is usually in a session you already had. You worked the problem out three weeks ago, in a different directory, possibly in a different client, and the only way back to it is to remember enough of it to search for it. So you describe it to a fresh agent instead and pay for the reasoning twice.

Nekyia searches the transcript stores your agent CLIs already keep on disk, ranks what comes back, and launches the client. Where the exact resume command was tested, it attaches to that session by ID. Where it was not, it starts a fresh session with a handover built from the indexed prompts, the touched files and the branch, and says plainly that it is a brief rather than a recovered state.

That distinction is the whole design. A tool that claims to resume everything and quietly starts something new is worse than one that does less and tells you which it did.

Quick start ​

Nekyia needs Bun 1.1 or newer. It is pre-release and not on npm yet, so it installs from the repository. Both names work: nekyia and the shorter nek.

bun install -g github:AraneaDev/Nekyia
nekyia index

The first run shows what it intends to read and waits for consent before it opens a transcript store or creates an index. --yes skips that prompt once you have looked at the boundary.

Examples ​

Run for real on this machine, abridged with '…'.

What it found:

$ nekyia doctor
clients
  agy           99 sessions  (built-in)
  claude       102 sessions  (built-in)
  codebuff      56 sessions  (built-in)  [partial]
  codex          0 sessions  (built-in)
  kilo           1 sessions  (built-in)
  opencode       2 sessions  (built-in)

index
  264 sessions, 16 size-capped, 1 missing from disk
  size-capped: codebuff:18843754-fafe-4461-bf1a-6b9b878dc4a8
  …

Six clients, one index, and it names the sessions it could not take whole rather than quietly indexing a truncated copy of them. Three of those six resume by ID; the other three get a briefed session, and doctor is where you find out which is which before it matters.

Searching without the picker:

$ nekyia search reconnect race
$ nekyia search reconnect --json      # machine-readable
$ nekyia last                         # newest session under this directory
$ nekyia show <uid>                   # the handover, as Markdown, before you send it

Search is scoped to the current directory by default. --all widens it, --client <id> narrows to one client, and --file <path> finds the sessions that touched a file.

Capabilities ​

The picker is the interactive half. Typing filters as you go and the matching span is lit in every title, so the list answers each keystroke instead of only getting shorter. ctrl+o opens the session under the cursor and gives it the screen: what you asked, what came back, which files moved. tab widens to every directory, and pressing it again narrows to the project of the row you are on, so you can start anywhere and end up somewhere specific. The count beside the search line always names what is being searched, and a query that matches nothing says what to try rather than leaving you on an empty screen.

Everything the picker does is also a command, with --json on the ones worth scripting.

Indexing runs in two phases. Discovery reads bounded metadata and a stable fingerprint per session; hydration runs only for what changed, and commits metadata and search facets to SQLite atomically. Search is FTS5, weighting titles, your prompts and selected assistant prose differently, then blending relevance against a recency half-life. Fork chains collapse to one row.

Tool output is not indexed. Command results and file dumps are large, noisy, and the most likely place for something private to be sitting, and none of that is what you search a session by.

Configuration ​

The index lives at ~/.local/share/nekyia/index.db and the config at ~/.config/nekyia/config.json, both honouring XDG_DATA_HOME and XDG_CONFIG_HOME.

There is no network service, no API key and no telemetry, and the handover is deterministic, so building one makes no model call. What the index does hold is a copy of text that was already on your disk, and that copy outlives the transcript it came from. Three commands control that:

nekyia forget <uid>              # one session, and every facet of it
nekyia prune --missing           # sessions whose source files are gone
nekyia exclude '/work/private/**'  # then: nekyia index --rebuild

It does not promise secret redaction or an encrypted index, so read what show, doctor and --json print before you paste any of it somewhere public.

A client it does not know yet can be described locally: user manifests live in ~/.config/nekyia/clients/*.json, and nekyia doctor --sniff inspects likely stores and scaffolds a draft rather than guessing at a path.