sidegraph 0.8.0__tar.gz → 0.10.0__tar.gz

{sidegraph-0.8.0 → sidegraph-0.10.0}/.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
         "source": "local",
         "path": "./plugin/sidegraph"
       },
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors."
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors."
     }
   ]
 }

{sidegraph-0.8.0 → sidegraph-0.10.0}/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     {
       "name": "sidegraph",
       "source": "./plugin/sidegraph",
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors.",
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors.",
       "homepage": "https://github.com/SantyagoSeaman/sidegraph"
     }
   ]

{sidegraph-0.8.0 → sidegraph-0.10.0}/CHANGELOG.md

@@ -7,6 +7,330 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-10-04
+
+### Added
+
+- **Every MCP tool now carries annotations, so a host's auto-reviewer stops rejecting memory
+  reads.** In the field, Codex's auto-reviewer rejected 20 `get_task_context` calls, and each
+  one lost memory for that step: an unannotated tool takes the MCP defaults (destructive,
+  open-world), and the review's verdict then depends on the prompt. The seven tools that never
+  change a tracked file are read-only; the other 17 are non-destructive, closed-world local
+  writes. No tool sends anything off the machine and none deletes a record. A test runs the
+  read-only tools on a store where a lazy sync would adopt a moved symbol, and fails if one of
+  them changes a tracked file, so the annotation cannot drift from what the tool does. See the
+  [reference](docs/reference/mcp-tools.md#annotations) and the
+  [Codex page](docs/integrations/codex.md#the-auto-reviewer-and-memory-reads).
+- **The seed tools accept the argument names agents try, and every tool names its parameters in
+  an error.** `get_task_context`, `query_structure` and `query_decisions` accept `paths` (as
+  `files`) and `seeds`; each seed goes to `files` when it looks like a path and to `entities`
+  otherwise. `task` is refused with a line saying there is no free-text query. Any other
+  unknown argument, on any tool, is an error that names it and lists the tool's real parameters;
+  FastMCP's own error named the argument but not the parameters.
+
+### Changed
+
+- **`retrieve_decisions` no longer returns the whole store.** One call returned a full dump of
+  every visible decision: about 143,000 tokens on a store of 260 records, more than a host would
+  show, and in a field report most agents passed `include_superseded: true` and then either
+  printed the dump or filtered it by hand. The call now has two answers.
+  - With no narrowing filter it returns an **overview**: the total, counts by status and kind
+    (superseded and rejected records included, so the counts say that history exists), and the
+    newest records as compact rows (`id`, `kind`, `status`, `title`, `valid_from`).
+  - With a narrowing filter it returns **full records**, gotchas and lessons first and newest
+    first, cut at `limit` (default 25, at most 100) or `budget_chars` (default 24,000, at most
+    60,000), whichever comes first. A `hint` says what cut the list, or why it is empty.
+  - The filters are new arguments, and they combine with AND: `status` and `kind` (a string or a
+    list), `files`, `query` (every word must occur in the record's text) and `ids` (exact record
+    ids, superseded ones too). `include_superseded` keeps its meaning: it widens the overview's
+    `newest` and a filtered call that has no `status`.
+  - `files` are read the way `get_task_context` reads them: a basename, a suffix, a directory or
+    a letter-case slip works. `unresolved_files` lists, for each path nothing could read (at most
+    ten, with `unresolved_omitted` counting the rest), why (`ambiguous`, `directory-too-large`,
+    `not-in-graph` or `no-graph`) and the candidates to pass instead.
+  - **The return type changed from a list to a JSON object, sent once as a single text block
+    with no structured copy**, so `budget_chars` is the real cost on every host. A client that
+    read the list now reads `decisions` of a filtered answer. The proposal policy is unchanged
+    and applies to every shape.
+  - The `check-plan`, `explain-why`, `triage-drift` and `heal-anchors` skills now call it with a
+    filter, and a test fails if a skill calls it without one. See the
+    [reference](docs/reference/mcp-tools.md#retrieve_decisions).
+
+### Fixed
+
+- **A fault converting a reviewed item in `sidegraph-bootstrap` now prints the RESUME line.** The
+  conversion of each reviewed item, and the check that its ref still matches the candidate,
+  ran outside the per-item error handling. A fault there, after an earlier item had been
+  written, left `apply_review` without a report: an `AssertionError` ended the run as a
+  traceback, a `ValueError` was reported as a failure before anything was written, and neither
+  printed `RESUME`, though canonical files were already on disk. The fault now takes the path a
+  write error takes: the run stops, reports `partial-recoverable` with the durable candidates and
+  the failing ref, and prints the resume command. A fault on the first item, before anything is
+  written, now exits 2 with `STORE incomplete`, the failing ref and the resume command, where a
+  `ValueError` used to exit 1 with an `ERROR` line; the terminal shows the failing ref and not the
+  reason.
+- **`sidegraph-import --dry-run` now says what auto-ratification would do.** Both import paths
+  decided auto-ratification only after a real write, so under a non-`manual`
+  `SIDEGRAPH_RATIFY_POLICY` a dry run could not show which records a real run would land
+  accepted without a human: on one fixture it reported 0 where the real run auto-ratified 2. The
+  dry run now runs the same eligibility gate on the record the write would produce and reports
+  the result in a new `would_auto_ratify` field on `ImportReport` and `DocImportReport`, and as
+  `auto_ratify_eligible` on each dry-run item. `auto_ratified` keeps its meaning, transitions
+  that actually happened, so it stays 0 in a dry run.
+  - **Behaviour change:** under a non-`manual` policy the summary line gains `would
+    auto-ratify M` before `(skipped:` and an eligible item line ends with ` [auto]`. Under
+    `manual` both are unchanged. A dry run still never carries the real run's `auto-ratified K`.
+  - The count is eligibility, not a guarantee: a real run's transition can still fail, for
+    example on a race or a refused cascade.
+  - A key repeated within one run no longer counts twice in the dry run. Two rationales with the
+    same title in one file count once. A document ref met more than once (one file named twice, a
+    directory plus a file inside it, or a live and an archived copy that a profile maps to one
+    ref) is classified against the records the earlier copies would have left there, as the real
+    run sees them: an identical repeat is skipped, a differing one supersedes, and a copy after a
+    `rejected` first copy is a fresh write. Two rare shapes can still differ in the
+    `superseded`/`skipped` split, not in the eligibility count where checked: a ref met three
+    times with the first content returning, under an auto policy, and a repeat with no anchor of
+    its own.
+- **`find_entity` no longer calls a dangling record a decision.** Each binding was labelled
+  `fact` if a fact lookup found it and `decision` otherwise, so a binding whose record exists in
+  neither table (a record file removed by hand, or lost in a merge) came back as a decision that
+  `get_decision` could not fetch, and each binding cost a query of its own. The types of all of an
+  entity's bindings now come from one read of the index, and a binding with no record reports
+  `record_type: "unknown"`. The value is additive: a client that handles `decision` and `fact`
+  is unaffected. `get_entity_history` uses the same read and still skips such a binding. See the
+  [reference](docs/reference/mcp-tools.md#find_entity).
+- **A document status like `should not be rejected` no longer lands `rejected`.** The check for
+  a turned-down status saw a negation only as `not` and one space directly before the word, so
+  `should not be rejected`, `not  rejected` (two spaces), `never rejected` and `isn't rejected`
+  all read as rejections, and a false `rejected` lands closed and invisible to retrieval. A
+  negation is now `not`, `never` or a word ending `n't` within the three words before the word in
+  the same clause. A clause ends at `,` `;` `.` `:`, a pipe, a slash, an em or en dash, or a spaced
+  hyphen or `->`, so `not reviewed, rejected`, `Not accepted — rejected` and `Won't do / rejected`
+  still read as rejections, as does `not rejected, rejected`. A conjunction does not end a
+  clause: `Not adopted and rejected` reads as negated, and lands accepted unless `--propose` or
+  a draft marker sends it to the ratification queue. See the
+  [reference](docs/reference/cli.md#sidegraph-import).
+
+## [0.9.0] — 2026-10-04
+
+### Added
+
+- **Host wiring that silently switched memory off is now visible.** Two field failures went
+  unnoticed for weeks: hooks that ran an old install under a newer plugin, and sessions started in
+  a subdirectory where the plugin was off. `SessionStart` now prints `Sidegraph <version>` right
+  after the standing instruction, and two advisory checks report the wiring, each with a notice
+  at most once a day (`plugin-off-in-subdirectories` only when a nested directory's own settings
+  leave the plugin off).
+  - `version-skew` compares the running package with the plugin manifest under
+    `$CLAUDE_PLUGIN_ROOT` (or else `$PLUGIN_ROOT`, which Codex sets) by numeric parts, and says
+    which side is stale. It does not run without a plugin root, a manifest named `sidegraph`, or a
+    version.
+  - `plugin-off-in-subdirectories` applies Claude Code's settings model (a launch directory's own
+    project settings only, the repository root's `.claude/settings.local.json` for every launch,
+    `enabledPlugins` merged key by key over user settings) to the directories of the repository.
+    It reports a plugin enabled only in the root's `.claude/settings.json`, and nested directories
+    whose own `enabledPlugins` leave it off. User settings are read from
+    `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set, else from `~/.claude/settings.json`. It also lists in `sidegraph-doctor` under the finding code
+    `plugin-off-in-subdirectories`, and **`--check` exits `2` on it** like any finding.
+  The getting-started pages now say that enabling the plugin at user scope, or in the root's
+  `.claude/settings.local.json`, covers every subdirectory, and the setup skill reads the doctor
+  finding. See [troubleshooting](docs/guides/troubleshooting.md#version-skew).
+
+- **A subagent's brief carries the records for the files it names.** The task a subagent works
+  on is in the brief its parent wrote, which the `SubagentStart` brief cannot see. The
+  `sidegraph-pre-tool-use` entry point now also handles `Agent` (and `Task`, the older name): it
+  reads the files the brief names, and the files named in a `.md`, `.txt` or `.rst` document the
+  brief names (one hop, the first 64 KB), finds the records anchored to them, and returns the
+  call's own input with a block appended to `prompt` (`updatedInput`; no `permissionDecision`).
+  The subagent finds the block at the end of its first message. **The parent's view of its own
+  call does not show it**: its transcript keeps the prompt it wrote. A path resolves exactly when
+  it is an existing regular file inside the project root, and otherwise by a unique suffix among
+  the anchored files (`sub/x.py` for `pkg/sub/x.py`; an ambiguous suffix names nothing), tried
+  from the directory the agent was launched in before the root. A document is followed only when
+  it is a regular file inside the root, and **no hop goes through a project-instruction file**
+  (`CLAUDE.md`, `AGENTS.md` and their `.public` twins): they are still shown when records are
+  anchored to them, but the files they list are not followed. The block is grouped by file, two
+  records each, at most six record lines and 3,000 characters, and it ends with a
+  `More: get_task_context(files=[…])` line for the files shown; a file that misses the sixth
+  line by one still gets its first record there. It is **on by default**;
+  `SIDEGRAPH_AGENT_BRIEF=off` disables it. The plugin manifests (Claude Code only, the Codex ones
+  are unchanged) and the manual recipe gain a third `PreToolUse` group, matcher `Agent|Task`, on
+  the same command; a hand-wired setup needs that group added. Not tested: agent-team teammates
+  and `fork` spawns. See the
+  [hooks reference](docs/reference/hooks.md#subagent-briefs).
+
+- **Every subagent starts knowing that memory exists and how to ask it.** A subagent gets no
+  `SessionStart` context, and Explore and Plan agents load no `CLAUDE.md` either, so nothing
+  standing told one that decision memory exists. The new `sidegraph-subagent-start` hook, wired
+  to `SubagentStart` in the Claude Code and Codex plugins, answers with a short brief: the same
+  standing `get_task_context(files=[…])` call `SessionStart` gives the main agent, and one
+  sentence of what memory holds ("N records anchored to code in M files, K of them recorded
+  mistakes"). The counts are what `get_task_context` could return: live records that may surface,
+  with a live or degraded binding to an entity that names a file. It carries no records, prints
+  `{}` where there is nothing anchored to code, and, like `PreToolUse`, reads the index directly
+  and builds no `Store`. `SIDEGRAPH_SUBAGENT_BRIEF=off` disables it. Codex records trust per hook
+  definition, so approve the new hook once in `/hooks`; manual recipes for both hosts gain the
+  entry. See the [hooks reference](docs/reference/hooks.md#sidegraph-subagent-start).
+
+### Changed
+
+- **The capture nudge comes back after more work, instead of firing once per session.** A session
+  that runs for a day and spawns subagents used to get one chance to record what it decided, at
+  its first substantial `Stop`, often before the work worth recording. A session that was already
+  nudged is now nudged again when at least 30 minutes have passed since its last nudge and at
+  least 10 commits authored since then are reachable from a local branch or `HEAD`; the text of
+  that nudge ends with `Since the last capture prompt: N commits.`, and the first nudge is
+  unchanged. The count is one `git log --branches HEAD`, run in the project the store belongs to
+  with a 2-second timeout, and it goes by author dates, so a rebase or cherry-pick of old commits
+  is not new work. A git failure means no re-arm. The last nudge is the meta key
+  `capture_rearm:<session>`, which the first nudge writes too and SessionStart expires after 30
+  days; a session captured by an older version has no key and counts from the `captured_at` of its
+  `capture_sessions` row. The new stamp is written with a compare-and-swap, so two parallel `Stop`
+  hooks cannot both nudge. A `Stop` inside the 30 minutes still exits on the read-only peek and
+  runs no git: a subprocess measured on a copy of this repository's store with a 1,000-commit
+  repository takes about 39 ms inside the gap and about 47 ms past it with too few commits. The
+  nudge's length bound is 850 characters, up from 800, for the added sentence. The count includes
+  commits that other sessions or people make on the same machine's branches.
+  `SIDEGRAPH_CAPTURE_NUDGE=off` silences re-armed nudges too. See the
+  [hooks reference](docs/reference/hooks.md#re-arm-after-more-work).
+
+- **`PreToolUse` hands the agent the records of a file when it reads or edits it, instead of
+  asking it to fetch them.** The hook used to print a one-line nudge (a count, or the titles of
+  two records) and ask the agent to call `get_task_context`, which for a tool the host lists only
+  by name means loading it first. In the field study the one nudge that named a record worked and
+  the five that named counts did not, Edit and Write never nudged, and Bash, which is how current
+  Claude Code reads and searches, was never wired. The hook now prints the records themselves: the
+  guard line, then for each file a header and its top two records (three when the first two are
+  mistakes), each as `- [kind] title — first sentence of the choice (id …)`, accepted mistakes
+  first, proposals last and marked `[unratified]`, and a `More: get_task_context(files=[…])` line
+  when records were left out. It covers `Read`, `Grep`, `Edit` and `Write`, and four Bash read
+  commands, `sed`, `grep`, `rg` and `cat`, wired as four `if` entries on one command (`if` needs
+  Claude Code 2.1.89 for correct matching; an older host runs the hook on every Bash call, which
+  exits early with no output). A Bash line delivers the first three files it reads that have
+  records. Each file arrives once per agent, and an agent receives at most ten files: one SQL
+  statement counts and inserts a `pretool_file:<session>:<agent>:<path>` key, where `<agent>` is
+  `-` for the session's own agent, so concurrent hooks cannot exceed the cap. The counting form
+  (`this project has a decision memory … N domains, M decisions`) is gone, the `pretool_nudge:`
+  and `pretool_nudge_path:` keys are no longer written (SessionStart still prunes them, and the
+  new keys after 30 days), and a Bash read is still not a touch event. **`SIDEGRAPH_GREP_NUDGE=off`
+  keeps its name and now turns off all of this**, on every tool that reads (not the `Agent`
+  brief below, which has its own switch); it stops neither the hook from
+  launching on a Bash call nor touch recording. A subprocess median of nine on this repository's
+  store: about 26 ms when nothing is delivered, about 35 ms for a `Read` of the file with the most
+  records, about 38 ms for a Bash line naming three anchored files. A hand-wired
+  `.claude/settings.json` gains the Bash group (see the
+  [setup guide](docs/getting-started/claude-code-setup.md#2-add-the-hooks)). The `PreToolUse`
+  commands, in the plugin and in that snippet, no longer set `SIDEGRAPH_GRAPH`, which the hook
+  never read: Graphify's `graphify claude install` and `uninstall` remove a `Bash` entry whose
+  text mentions `graphify`, and would otherwise have removed the hand-wired group. See the
+  [hooks reference](docs/reference/hooks.md#sidegraph-pre-tool-use).
+
+- **The plugin's hot hooks start from the commit `SessionStart` resolved, not from `@main`.**
+  `uv` re-resolves a branch reference on every call, about 0.8 s on a warm cache, and `Stop` and
+  `PreToolUse` run many times a session. `SessionStart` now records the commit `uv` resolved for
+  an `@main` install in `${XDG_CACHE_HOME:-$HOME/.cache}/sidegraph/launch-commit`: 40 hex bytes,
+  one file per machine, never written by an install pinned to a tag or SHA, an editable install
+  or a PyPI install. The public `Stop` and `PreToolUse` commands (Claude Code) and `Stop` (Codex)
+  launch `uvx --from` that commit, which `uv` serves from its cache in about 0.2 s, and fall back
+  to `@main` when there is no valid file, as before. A plugin pinned to a tag or commit ignores
+  the file and launches its own ref. `SessionStart` and the MCP server still run `@main`. A release therefore reaches a running session at the next `SessionStart` on the
+  machine, in any project and either host, not at its next hook call. The Codex `Stop` command is
+  wrapped in `sh -c '…'` so a fish login shell parses one literal. Codex records trust per hook
+  definition, so approve the changed `Stop` hook once in `/hooks`; the command no longer changes
+  between releases. `sidegraph-bootstrap`'s verification finds an entry point inside such a
+  `sh -c` script. See [troubleshooting](docs/guides/troubleshooting.md#the-launch-commit-file).
+
+- **`PreToolUse` and `Stop` start about three times faster, and a tool call no longer creates a
+  store.** `import sidegraph.<anything>` used to load pydantic, ulid and every model, and
+  `PreToolUse` constructed a `Store`, which walks every record file, once for the touch row and
+  once for the nudge. The package root now resolves its re-exports on first access;
+  `PreToolUse` reads and writes `index.db` through one raw SQLite handle, with the same nudge
+  text, the same one-shot claim and the same touch row; and `Stop` imports `Store` only past its
+  early exits. On this repository's own store (about 1,500 record files), a subprocess median of
+  nine: a hook call that does nothing falls from about 83 ms to about 25 ms, an `Edit` from about
+  96 ms to about 30 ms, a `Read` from about 127 ms to about 35 ms, and the two `Stop` early exits
+  from about 87 ms to about 34 ms. The handle trusts the index as the last full open left it and
+  does nothing, printing `{}`, when the index is missing, a store-owned entry is a symlink, the
+  `schema_version` is not this version's, `retrieval_events` has no `agent` column, or opening it
+  fails. A `Store` open (a `SessionStart`, a command, a started MCP server) repairs a missing, empty or
+  older-layout index and refuses a symlinked entry or an unknown `schema_version`, as before; a
+  running server does not recreate a deleted index. A write that waits out the one-second lock timeout is not
+  retried in that run. **Behaviour change:** a `Read` or
+  `Edit` in a project without a store no longer creates `.sidegraph/`, and the nudge path no
+  longer prints "creating new store"; `SessionStart` and the MCP server still create the store.
+  A record that arrives mid-session can be missing from the nudge's titles until the next MCP
+  call. See the [hooks reference](docs/reference/hooks.md#sidegraph-pre-tool-use).
+
+### Fixed
+
+- **A finished background agent, an agent-team message or a `!` command's output no longer counts
+  as a typed prompt.** Claude Code writes each of these into the transcript as a `type: "user"`
+  line without the `isMeta` flag, so the `Stop` gate counted it: a session with one request and two
+  background agents passed the two-prompt gate at its first stop, and the capture nudge, which fires
+  once per session, was spent before there was anything to record. The gate now skips content that
+  starts `<task-notification>`, `<teammate-message` (the tag carries attributes, and is how a
+  teammate's own session receives a message), `Another Claude session sent a message` (how the
+  lead's session receives one) or `<bash-stdout>`, next to the three slash-command wrappers it
+  already skipped. It also skips a line that newer Claude Code marks with
+  `origin.kind: "task-notification"` or `promptSource: "system"`, which catches task
+  notifications written in plain prose. A slash command the
+  person typed, which starts `<command-message>`, and a `!` command's own `<bash-input>` still
+  count. Codex rollouts share the prefixes. See the
+  [hooks reference](docs/reference/hooks.md#sidegraph-stop).
+- **A running MCP server sees a record that arrives mid-session.** The server keeps one `Store`,
+  and a `Store` checks the record files only when it is opened, so after a `git pull`
+  `get_task_context` and `retrieve_decisions` kept answering from the index as it stood until the
+  server restarted. The `PreToolUse` hook, which opened a `Store` on every call, was what
+  refreshed it, by accident. Every tool call now first re-checks the record files: a digest walk
+  (about 8 ms on 1,500 files), and a rebuild only when something changed. A filesystem error during
+  that check, such as a checkout deleting a record file mid-walk, does not fail the call: the tool
+  answers from the previous index and one line goes to stderr.
+- **One record file that does not parse no longer switches memory off.** A merge that left
+  conflict markers in a decision, entity, fact or bindings file made the index rebuild raise, so
+  the store could not be opened: every hook fell back to "cannot open its store", and the MCP
+  server served nothing. The rebuild now skips such a file, whether it is invalid JSON, invalid
+  UTF-8, a wrong shape, rejected by its model or impossible to serialise, lists it as
+  `parse-error`, and loads the rest. The usual notice names the first such file, and
+  `sidegraph-verify` reports each of them; a file that fails validation no longer hides its
+  archived copy. A bindings file is skipped whole, so a half-valid file never leaves half of its
+  anchors in the index, and its record stays retrievable without them. A file that cannot be
+  opened at all (a permission or I/O error) still fails the open.
+- **An archive line that cannot be read costs that line, not the store.** A line of an archive
+  segment that is not valid UTF-8 or JSON, or whose decision or domain fails its model, is skipped
+  with a warning in the rebuild, the rest of the segment loads, and the segment is listed as
+  `bad-archive-segment`. `sidegraph-verify` reports each such line with its segment and line
+  number. `sidegraph-compact` keeps the strict rule: it refuses to run over a segment it cannot
+  fully read and names the segment and the line (`--dry-run` included, with exit code 1 and no
+  traceback), and a hot file the rebuild left out no longer makes `--dry-run` fail with a bare
+  `JSONDecodeError`.
+- **A file the rebuild left out is never overwritten.** With the store open again, a write that
+  recomputes a record's bindings from the index (`add_anchors`, `add_binding`) would have replaced
+  a conflicted bindings file with only the new anchor. All six canonical writers now refuse to
+  replace a listed file, with an error that names it. `add_anchors` checks first, so its refusal
+  leaves no orphan entity file behind. `supersede_decision` and `supersede_fact` refuse to inherit
+  anchors from a predecessor whose bindings file is skipped, since the successor would silently
+  start with none. `sidegraph-doctor` now says a skipped bindings file is skipped (unreadable),
+  not absent or empty. While an entity file is skipped, an anchor to the
+  same name mints a second entity, which `sidegraph-doctor`'s `duplicate-entity` check shows once
+  the file is fixed.
+- **The skip warning no longer says "remove".** Removing a record file breaks the append-only
+  store, and removing an archive segment destroys every archived record in it. The warning now
+  says to restore the file with git or fix it by hand, and never to delete a segment. The
+  `store-files-skipped` notice says the same when the first listed file is an archive segment:
+  its lines that could not be read are left out, restore it with git, never delete it.
+- **`sidegraph-verify` and `sidegraph-doctor` report what the rebuild leaves out.** They read an
+  archive segment as one string, so a line of invalid UTF-8 made them exit 1 with "store not
+  readable" and no file, and a line whose decision or domain fails its model was not reported at
+  all. They now split a segment into lines as bytes and report each bad line as
+  `bad-archive-segment`, with its segment and line number. A record file of invalid UTF-8, one
+  nested past the recursion limit and one that validates but cannot be serialised (a lone
+  surrogate) are `parse-error`s naming the file, where the first two exited 1 and the third
+  reported clean. A title holding U+2028 or U+0085 no longer gives a false `bad-archive-segment`.
+- **Compacting a decision whose title holds U+2028 or U+0085 no longer leaves a store that will
+  not open.** The archive reader split a segment with `str.splitlines`, which breaks a line at
+  those characters (the segment holds them raw), so the next rebuild raised "corrupt archive
+  segment". A segment is now split as bytes, at `\n` and `\r` only.
+
 ## [0.8.0] — 2026-10-03
 
 ### Added

{sidegraph-0.8.0 → sidegraph-0.10.0}/CLAUDE.md

@@ -13,7 +13,7 @@ task-aware retrieval + decision memory riding on the engine's entity graph.
 continuing participant in the project. A core feature must preserve, organize, or deliver
 accumulated project understanding. Document search by itself is not the product.
 
-Sidegraph is pre-1.0 (v0.8.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.10.0) — the full loop (capture, ratification, mistakes-first
 retrieval, refactor-surviving re-anchoring, semantic docs layer, mind-model domains, and the
 facts evidence layer) ships and is exercised end-to-end, but interfaces may still move before
 a stable release. See
@@ -53,11 +53,14 @@ src/sidegraph/
 ├── schema.py        # Pydantic models: Entity, Decision, Fact, AnchorBinding, Domain, Initiative
 ├── store.py         # owned append-only store (file-per-record JSON); enforces invariants on write
 ├── retrieval.py     # multi-altitude, budget-bounded, task-aware read path (mistakes first)
+├── hot_index.py     # raw-sqlite handle on index.db for the hook hot path (no Store, no pydantic)
+├── store_layout.py  # store constants and rules shared with the hot path (pydantic-free)
 ├── server.py        # FastMCP decision MCP — the tools agents call
 ├── engine/          # ── ENGINE SEAM ── the ONLY place Graphify specifics may live
 │   └── reader.py    #   GraphifyReader: reads graph.json (read-only input; no MCP)
-└── host/            # ── HOST SEAM ── Claude Code integration (SessionStart/Stop/PreToolUse)
-    └── hooks.py     #   host-specific; portable core never reaches in here
+└── host/            # ── HOST SEAM ── Claude Code integration (SessionStart/Stop/PreToolUse/SubagentStart)
+    ├── hooks.py     #   host-specific; portable core never reaches in here
+    └── subagent.py  #   SubagentStart: the memory brief for a starting subagent
 ```
 
 - **Portable core** (`schema`, `store`, `retrieval`, `server`) knows nothing about Graphify

{sidegraph-0.8.0 → sidegraph-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.8.0
+Version: 0.10.0
 Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
 Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
 Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph
@@ -21,7 +21,9 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.13
+Requires-Dist: anyio>=4
 Requires-Dist: fastmcp>=3.4
+Requires-Dist: mcp>=1.24
 Requires-Dist: pydantic>=2.9
 Requires-Dist: python-ulid>=3.0
 Description-Content-Type: text/markdown
@@ -73,14 +75,16 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```
 # 2. Inside a Claude Code session in that repo: install the plugin — MCP server + all
-#    three hooks, wired automatically.
+#    four hooks, wired automatically.
 /plugin marketplace add SantyagoSeaman/sidegraph
 /plugin install sidegraph@sidegraph
 ```
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -167,9 +171,13 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  next session ◀── SessionStart TOC            anchored to entities in the
  of named domains ◀── get_task_context ◀────── engine's graph (read-only);
  mistakes first        drill_down             re-anchored after refactors
- blind Read/Grep ──▶ nudged back to get_task_context (each form once per agent)
+ Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -213,7 +221,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -245,16 +253,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -267,7 +281,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.8.0 → sidegraph-0.10.0}/README.md

@@ -45,14 +45,16 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```
 # 2. Inside a Claude Code session in that repo: install the plugin — MCP server + all
-#    three hooks, wired automatically.
+#    four hooks, wired automatically.
 /plugin marketplace add SantyagoSeaman/sidegraph
 /plugin install sidegraph@sidegraph
 ```
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -139,9 +141,13 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  next session ◀── SessionStart TOC            anchored to entities in the
  of named domains ◀── get_task_context ◀────── engine's graph (read-only);
  mistakes first        drill_down             re-anchored after refactors
- blind Read/Grep ──▶ nudged back to get_task_context (each form once per agent)
+ Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -185,7 +191,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -217,16 +223,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -239,7 +251,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.8.0 → sidegraph-0.10.0}/SECURITY.md

@@ -25,10 +25,21 @@ Sidegraph is a local-only tool. Its entire data surface:
   the visualization, OKF export and bootstrap-report commands write to the output paths you
   give them; and the optional `sidegraph-prepare-commit-msg` git hook, once you install it,
   adds commented decision trailers to the commit message file git hands it
-  (normally `.git/COMMIT_EDITMSG`). Beyond those, the only filesystem writes are the standard config
-  snippets you install yourself (`.mcp.json`, hook entries) — Sidegraph touches nothing
-  else. See [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full
-  layout.
+  (normally `.git/COMMIT_EDITMSG`). Three more writes sit outside the repository's own
+  files. `sidegraph-init --hooks` (or a yes to its refresh question) writes a helper script
+  and a marked block in three git hooks (`post-commit`, `post-merge`, `post-checkout`) under
+  `.git/hooks/`. When `core.hooksPath` is set, `sidegraph-init` writes only the helper (to
+  `.git/hooks/`) and prints the lines to add to your hooks by hand. While it runs, the helper
+  also keeps a lock, a flag file and a log in the git directory. `sidegraph-init --no-hooks`
+  writes the git config key `sidegraph.graphRefresh` to the repository's own config, and
+  `sidegraph-init --remove-hooks` takes the blocks, the helper and that key out again. The
+  SessionStart hook writes one 40-character commit id to
+  `${XDG_CACHE_HOME:-~/.cache}/sidegraph/launch-commit`, and only when the running package was
+  installed from the canonical `git+https://github.com/SantyagoSeaman/sidegraph.git@main`. That
+  covers the plugin and the manual `uvx --from …@main` recipe. A PyPI, tag, SHA or editable
+  install never writes it. Beyond those, the only filesystem writes are the standard config
+  snippets you install yourself (`.mcp.json`, hook entries). See
+  [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full layout.
 - **Network:** none. No remote telemetry, no phone-home, nothing leaves your machine. Local
   retrieval telemetry is recorded in the gitignored `index.db` by default (which records
   were shown and which files were touched, never uploaded); set `SIDEGRAPH_TELEMETRY=off` to

{sidegraph-0.8.0 → sidegraph-0.10.0}/docs/concepts/data-model.md

@@ -238,7 +238,7 @@ for how this differs from a `Domain`.
 
 ## `schema_version` — a public contract
 
-`SCHEMA_VERSION` (currently `0.6.0` in `schema.py`) is stamped into the store's `meta` table
+`SCHEMA_VERSION` (currently `0.6.0`, defined in `store_layout.py` and re-exported by `schema.py`) is stamped into the store's `meta` table
 once, at creation, and checked for an **exact** match on the fast (digest-matches) freshness
 path — a mismatch there normally raises immediately rather than silently reading mismatched
 data. The one exception: a store stamped with a version in `_RELOADABLE_SCHEMA_VERSIONS`

{sidegraph-0.8.0 → sidegraph-0.10.0}/docs/concepts/mind-model.md

@@ -105,7 +105,7 @@ write below — the three raw authoring paths underneath it are:
    asked to) names a domain directly, optionally nesting it under a `parent_slug`.
 
 All three land `status=proposed`. **Every path passes through the same ratification gate** —
-the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, kept for one release)
+the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, still kept)
 and the `sidegraph-ratify` CLI, which list and accept/drop decisions *and* domains side by
 side. By default no path bypasses human review, including bootstrap: a fresh repo can
 propose dozens of domains from its community structure in one command, but nothing is named