zikaron 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zikaron
-Version: 0.3.0
+Version: 0.3.2
 Summary: Memory and searchable project knowledge for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nathan-shapiro/Zikaron
@@ -11,16 +11,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiosqlite==0.22.1
 Requires-Dist: sqlite-vec==0.1.9
-Requires-Dist: fastembed==0.8.0
-Requires-Dist: huggingface_hub==1.26.0
-Requires-Dist: fastmcp==3.4.7
+Requires-Dist: fastembed==0.8.1
+Requires-Dist: huggingface_hub==1.33.0
+Requires-Dist: fastmcp==4.0.10
 Provides-Extra: dev
-Requires-Dist: ruff==0.16.7; extra == "dev"
+Requires-Dist: ruff==0.16.9; extra == "dev"
 Requires-Dist: mypy==2.3.1; extra == "dev"
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-cov==7.1.0; extra == "dev"
 Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
-Requires-Dist: hypothesis==6.168.0; extra == "dev"
+Requires-Dist: hypothesis==6.168.3; extra == "dev"
 Requires-Dist: pyyaml==6.0.3; extra == "dev"
 Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
 Requires-Dist: build==1.3.0; extra == "dev"
@@ -61,6 +61,13 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
+**And, on request, guards for Claude Code** — two deterministic hooks, independent of both stores.
+One refuses two kinds of command: a find-replace edit to an authored file (`sed -i`, an inline
+script, a heredoc into the file), pointing the agent at `Read` and `Edit`, and a `pgrep -f` or
+`pkill -f` whose pattern matches the shell running it. The other reminds the agent, after each
+edit, to re-read what it changed. See [Guards](#guards-claude-code-on-request); a project may install the memory store, the
+guards, or both.
+
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
 the embedding-model download described under [Install](#install), pinned to one revision and
@@ -124,6 +131,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. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each `Bash` or `Monitor` call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **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
@@ -235,6 +243,16 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
+Under Claude Code, `--components` adds the [guards](#guards-claude-code-on-request), or
+installs them alone; without it you get the memory store only, exactly as before:
+
+```bash
+zikaron install --project . --harness claude-code --components both     # memory and guards
+zikaron install --project . --harness claude-code --components guards   # guards only
+```
+
+Installing one later keeps the other: an install touches only what it was asked for.
+
 **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
@@ -334,6 +352,12 @@ and under **Claude Code**:
 | `.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 — each marked `alwaysLoad` so their descriptions are in context from the start rather than fetched per tool |
 
+With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
+hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
+two guard hooks — before each `Bash` or `Monitor` call, after each edit. No server, no approval
+key, no consolidator. With `--components both` you get all of the above together, and the start hooks carry
+the write policy and the guards' note.
+
 **`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.
 The third hook is the one with no kiro counterpart — it hands the write policy to each subagent you
@@ -451,6 +475,48 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
+### Guards (Claude Code, on request)
+
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to three
+rules, with no model and no store behind them (`design/guards.md`):
+
+- **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
+  or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
+  `/tmp` or `$TMPDIR` that the command runs and that does any of these. The refusal reaches the
+  agent as the tool's result and tells it to use `Read` and `Edit`, or `Write` for a new file.
+  Paths under `/tmp`, `/var/tmp` and `$TMPDIR` are exempt, and so is a command carrying the
+  override the refusal itself describes, for the files whose bytes a program owns.
+- **After each edit, the agent is reminded** that the file has not been re-read, and asked for one
+  re-read of the edited material once that file's editing is done. A Bash command gets no such
+  reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
+  command changes and asks for that re-read instead.
+- **A `pgrep -f` or `pkill -f` whose pattern matches its own command is refused.** Claude Code
+  runs each command inside a shell whose command line carries the command's text, so on Linux such
+  a pattern matches that shell: `pkill` kills it, and `pgrep` always finds it, so a check for a
+  process that has exited never sees it gone. The refusal shows where the pattern matched and gives
+  the fix: `-A`, where `pgrep` has it, or a bracketed character (`[m]onth_monitor.py`). On macOS,
+  whose `pgrep` already leaves out the shell, only `-a` brings it back.
+
+Both refusals judge `Bash` and `Monitor` commands alike. An install made by an earlier version
+judges `Bash` alone; re-running it with the same `--components` adds `Monitor`.
+
+They are not a security boundary: a script the guard reads is one run from a scratch directory,
+and a script anywhere else — one of the project's own programs — is never read, by design. A guard
+that fails for any reason allows the call.
+
+They write no log and no store record: a refusal, an override and its reason are in the session's
+own transcript. `zikaron doctor` does not report on them. To see the refusal without a model in
+the loop, hand the guard the payload Claude Code would send it, from the project directory — run
+from a scratch directory such as `/tmp`, the same command is exempt and prints nothing:
+
+```bash
+printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","cwd":"'"$PWD"'","tool_input":{"command":"sed -i s/a/b/ README.md"}}' | zikaron-guard
+```
+
+It prints the deny the agent would read as the command's result. Asking an agent to run `sed -i`
+usually shows something else: told the rule when its session starts, it reaches for `Read` and
+`Edit` without trying.
+
 ### Options
 
 | Flag | Effect |
@@ -462,6 +528,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 |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--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
@@ -508,7 +575,7 @@ write policy goes into the model's context, not to your terminal. Then, from the
 # a service should be running for this project after your first message
 pgrep -af zikaron.service.main
 
-# one line per hook failure, write-policy-override note, or session/environment mismatch; absent means none happened
+# one line per hook failure, missed cold start, write-policy-override note, or session/environment mismatch; absent means none happened
 cat .zikaron/hook.log
 ```
 
@@ -699,9 +766,11 @@ it is `0600` or `0700`. The **installer** also writes harness config — the fil
   config.toml        your per-project overrides, if you wrote any
   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
+  hook.log           one line per hook failure, missed cold start, write-policy-override note, or
+                     session/environment mismatch. Absent means none happened. Not every line is a
+                     failure: `starting` is a message that arrived while the service was still
+                     starting, and an override that is used but exceeds the injection budget is
+                     printed anyway and logged
   warmup.log         the small helper that warms the service when a session starts
   write-policy.md    your policy override, if you wrote one
 ```
@@ -714,19 +783,23 @@ shared by every project you use Zikaron in, under `$XDG_CACHE_HOME/zikaron/model
 A copy inside each project would duplicate it for bytes that are identical by construction, since the
 version fetched is pinned. Removing a project does not remove it; [Uninstall](#uninstall) says how.
 
-The second is the service's Unix socket, which with its lock file sits in
-`$XDG_RUNTIME_DIR/zikaron/` — or `/tmp/zikaron-<uid>/` where that variable is unset, which is every
-Mac — named by a hash of the store's path, `0600` inside a `0700` directory. A socket belongs on a
-runtime filesystem rather than in your project. **Under Claude
-Code**, an over-large consolidator result also spills to a file beside them, carrying that group's
-record prose verbatim and named by the same store hash; it is deleted when the consolidator asks for
-its next group — or, if that process is killed first, by the next one that starts. It is the one
-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.
+The second is the service's Unix socket. It sits in `$XDG_RUNTIME_DIR/zikaron/` — or
+`/tmp/zikaron-<uid>/` where that variable is unset, which is every Mac — named by a hash of the
+store's path, `0600` inside a `0700` directory, beside two lock files: one clients take while they
+start the service, and one the service holds while it has the store open. A socket belongs on a
+runtime filesystem rather than in your project. **Under Claude Code**, an over-large consolidator
+result also spills to a file beside them, carrying that group's record prose verbatim and named by
+the same store hash; it is deleted when the consolidator asks for its next group — or, if that
+process is killed first, by the next one that starts. It is the one 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
+writes one `stopping: reason=…` line: `idle`, `store_replaced`, `socket_lost` (its socket file was
+removed, so nothing could reach it), `encoder_failed`, or `sigterm` / `sigint` when it was asked to
+stop. A start that found another service already holding the store writes `not starting:
+reason=another_service` and exits, leaving that one to serve it. 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
@@ -735,8 +808,8 @@ 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
-error code, never your prompt or a memory's text, so it cannot hold a leaked secret.
+checkpoint; the files together are the store. And `hook.log` records only fixed labels and an error
+code, never your prompt or a memory's text, so it cannot hold a leaked secret.
 
 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
@@ -756,6 +829,16 @@ Zikaron is built to fail quietly rather than get in your way. A hook that cannot
 prints a short note asking the agent to tell you, writes one line to `hook.log`, and exits cleanly. It
 never blocks your message, and it never reads the store directly.
 
+The service stops itself after a stretch of idleness, and the next message starts it again. That
+message waits a few seconds longer — the hook allows a start more time than a running service — and
+if the start still is not finished, the message goes without memories and the agent is told so, without
+being asked to report it. `hook.log` records that as `starting`, followed by what the hook was still
+waiting on — `lock` or `poll` before the service answered, or the lateness of its answer after — and
+memories return once it has started, usually with the next message. A run of `starting` lines means
+starts are slower than the hook allows, not that the service is broken; a start that never finishes is
+reported as `transport` once it has gone a minute without a sign of life — which a first run still
+fetching its model over a slow link can also do, until it finishes.
+
 **Run `zikaron doctor` first for anything that smells environmental** — no search results at all, a
 service that will not start, an MCP server that dies on contact. It checks the things about this
 machine that can stop Zikaron working and names what to change for each. The table below is for
@@ -864,6 +947,12 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
+**The guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+`PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
+`SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
+guards, re-running the installer will not do it — an install never removes a selection — so delete
+the two guard groups and the `--components …` arguments from the two start groups' command.
+
 Note that `rm -rf .zikaron` takes the knowledge bases with it. They are rebuildable — an index is a
 view onto files you still have — but rebuilding one takes minutes per corpus.
 

zikaron-0.3.0/PKG-INFO → zikaron-0.3.2/README.md

@@ -1,32 +1,3 @@
-Metadata-Version: 2.4
-Name: zikaron
-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
-Project-URL: Repository, https://github.com/nathan-shapiro/Zikaron
-Project-URL: Issues, https://github.com/nathan-shapiro/Zikaron/issues
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiosqlite==0.22.1
-Requires-Dist: sqlite-vec==0.1.9
-Requires-Dist: fastembed==0.8.0
-Requires-Dist: huggingface_hub==1.26.0
-Requires-Dist: fastmcp==3.4.7
-Provides-Extra: dev
-Requires-Dist: ruff==0.16.7; extra == "dev"
-Requires-Dist: mypy==2.3.1; extra == "dev"
-Requires-Dist: pytest==9.1.1; extra == "dev"
-Requires-Dist: pytest-cov==7.1.0; extra == "dev"
-Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
-Requires-Dist: hypothesis==6.168.0; extra == "dev"
-Requires-Dist: pyyaml==6.0.3; extra == "dev"
-Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
-Requires-Dist: build==1.3.0; extra == "dev"
-Requires-Dist: setuptools==84.0.0; extra == "dev"
-Dynamic: license-file
-
 # Zikaron
 
 [![PyPI](https://img.shields.io/pypi/v/zikaron)](https://pypi.org/project/zikaron/)
@@ -61,6 +32,13 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
+**And, on request, guards for Claude Code** — two deterministic hooks, independent of both stores.
+One refuses two kinds of command: a find-replace edit to an authored file (`sed -i`, an inline
+script, a heredoc into the file), pointing the agent at `Read` and `Edit`, and a `pgrep -f` or
+`pkill -f` whose pattern matches the shell running it. The other reminds the agent, after each
+edit, to re-read what it changed. See [Guards](#guards-claude-code-on-request); a project may install the memory store, the
+guards, or both.
+
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
 the embedding-model download described under [Install](#install), pinned to one revision and
@@ -124,6 +102,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. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each `Bash` or `Monitor` call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **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
@@ -235,6 +214,16 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
+Under Claude Code, `--components` adds the [guards](#guards-claude-code-on-request), or
+installs them alone; without it you get the memory store only, exactly as before:
+
+```bash
+zikaron install --project . --harness claude-code --components both     # memory and guards
+zikaron install --project . --harness claude-code --components guards   # guards only
+```
+
+Installing one later keeps the other: an install touches only what it was asked for.
+
 **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
@@ -334,6 +323,12 @@ and under **Claude Code**:
 | `.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 — each marked `alwaysLoad` so their descriptions are in context from the start rather than fetched per tool |
 
+With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
+hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
+two guard hooks — before each `Bash` or `Monitor` call, after each edit. No server, no approval
+key, no consolidator. With `--components both` you get all of the above together, and the start hooks carry
+the write policy and the guards' note.
+
 **`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.
 The third hook is the one with no kiro counterpart — it hands the write policy to each subagent you
@@ -451,6 +446,48 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
+### Guards (Claude Code, on request)
+
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to three
+rules, with no model and no store behind them (`design/guards.md`):
+
+- **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
+  or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
+  `/tmp` or `$TMPDIR` that the command runs and that does any of these. The refusal reaches the
+  agent as the tool's result and tells it to use `Read` and `Edit`, or `Write` for a new file.
+  Paths under `/tmp`, `/var/tmp` and `$TMPDIR` are exempt, and so is a command carrying the
+  override the refusal itself describes, for the files whose bytes a program owns.
+- **After each edit, the agent is reminded** that the file has not been re-read, and asked for one
+  re-read of the edited material once that file's editing is done. A Bash command gets no such
+  reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
+  command changes and asks for that re-read instead.
+- **A `pgrep -f` or `pkill -f` whose pattern matches its own command is refused.** Claude Code
+  runs each command inside a shell whose command line carries the command's text, so on Linux such
+  a pattern matches that shell: `pkill` kills it, and `pgrep` always finds it, so a check for a
+  process that has exited never sees it gone. The refusal shows where the pattern matched and gives
+  the fix: `-A`, where `pgrep` has it, or a bracketed character (`[m]onth_monitor.py`). On macOS,
+  whose `pgrep` already leaves out the shell, only `-a` brings it back.
+
+Both refusals judge `Bash` and `Monitor` commands alike. An install made by an earlier version
+judges `Bash` alone; re-running it with the same `--components` adds `Monitor`.
+
+They are not a security boundary: a script the guard reads is one run from a scratch directory,
+and a script anywhere else — one of the project's own programs — is never read, by design. A guard
+that fails for any reason allows the call.
+
+They write no log and no store record: a refusal, an override and its reason are in the session's
+own transcript. `zikaron doctor` does not report on them. To see the refusal without a model in
+the loop, hand the guard the payload Claude Code would send it, from the project directory — run
+from a scratch directory such as `/tmp`, the same command is exempt and prints nothing:
+
+```bash
+printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","cwd":"'"$PWD"'","tool_input":{"command":"sed -i s/a/b/ README.md"}}' | zikaron-guard
+```
+
+It prints the deny the agent would read as the command's result. Asking an agent to run `sed -i`
+usually shows something else: told the rule when its session starts, it reaches for `Read` and
+`Edit` without trying.
+
 ### Options
 
 | Flag | Effect |
@@ -462,6 +499,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 |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--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
@@ -508,7 +546,7 @@ write policy goes into the model's context, not to your terminal. Then, from the
 # a service should be running for this project after your first message
 pgrep -af zikaron.service.main
 
-# one line per hook failure, write-policy-override note, or session/environment mismatch; absent means none happened
+# one line per hook failure, missed cold start, write-policy-override note, or session/environment mismatch; absent means none happened
 cat .zikaron/hook.log
 ```
 
@@ -699,9 +737,11 @@ it is `0600` or `0700`. The **installer** also writes harness config — the fil
   config.toml        your per-project overrides, if you wrote any
   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
+  hook.log           one line per hook failure, missed cold start, write-policy-override note, or
+                     session/environment mismatch. Absent means none happened. Not every line is a
+                     failure: `starting` is a message that arrived while the service was still
+                     starting, and an override that is used but exceeds the injection budget is
+                     printed anyway and logged
   warmup.log         the small helper that warms the service when a session starts
   write-policy.md    your policy override, if you wrote one
 ```
@@ -714,19 +754,23 @@ shared by every project you use Zikaron in, under `$XDG_CACHE_HOME/zikaron/model
 A copy inside each project would duplicate it for bytes that are identical by construction, since the
 version fetched is pinned. Removing a project does not remove it; [Uninstall](#uninstall) says how.
 
-The second is the service's Unix socket, which with its lock file sits in
-`$XDG_RUNTIME_DIR/zikaron/` — or `/tmp/zikaron-<uid>/` where that variable is unset, which is every
-Mac — named by a hash of the store's path, `0600` inside a `0700` directory. A socket belongs on a
-runtime filesystem rather than in your project. **Under Claude
-Code**, an over-large consolidator result also spills to a file beside them, carrying that group's
-record prose verbatim and named by the same store hash; it is deleted when the consolidator asks for
-its next group — or, if that process is killed first, by the next one that starts. It is the one
-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.
+The second is the service's Unix socket. It sits in `$XDG_RUNTIME_DIR/zikaron/` — or
+`/tmp/zikaron-<uid>/` where that variable is unset, which is every Mac — named by a hash of the
+store's path, `0600` inside a `0700` directory, beside two lock files: one clients take while they
+start the service, and one the service holds while it has the store open. A socket belongs on a
+runtime filesystem rather than in your project. **Under Claude Code**, an over-large consolidator
+result also spills to a file beside them, carrying that group's record prose verbatim and named by
+the same store hash; it is deleted when the consolidator asks for its next group — or, if that
+process is killed first, by the next one that starts. It is the one 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
+writes one `stopping: reason=…` line: `idle`, `store_replaced`, `socket_lost` (its socket file was
+removed, so nothing could reach it), `encoder_failed`, or `sigterm` / `sigint` when it was asked to
+stop. A start that found another service already holding the store writes `not starting:
+reason=another_service` and exits, leaving that one to serve it. 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
@@ -735,8 +779,8 @@ 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
-error code, never your prompt or a memory's text, so it cannot hold a leaked secret.
+checkpoint; the files together are the store. And `hook.log` records only fixed labels and an error
+code, never your prompt or a memory's text, so it cannot hold a leaked secret.
 
 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
@@ -756,6 +800,16 @@ Zikaron is built to fail quietly rather than get in your way. A hook that cannot
 prints a short note asking the agent to tell you, writes one line to `hook.log`, and exits cleanly. It
 never blocks your message, and it never reads the store directly.
 
+The service stops itself after a stretch of idleness, and the next message starts it again. That
+message waits a few seconds longer — the hook allows a start more time than a running service — and
+if the start still is not finished, the message goes without memories and the agent is told so, without
+being asked to report it. `hook.log` records that as `starting`, followed by what the hook was still
+waiting on — `lock` or `poll` before the service answered, or the lateness of its answer after — and
+memories return once it has started, usually with the next message. A run of `starting` lines means
+starts are slower than the hook allows, not that the service is broken; a start that never finishes is
+reported as `transport` once it has gone a minute without a sign of life — which a first run still
+fetching its model over a slow link can also do, until it finishes.
+
 **Run `zikaron doctor` first for anything that smells environmental** — no search results at all, a
 service that will not start, an MCP server that dies on contact. It checks the things about this
 machine that can stop Zikaron working and names what to change for each. The table below is for
@@ -864,6 +918,12 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
+**The guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+`PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
+`SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
+guards, re-running the installer will not do it — an install never removes a selection — so delete
+the two guard groups and the `--components …` arguments from the two start groups' command.
+
 Note that `rm -rf .zikaron` takes the knowledge bases with it. They are rebuildable — an index is a
 view onto files you still have — but rebuilding one takes minutes per corpus.
 

{zikaron-0.3.0 → zikaron-0.3.2}/pyproject.toml

@@ -4,16 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zikaron"
-# Semver, and `0.x` for as long as the *install contract* may still change — the shapes and
-# locations of the artefacts the installer writes into a harness's config. The one rule that
-# matters for an upgrade: **a release whose installed artefacts differ in shape from the previous
-# one is a minor bump, never a patch**, because those paths are written into harness config that an
-# upgrade has to be able to refresh, and a patch bump tells a reader nothing needs refreshing.
-# `design/distribution.md` §"The version scheme" is normative.
-version = "0.3.0"
+# Semver, `0.x`. **A minor bump means one thing: `meta.schema_version` moved**, so a release that
+# cannot open a store an earlier one wrote says so in its number. Every other change is a patch, a
+# changed installed artifact included; a release that needs an existing install refreshed says so
+# in its release note. `design/distribution.md` §"The version scheme" is normative.
+version = "0.3.2"
 # What a package index renders as the one-line summary, so it must name both stores: the memory
 # store, for what was learned by working here, and the knowledge index, for what the project already
-# wrote down.
+# wrote down. The guards, which ship on request, are the README's to describe.
 description = "Memory and searchable project knowledge for coding agents"
 readme = "README.md"
 # An SPDX expression plus `license-files`, which is the PEP 639 shape. **No
@@ -32,11 +30,11 @@ requires-python = ">=3.12"
 dependencies = [
     "aiosqlite==0.22.1",
     "sqlite-vec==0.1.9",
-    "fastembed==0.8.0",
+    "fastembed==0.8.1",
     # Direct, not transitive: `core/indexing/acquisition.py` calls `snapshot_download` itself, so
     # that the revision and the digests are Zikaron's rather than whatever upstream head fastembed
     # would resolve. §6 pins direct dependencies exactly.
-    "huggingface_hub==1.26.0",
+    "huggingface_hub==1.33.0",
     # `zikaron-mcp` only. Deliberately not stdlib-only, unlike `zikaron-hook` — see
     # coding-standards.md §6 for the cost-model reasoning (once per agent spawn, not once per
     # message) and architecture.md §Components for the measured import cost.
@@ -45,7 +43,7 @@ dependencies = [
     # changes how a client's connection — and therefore the session label this client adopts and
     # reuses across calls — is carried. That is a transport change worth its own measurement, so
     # the bump is deliberate rather than absorbed into an ordinary dependency refresh.
-    "fastmcp==3.4.7",
+    "fastmcp==4.0.10",
 ]
 
 # Absent until now, which is why the PyPI page M30 will publish would have rendered blank. The
@@ -64,12 +62,13 @@ Homepage = "https://github.com/nathan-shapiro/Zikaron"
 Repository = "https://github.com/nathan-shapiro/Zikaron"
 Issues = "https://github.com/nathan-shapiro/Zikaron/issues"
 
-# The two commands a shipped harness config names — either harness — and the reason they are console
-# scripts rather than `python -m` command lines: a hook entry's `command` and an `mcpServers` entry's
-# `command` each need one absolute path, and a console script's shebang pins the interpreter Zikaron
-# is installed into — which is also the interpreter start-if-absent will spawn the service with, via
-# `sys.executable`. Measured, so the choice costs nothing: the two forms differ by about 1.4 ms
-# median over a full hook process (architecture.md §"The install contract").
+# The commands a shipped harness config names — `zikaron-hook` and `zikaron-mcp` for either harness,
+# `zikaron-guard` for Claude Code's guards — and the reason they are console scripts rather than
+# `python -m` command lines: a hook entry's `command` and an `mcpServers` entry's `command` each need
+# one absolute path, and a console script's shebang pins the interpreter Zikaron is installed into —
+# which is also the interpreter start-if-absent will spawn the service with, via `sys.executable`.
+# Measured, so the choice costs nothing: the two forms differ by about 1.4 ms median over a full hook
+# process (architecture.md §"The install contract").
 #
 # `zikaron-service` is deliberately *not* here. No config names it: it is spawned by
 # `sys.executable -m zikaron.service.main` from whichever client finds the socket absent, which is
@@ -84,17 +83,18 @@ Issues = "https://github.com/nathan-shapiro/Zikaron/issues"
 zikaron = "zikaron.cli.main:main"
 zikaron-hook = "zikaron.hook.main:main"
 zikaron-mcp = "zikaron.mcp.main:main"
+zikaron-guard = "zikaron.guard.main:main"
 
 [project.optional-dependencies]
 dev = [
-    "ruff==0.16.7",
+    "ruff==0.16.9",
     "mypy==2.3.1",
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
     "pytest-asyncio==1.4.0",
     # Property-based tests, for the places the design states a property rather than a case:
     # chunking never loses content, and no chunk exceeds the budget it was cut to.
-    "hypothesis==6.168.0",
+    "hypothesis==6.168.3",
     # Tests only, and never imported by shipped code. Two of Claude Code's four installed
     # artefacts are YAML-frontmatter Markdown, and the installer emits that frontmatter by string
     # formatting — so the only way to assert it is *valid* is to parse it with something that did

{zikaron-0.3.0 → zikaron-0.3.2}/tests/test_check_gate.py

@@ -140,7 +140,7 @@ def test_the_project_table_still_holds_the_keys_a_later_table_can_swallow() -> N
     still *in `[project]`*, which is the property an inserted table destroys.
     """
     project = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"]
-    for key in ("name", "version", "readme", "license", "requires-python", "dependencies"):
+    keys = ("name", "version", "readme", "license", "requires-python", "dependencies", "scripts")
+    for key in keys:
         assert key in project, f"`{key}` has left [project] — a table header was inserted above it"
     assert len(project["dependencies"]) == 5, "the runtime dependency list changed size"
-    assert set(project["scripts"]) == {"zikaron", "zikaron-hook", "zikaron-mcp"}

{zikaron-0.3.0 → zikaron-0.3.2}/tests/test_cli_front_door.py

@@ -25,10 +25,18 @@ _ROOT: Final = Path(__file__).resolve().parent.parent
 _SUBCOMMANDS: Final = ("init", "install", "knowledge", "doctor")
 
 
-def test_the_console_script_resolves_to_something_callable() -> None:
-    declared = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
-    target = declared["project"]["scripts"][NAME]
-    module_path, _, attribute = target.partition(":")
+_SCRIPTS: Final[dict[str, str]] = tomllib.loads(
+    (_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+)["project"]["scripts"]
+
+
+def test_the_front_door_is_a_declared_console_script() -> None:
+    assert NAME in _SCRIPTS
+
+
+@pytest.mark.parametrize("script", sorted(_SCRIPTS))
+def test_every_console_script_resolves_to_something_callable(script: str) -> None:
+    module_path, _, attribute = _SCRIPTS[script].partition(":")
     entry = getattr(importlib.import_module(module_path), attribute)
     assert callable(entry)
 

{zikaron-0.3.0 → zikaron-0.3.2}/tests/test_distribution.py

@@ -143,8 +143,11 @@ def test_the_wheel_declares_every_console_script(built: tuple[Path, Path]) -> No
     with zipfile.ZipFile(wheel) as archive:
         (entry_points,) = [n for n in archive.namelist() if n.endswith("entry_points.txt")]
         declared = archive.read(entry_points).decode()
-    for script in ("zikaron =", "zikaron-hook =", "zikaron-mcp ="):
-        assert script in declared, f"{script.rstrip(' =')} is not in the built wheel"
+    scripts = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"][
+        "scripts"
+    ]
+    for script in scripts:
+        assert f"{script} =" in declared, f"{script} is not in the built wheel"
 
 
 def test_nothing_published_names_this_machine(built: tuple[Path, Path]) -> None: