zikaron 0.1.0__tar.gz → 0.3.0__tar.gz

{zikaron-0.1.0/zikaron.egg-info → zikaron-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zikaron
-Version: 0.1.0
+Version: 0.3.0
 Summary: Memory and searchable project knowledge for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nathan-shapiro/Zikaron
@@ -124,7 +124,7 @@ reads which one it is addressing before it reads a description. Consolidation ne
 | **service** | A long-running process per project. Holds the embedding model in memory and the databases open, and answers requests over a Unix socket. Starts itself when needed and stops itself when idle. |
 | **MCP server** | Translates the agent's tool calls into requests to the service. One process per agent instance; loads no model. |
 | **hook** | A single-shot executable your agent runs on start, before each message, and — under Claude Code — when it spawns a subagent. Deliberately tiny; loads no model and never touches the databases directly. |
-| **indexer** | A detached process started per knowledge-base build — by the service when an agent asks, or by the `zikaron.knowledge` command when you do. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
+| **indexer** | A detached process started per knowledge-base build — by the service on every `add`/`refresh`, whether an agent asked or you did, or by you running the foreground command a build result prints. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
 
 The service exists for one measured reason: loading the embedding model costs about **780 ms**, and
 retrieval sits on the path of every message you send. Keeping the model resident turns that into a
@@ -161,16 +161,21 @@ and never fails your turn.
   which harness a project is for from the project itself (a `.claude/` or a `.kiro/` directory),
   falls back to the `CLAUDECODE` marker when the project says nothing, and **refuses — telling you
   to name the harness — when the project names both, or when neither the project nor the marker
-  says**. Under kiro it additionally validates the consolidator's model id against the binary,
-  because kiro substitutes an unknown model silently; Claude Code refuses one itself, at
-  spawn, so no such check is needed there.
+  says**. `CLAUDECODE` reaches the processes a session spawns, so a **Claude Code** agent asked to
+  run the installer is detected; kiro exports no marker, so there it is a `.kiro/` in the project or
+  nothing. A person running it from a terminal outside a session, into a project that has not been
+  set up yet, is the case where nothing says anything and `--harness` is required.
+
+  Under kiro it additionally validates the consolidator's model id against the binary, because kiro
+  substitutes an unknown model silently; Claude Code refuses one itself, at spawn, so no such check
+  is needed there.
 
 ## Install
 
 **Two supported paths, and the first is recommended for a reason worth reading.**
 
 ```bash
-# Recommended. `--managed-python` is not optional; the paragraph below says why.
+# Recommended. `--managed-python` is not optional; "Why `uv` is recommended" below says why.
 uv tool install --managed-python zikaron
 ```
 
@@ -179,6 +184,11 @@ uv tool install --managed-python zikaron
 uv tool install --managed-python git+https://github.com/nathan-shapiro/Zikaron.git
 ```
 
+Both of those need [`uv`](https://docs.astral.sh/uv/) and **no Python**, which is the point; the
+`git+` form also needs `git` on `PATH`, which `uv` calls rather than bundles. `uv`'s own installer is
+`curl -LsSf https://astral.sh/uv/install.sh | sh`, and on a stripped-down image you may have to
+install `curl` and `ca-certificates` before that line will run.
+
 ```bash
 # Alternative — a source checkout on a Python you already have.
 git clone https://github.com/nathan-shapiro/Zikaron.git
@@ -218,44 +228,88 @@ goes bad on disk *afterwards* is `zikaron doctor`'s to find rather than startup'
 64 MB on every start costs more of the push hook's budget than it is worth, which is measured in
 `design/distribution.md` §"Model acquisition". `zikaron doctor` reports which state your cache is in.
 
-Then install into the project you want Zikaron in:
+Then install into the project you want Zikaron in, naming the harness:
 
 ```bash
 cd /path/to/your/project
-zikaron install --project .
+zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
-Under **kiro**, name the config for the agent you actually work in:
+**Name it on a first install, rather than leaving it to be detected.** Detection looks for a
+`.kiro/` or `.claude/` directory in the project and for `CLAUDECODE` in the environment, and it
+refuses rather than guessing when neither says. Running from an ordinary terminal, a first install
+is exactly the case where neither says anything: a Claude Code project has no `.claude/` yet —
+neither the trust dialog nor an ordinary tool use creates one — and `CLAUDECODE` is exported into
+the processes a session spawns, not into a terminal outside one. (Ask a *Claude Code* agent to run
+the installer and detection does succeed, because `CLAUDECODE` reaches it; kiro exports no marker,
+so there it is a `.kiro/` in the project or nothing.)
+
+Under **kiro**, also name the config for the agent you actually work in:
 
 ```bash
-zikaron install --project . --agent .kiro/agents/<your-agent>.json
+zikaron install --project . --harness kiro --agent .kiro/agents/<your-agent>.json
 ```
 
 If `zikaron` is not on your `PATH` — a source checkout whose virtualenv you have not activated —
-every command below also works as `python -m zikaron.<command>`, run with that virtualenv's
-interpreter. `zikaron doctor` has no such form; it is new with the `zikaron` command.
+three commands have a module form you can run with that virtualenv's interpreter, and the spelling
+is not uniform:
 
-Pass `--harness claude-code` or `--harness kiro` to override the detection described under
-[Requirements](#requirements). `--agent` is kiro-only, and passing it under Claude Code is refused
-rather than ignored — there its entries go into fixed project files instead. To see exactly what
-would be written without writing anything, pass `--print-only` on either harness.
+| command | module form |
+|---|---|
+| `zikaron install` | `python -m zikaron.install` |
+| `zikaron knowledge` | `python -m zikaron.knowledge` |
+| `zikaron init` | `python -m zikaron.project` |
+
+`zikaron doctor` and `zikaron --version` have no such form; both are new with the `zikaron` command.
+
+Omitting `--harness` falls back to the detection described under [Requirements](#requirements), which
+refuses rather than guessing when it cannot tell. `--agent` is kiro-only, and passing it under Claude
+Code is refused rather than ignored — there its entries go into fixed project files instead. To see
+exactly what would be written without writing anything, pass `--print-only`; it previews past an
+absent harness binary or an unvalidated model, and says so — but it still has to know *which*
+harness, so pass `--harness` alongside it exactly as a real install would.
+
+**Re-run the installer after you upgrade the package.** Upgrading replaces the code, not what an
+earlier version wrote into your project, and a release can change a merged entry — `alwaysLoad` is
+one such change. On both harnesses re-running upgrades those entries in place and needs no
+`--force`; it refuses only where another Zikaron install owns something, or, under Claude Code,
+where you have added a hook of your own inside Zikaron's group (both below), which is what `--force`
+exists for. `zikaron doctor` afterwards says whether a Claude Code project's Zikaron entries carry
+`alwaysLoad` — the one thing about `.mcp.json` it judges.
+
+**What upgrading the package does not do by itself:**
+
+- **A service already running keeps the old code** until it idles out (`idle_timeout`, below) or is
+  stopped — `pkill -f zikaron.service.main`. Until then `zikaron knowledge` may be refused with a
+  `bounds` error naming a field you never typed: that is the older service not knowing the newer
+  command.
+- **A store moves forward, never back.** The first time a newer service opens a project's store it
+  migrates it in one transaction, without saying so, and an older Zikaron then refuses that store —
+  `0.1.0` cannot open one `0.3.0` has opened. If more than one environment serves the same project,
+  upgrade them together.
 
 Finally, if the project is a git repository, tell git to ignore the store — and, under Claude Code,
 the MCP config too:
 
 ```bash
 echo '.zikaron/' >> .gitignore
-echo '.mcp.json' >> .gitignore     # Claude Code only; see below
+echo '.mcp.json*' >> .gitignore    # Claude Code only; see below
 ```
 
+**The `*` covers `.mcp.json.bak`**, the copy the installer takes of `.mcp.json` before the first
+merge that finds none there (the backup rule is below). It sits at the repository root and holds the
+file as it then stood — the same absolute paths, and whatever the entry held at the time, an `env`
+included — and it is where `--force` sends you to look for a key it dropped.
+
 **`.mcp.json` is the awkward one.** Claude Code intends that file to be committed and shared — that
 is what "project-scoped" means — but the entries Zikaron writes into it name absolute paths inside
 *your* virtualenv, so a clone-mate gets a server that cannot start, plus an approval prompt for it.
 This is the same objection that keeps the hook entries out of the checked-in `settings.json`; the
 difference is that `settings.local.json` exists as an untracked sibling and `.mcp.json` has no
 equivalent. With no per-project, machine-local MCP scope to move it to, the choice is yours: ignore
-the file, or accept that each clone re-runs the installer. Re-running is safe — a differing Zikaron
-entry is refused loudly rather than merged over.
+the file, or accept that each clone re-runs the installer. Re-running is safe — an entry naming a
+*different* virtualenv is exactly what the installer refuses loudly rather than merging over, which
+is the clone-mate case.
 
 The installer does not edit `.gitignore` for you; appending to it is not a decision an installer
 should make silently. But it matters and is easy to forget: without it the memory database and its
@@ -278,7 +332,7 @@ and under **Claude Code**:
 | `.claude/agents/zikaron-consolidator.md` | the consolidation subagent, as frontmatter plus its prompt |
 | `.claude/skills/zikaron-consolidate/SKILL.md` | how to run a consolidation, and how to recover a stuck one |
 | `.claude/settings.local.json` | three hooks — session start, per-message, and per-subagent — plus both approval keys, `enabledMcpjsonServers` and `permissions.allow` |
-| `.mcp.json` | both servers: `zikaron` for your own tools, `zikaron-consolidator` for the consolidation verbs |
+| `.mcp.json` | both servers: `zikaron` for your own tools, `zikaron-consolidator` for the consolidation verbs — each marked `alwaysLoad` so their descriptions are in context from the start rather than fetched per tool |
 
 **`settings.local.json`, not `settings.json`**, and it matters if you commit your settings: the hook
 entries name absolute paths inside *your* virtualenv, so they are meaningless in anyone else's clone.
@@ -288,8 +342,28 @@ spawn, which kiro achieves by firing its ordinary hooks for subagent sessions in
 It backs up any file it merges into (`<file>.bak`, and the first backup wins), and **refreshes a
 shipped file whose contents are not what this version ships** — after backing it up, and saying so.
 That is what makes upgrading work, and the cost is that a hand-edit to a shipped file is reverted on
-the next install rather than kept. Under kiro it also validates the consolidator's model id, because
-an unknown model would otherwise be silently replaced by the harness's default.
+the next install rather than kept. **Under Claude Code the same holds inside a file it *merges*
+into**: a Zikaron hook entry whose command is this install's but whose `timeout` or matcher you
+changed is rewritten, and the install names the trigger so you can re-apply it. Otherwise a new
+default timeout could never reach an existing install. What refuses is an entry naming a *different*
+Zikaron install — or a Zikaron hook group you have added your own second entry to, since the
+installer replaces a group wholesale rather than merging inside one, so refusing is the only way not
+to drop your entry silently. `--force` overrides that, and then says which command of your own it
+dropped.
+
+`.mcp.json` is merged **per key**: a key you added to Zikaron's own entry is kept and named in the
+output, a value this install writes — `alwaysLoad` in particular — is set to this install's and
+named too, whether it was missing or different, and only a different `command` or `--mode` refuses. `--force` is the exception: it
+replaces the entry whole, says which of your keys that dropped, and points you at the `.bak` beside
+the file. It does not say whether the backup has them, because it cannot know — the first backup
+wins, so the `.bak` on disk may have been written before or after you added the key.
+
+Under kiro the same rules hold inside the agent config you name: the `mcpServers` entry merges per
+key, a Zikaron hook entry whose command is this install's is rewritten and its trigger named, and
+only an entry naming a different install's command, or another `--mode`, refuses. A hook of Zikaron's
+on a trigger this install does not write is left alone. Kiro's install also validates the
+consolidator's model id, because an unknown model would otherwise be silently replaced by the
+harness's default.
 
 `@zikaron` has to be in `tools` or Zikaron's tools are simply absent: the `mcpServers` entry
 *configures* the server and `tools` is what *selects* from it. It goes into `allowedTools` too, so the
@@ -361,6 +435,14 @@ consolidator's: a subagent has nobody to answer a permission prompt, so an unapp
 there does not ask, it fails at the moment consolidation needs it. The file read above is the
 exception — that one prompts.
 
+**A subagent that sets its own `tools:` list cannot see Zikaron at all.** Registering a server in
+`.mcp.json` makes it available project-wide, but an agent whose frontmatter carries an explicit
+`tools:` allowlist gets exactly that list — the registration does not add to it. So a correct
+install, a running service and a subagent doing the work can still produce zero memories, with
+nothing anywhere saying why. The install names any such agent it finds and tells you to add
+`mcp__zikaron` to its `tools:`, and `zikaron doctor` reports the same. Your allowlist is a
+deliberate grant, so neither one edits it for you.
+
 **Your own agent can see the four consolidation verbs**, and that is not a misconfiguration. A server
 has to be registered for the whole session before any subagent can reach it, so registering the
 consolidator's server exposes it to you too. Under kiro the two tool sets are separated mechanically;
@@ -380,7 +462,7 @@ global and unregisters the tool, after which the consolidator itself refuses to
 | `--model <id>` | the consolidator's model (default: `claude-sonnet-5` under kiro, `sonnet` under Claude Code) |
 | `--format {object,array}` | **kiro only.** Which hook format to write when the target config has none yet |
 | `--no-trust-tools` | do not pre-approve Zikaron's own tools, so every Zikaron tool call asks permission |
-| `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused |
+| `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused. It also stops merging: a server entry — `.mcp.json`'s, or kiro's `mcpServers` — is replaced **whole**, so a key you added to Zikaron's own entry goes, and under Claude Code a Zikaron hook group is replaced whole, so a hook of your own inside it goes too. Both are named in the output |
 
 Both hook formats kiro accepts are supported, and a config that already uses one keeps it: kiro
 rewrites a config in whichever format it read, so mixing them in one file has no defined meaning.
@@ -408,7 +490,16 @@ It exits non-zero if any check fails. **A model cache that is not there yet is n
 is no prefetch at install time, so a first run reports it as fetched on first use and exits 0. The
 last row reports rather than checks: the linked SQLite version varies between interpreter builds on
 one machine and there is no correct value to compare against, so stating it is the whole point.
-`zikaron doctor --project <dir>` checks another project's socket path.
+Some rows appear only where a project gives them something to check: under Claude Code, whether
+the Zikaron servers in `.mcp.json` carry `alwaysLoad` — an older install lacks it, and a re-install
+fixes that — and which of your subagents cannot reach Zikaron's tools.
+`zikaron doctor --project <dir>` checks another project.
+
+**`zikaron --version` names the version you installed**, which is the first thing to put in a bug
+report; `doctor` reports on the machine and leaves the version to this. A PyPI install reports a
+release. A `git+` install or a source checkout between releases reports a `.dev` version — a `.dev0`
+suffix means "working toward that number, not released" — so it never impersonates a release, but it
+does span every commit until the next bump, and a bug report from one needs the commit as well.
 
 Then start a session with the agent you installed into. On start you should see nothing unusual — the
 write policy goes into the model's context, not to your terminal. Then, from the project directory:
@@ -449,6 +540,7 @@ a knowledge base called design docs"*. It has tools to list, create, rename, ref
 remove them. The same verbs are available at a shell, for when no agent is running:
 
 ```bash
+zikaron init                         # once per project; safe to run twice
 zikaron knowledge list
 zikaron knowledge add "design docs" --path ./design \
     --description "Architecture and design records"
@@ -456,7 +548,21 @@ zikaron knowledge refresh            # every corpus; name one to narrow it
 zikaron knowledge status "design docs"
 ```
 
-Three things are worth knowing before you point one at a directory.
+**`init` comes first because every `knowledge` verb refuses a project with no store**, and it is the
+only command that creates one. In a project your agent has already opened there is a store
+already, and `init` will say so and exit 0 — so putting it at the top of a provisioning script
+costs at most the service start the next command would pay anyway. The **first** `init` — the one
+that creates the store — can outlast the deadline on a cold model cache and exit 1 while the
+service keeps fetching the model; running it again succeeds when the service was only slow, and the
+command points at `.zikaron/service.log` for when it was not.
+
+**They act on the project you run them in.** The directory is resolved as `--project` if you pass
+it, else the harness's own project directory if it exports one, else the directory you are standing
+in — so a command typed a few levels down is a different project from the one your agent uses, and
+saying so is the whole point of the refusal. It names the store it found above you, if there is one,
+and never acts on it.
+
+Three more things are worth knowing before you point a knowledge base at a directory.
 
 **Building takes minutes and runs in the background.** `add` and `refresh` start a build and return.
 A **first** build answers nothing at all while it runs: the corpus reports `reindex_required` for
@@ -465,6 +571,13 @@ answering from what is already indexed while it works — as does a `--full` one
 of a rebuild forced by a changed embedding model, which empties the corpus before it starts and so
 answers nothing until it finishes. `status` says how far it has got.
 
+In a script or a CI step, use `zikaron knowledge refresh --wait`: it reports progress and returns
+once every build against those corpora has let go of its corpus — including one an earlier `add`
+started, which it waits for rather than stepping past — exiting non-zero if any build left its corpus
+unusable. By then each build's record of what it cost has been written to `memory.db`, or dropped if
+the store stayed locked; the indexer process itself may still be exiting. Without `--wait` the step
+can finish while an indexer is still running, and whatever kills the step kills the build too.
+
 **Nothing updates an index on its own.** There is no watcher and no schedule: a corpus drifts from
 its files until somebody refreshes it. A search says so when it can — a result whose file has
 changed since it was indexed comes back marked `stale`.
@@ -584,7 +697,8 @@ it is `0600` or `0700`. The **installer** also writes harness config — the fil
   knowledge/         one database per knowledge base, named by a generated id.
                      Absent until you create one
   config.toml        your per-project overrides, if you wrote any
-  service.log        the background service: startup, resolved config, errors
+  service.log        the background service: startup, resolved config, errors, why it stopped,
+                     any request running longer than 30 s, and the stack dumps below
   hook.log           one line per hook failure, write-policy-override note, or session/environment
                      mismatch. Absent means none happened. Not every line is a failure: an override
                      that is used but exceeds the injection budget is printed anyway and logged
@@ -610,6 +724,15 @@ its next group — or, if that process is killed first, by the next one that sta
 copy of memory text that lives outside `.zikaron/`, which is why the erasure procedure under
 [Secrets](#secrets) removes it by hand. Nothing spills under kiro.
 
+**What `service.log` tells you about a service that stopped, or stopped answering.** A clean stop
+writes one `stopping: reason=…` line: `idle`, `store_replaced`, `encoder_failed`, or `sigterm` /
+`sigint` when it was asked to stop. A request still running after the 30 s idle poll is logged as
+`long request: method=… session=… age=…` on every poll until it ends — `session=unresolved` if it
+never got that far. Two signals write a dump without stopping the service: `kill -USR2 <pid>` writes
+the requests in flight and every asyncio task's stack, and `kill -USR1 <pid>` writes every thread's
+stack, which is the one that still works when the service's event loop itself is stuck. The second is
+raw text, without the timestamp and `pid=` every other line carries.
+
 Two notes on reading the rest. `memory.db` can look implausibly small while `memory.db-wal` is large —
 that is normal for a database held open by the service, since recent writes live in the log until a
 checkpoint; the files together are the store. And `hook.log` records only a fixed failure label and an
@@ -617,8 +740,11 @@ error code, never your prompt or a memory's text, so it cannot hold a leaked sec
 
 There is one more log that is not a file: an event table inside `memory.db`. It records what happened
 on every **memory** read and write — used to measure whether the write policy is working, and kept in
-the database because those rows must commit alongside the change they describe. A knowledge base has
-no event log: it keeps four **search** counters in its own metadata — searches, empty searches,
+the database because those rows must commit alongside the change they describe. It also holds an
+access log, best-effort: a `call` row for each request the service answers — which method, how long
+it took, and what it refused, if anything — and a `knowledge_build` row for each corpus build.
+Neither carries text. A knowledge base's own database has no event log: it keeps four **search**
+counters in its metadata — searches, empty searches,
 results returned, results stale — which `zikaron_knowledge_status` reports beside the last build's
 own file, byte and skip-reason counts.
 
@@ -640,13 +766,15 @@ symptoms it cannot see.
 | nothing searchable works at all | `zikaron doctor` — extension loading, FTS5 and `sqlite-vec` are the three that fail this way, and all three are properties of the interpreter rather than of your project |
 | the MCP server starts and immediately dies | `zikaron doctor` — an over-long `$XDG_RUNTIME_DIR` makes the socket path exceed what the platform allows, and this is the only channel that says so |
 | no memories are being injected | `.zikaron/hook.log`, then `pgrep -af zikaron.service.main` |
-| the agent has no `zikaron_*` tools | kiro: `/tools`, and check `@zikaron` is in the agent's `tools`. Claude Code: `/mcp`, and check neither server is pending approval |
+| the agent has no `zikaron_*` tools | kiro: `/tools`, and check `@zikaron` is in the agent's `tools`. Claude Code: `/mcp`, and check neither server is pending approval — then check whether that agent's own frontmatter sets `tools:`, which overrides the project-wide registration entirely (below) |
 | every Zikaron tool call asks permission | kiro: add `@zikaron` to the agent's `allowedTools`. Claude Code: it is `permissions.allow` in `settings.local.json` that did not take |
 | a knowledge search returns nothing, or too little | `zikaron_knowledge_status` (or `zikaron knowledge status <name>`) — a corpus **refreshing** answers from what is already indexed, but one building for the first time answers nothing until it finishes. `reindex_required` means it has no usable index **right now**: never built, or a rebuild emptied it and was interrupted before it finished, or its database is gone, or the configured embedding model changed since it was built. `refresh` rebuilds it |
 | knowledge results look wrong for the file on disk | the index has drifted; nothing refreshes it on a schedule. A result whose file changed since indexing is marked `stale` — run `refresh` |
 | "Agents not available for crew stages: zikaron-consolidator" | add it to `toolsSettings.crew.availableAgents`, or re-run the installer |
 | consolidation seems stuck | ask to consolidate again — that takes the run over |
 | the service will not start | `.zikaron/service.log`; a change to a **hard** store-coupled key (`embed_model`, `embed_dim`) is the usual cause. A soft one never refuses **over what is already stored** — but any key set outside its range refuses at startup, whatever its coupling |
+| the service is running but stops answering | `.zikaron/service.log`'s last `long request:` lines name the request it is stuck in; `kill -USR2 <pid>` adds the requests in flight and every task's stack, and `kill -USR1 <pid>` every thread's stack if the loop itself is blocked (`pgrep -af zikaron.service.main` gives the pid). A `memory_plan_groups` or `memory_next_group` under five minutes is a plan, not a wedge. `hook.log` says which kind it is: **`transport`** on every push, though the socket connects, is a blocked loop; **`deadline_passed`** — or `unanswered`, when the answer lost the race to the hook's deadline — on every push with **no `call` rows** behind them in the event table is a request holding the store's writer, and the same run **with** `call` rows is every read connection taken; **`unanswered`** alone is a push whose own request hangs. One kind looks healthy in `hook.log`: pushes succeed while every write answers `store_busy` after about five seconds — the writer's lock held with nothing running — and the `long request:` line names that one too |
+| Zikaron's tools are listed but arrive name-only, or the agent's first calls are refused for argument shape | Claude Code: an install predating `alwaysLoad`, which `zikaron doctor` reports. Upgrade Zikaron where the project was installed from and re-run the installer there; the entry upgrades in place and needs no `--force` |
 | a hook command "not found" | the config names a different virtualenv than the one you installed from; re-run the installer with `--force` |
 | a memory looks half-written when injected | an over-long gist; see the note below |