memorix 1.2.2 → 1.2.4

package/docs/1.2.4-PERSISTENT-MEMORY-DELIVERY.md

@@ -0,0 +1,86 @@
+# 1.2.4 Persistent Memory Delivery
+
+**Status:** release-ready
+**Date:** 2026-07-26
+
+## Problem
+
+Memorix already has durable project memory, Code State, session summaries,
+knowledge, visibility policy, CLI, and MCP. The delivery path was uneven:
+
+- A fresh agent without a visible MCP tool could guess through many CLI commands
+  before finding the relevant state.
+- The normal task Workset deliberately avoided generic old-chat dumping, but it
+  also hid the small amount of prior work that matters when a user says
+  "continue" or "take over".
+- A new retrieval path must not bypass the session visibility fix shipped in
+  1.2.3.
+
+This release improves delivery, not storage. It does not create a handoff
+database, a transcript archive, or another default MCP tool.
+
+## Product Contract
+
+| Situation | Delivery |
+| --- | --- |
+| Start a new, unrelated task | A bounded task Workset. No automatic prior-session text. |
+| Continue or take over prior work | The same Workset plus a bounded prior-work projection. |
+| MCP is available | Use the existing `memorix_project_context` tool with the real task. |
+| MCP is unavailable | Make one CLI call: `memorix resume "<task>" --json` for continuation or `memorix context "<task>" --json` for a new task. |
+| Claude Code hook is installed | An explicit continuation prompt receives the same bounded prior-work Workset through the official `UserPromptSubmit` context channel, unless `memory.inject = "silent"`. |
+| Read-only assessment | The brief may be read, but Memorix does not persist a new observation unless the user explicitly asks to save one. |
+| Need a deliberate session handoff | Keep using the explicit session/handoff surfaces; this projection does not replace them. |
+
+Continuation detection is independent of the underlying task lens. For example,
+"continue fixing the authentication timeout" is still a `bugfix` task, with
+bugfix verification guidance, plus bounded prior-work evidence.
+
+## Delivery Model
+
+```text
+Canonical project identity
+  -> existing SQLite sessions + durable observations + visibility policy
+  -> Task Workset
+       -> normal task: current facts, code state, selected evidence
+       -> continuation: normal task + one session summary + <=3 durable anchors
+  -> existing MCP Project Context, direct CLI Context/Resume, or an eligible host hook
+```
+
+The projection is intentionally small and source-aware:
+
+- The latest meaningful completed session summary is eligible.
+- At most three durable decision/fix/discovery-style observations are eligible.
+- Project, team, and personal visibility is enforced with the caller's reader.
+- The `ContextReceipt` records selected or budget-withheld continuation items.
+- Current code remains the authority; historical material is a lead, not an
+  instruction.
+
+## Explicit Non-Goals
+
+- Do not inject arbitrary transcript history into every request.
+- Do not infer continuation from every mention of a past file or release.
+- Do not add a separate `handoff` store or duplicate session memory.
+- Do not add an eighth default MCP tool merely for CLI parity.
+- Do not make an unbound terminal see personal or team-scoped memory.
+
+## Acceptance Gates
+
+1. A normal new task has no `Resume from prior work` section.
+2. A continuation task has a bounded section and keeps its real task lens.
+3. `memorix resume` and `memorix_project_context` share the Workset contract.
+4. A foreign identity cannot receive personal continuation evidence.
+5. Generated guidance performs one precise CLI fallback instead of help/search
+   enumeration or inferring an empty memory store from project files.
+6. Compiled package smoke proves CLI positional parsing and stdio MCP output.
+7. Claude Code receives an explicit continuation through its official
+   `UserPromptSubmit.additionalContext` path; an unrelated prompt stays quiet.
+8. A fresh agent-style user path evaluates the installed package without
+   modifying the maintainer's real agent configuration.
+9. A fresh package installation whose optional native SQLite binary cannot load
+   still preserves the same `memorix.db` across separate CLI and hook processes
+   through the supported Node 22 SQLite fallback.
+10. A successful Autopilot brief preserves the exact continuation flag/path or
+    command needed to act, and does not trigger redundant memory retrieval by
+    default.
+11. A read-only continuation assessment neither replays already-delivered
+    durable evidence nor writes a new memory without an explicit user request.

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -38,7 +38,7 @@ For the 1.2 release line, the visible product shape is:
 - model lanes are separate: `[memory.llm]` for formation/rerank/summaries, `[embedding]` for semantic search, `[agent]` for the model memcode talks to while coding
 - legacy `memorix.yml`, `.env`, and `~/.memorix/config.json` are compatibility inputs, not the recommended setup path
 - generated agent rules treat `memorix_session_start` as optional unless explicit session semantics matter
-- `memorix_project_context` / `memorix context --task "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump
+- `memorix_project_context` / `memorix context "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump; `memorix resume "..."` is the explicit CLI continuation projection
 - Code State keeps local snapshots and freshness links; a healthy pre-existing local CodeGraph index can add a bounded semantic outline, but Memorix never initializes or synchronizes that external index itself
 - `memorix knowledge` is an explicit review path for source-backed Markdown knowledge and canonical workflows. Do not initialize a versioned workspace or apply a proposal unless the user asks for that managed artifact
 - integration surfaces are agent-specific: Claude Code, Codex, GitHub Copilot CLI, Antigravity, and Hermes receive plugin packages; OpenClaw receives a compatible bundle; Pi and Oh-my-Pi receive package entries; Gemini CLI receives an extension package; OpenCode receives a plugin file and skill; Cursor and other agents receive MCP/rules/hooks where supported
@@ -766,6 +766,18 @@ memorix doctor
 
 to inspect active runtime status.
 
+### 9. Does a fresh CLI install report a `better-sqlite3` binding error?
+
+On the supported Node 22 runtime, current Memorix releases automatically use
+Node's built-in SQLite with the same local `memorix.db` when the optional
+`better-sqlite3` native binary is unavailable. Upgrade the package and rerun
+the command; do not delete the data directory or create a replacement database.
+
+Node may print its own experimental SQLite warning on that fallback path. It is
+not a memory-loss condition. If Memorix instead reports that SQLite is
+unavailable, confirm the installed Node version satisfies the package engine
+and include the exact error when filing an issue.
+
 ---
 
 ## 11. What Not to Do

package/docs/API_REFERENCE.md

@@ -59,7 +59,7 @@ The current CLI namespaces are:
 Typical examples:
 
 ```bash
-memorix --cwd /path/to/repo context --task "continue auth bug"
+memorix --cwd /path/to/repo resume "continue auth bug"
 memorix identity join --agent-type codex --name codex-main
 memorix session start --agent codex-main --agent-type codex --join-team --use
 memorix memory search --query "release blocker"
@@ -96,6 +96,8 @@ memorix codegraph status
 memorix codegraph status --json
 memorix context
 memorix context --task "continue auth bug"
+memorix context "continue auth bug"
+memorix resume "continue auth bug"
 memorix context --task "prepare 1.1.7 release"
 memorix explain
 memorix codegraph context-pack --task "continue auth bug"
@@ -107,11 +109,11 @@ MCP:
 - `memorix_codegraph_status` returns provider/index counts for the current project.
 - `memorix_context_pack` builds a task-specific packet with reliable current memories, lower-trust unbound memories, current code facts, freshness warnings, suggested reads, and suggested verification.
 
-`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
+`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Continuation delivery is separate from the task lens: continuation language in `memorix_project_context` enables a bounded prior-work projection, and `memorix resume "..."` makes that choice explicit. It includes only the latest useful session summary and up to three readable durable memories; ordinary new tasks do not receive historical-session context. A completed MCP brief is the default retrieval boundary: search, detail, or Context Pack should expand it only for a named missing fact or an explicit request for deeper history. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
 
 Project-specific generated, vendored, or cache paths can be excluded from Code State with `[codegraph].exclude_patterns` in `memorix.toml` or `~/.memorix/config.toml` (`codegraph.excludePatterns` in legacy YAML). User patterns extend the built-in excludes and are applied to indexing, Project Context suggested reads, and Context Pack suggested reads.
 
-SessionStart hooks keep the default minimal hint lightweight. When memory behavior is configured with `sessionInject=full`, Memorix injects the compact Memory Autopilot brief at session start instead of only listing recent text memories.
+SessionStart hooks keep the default minimal hint lightweight. When memory behavior is configured with `sessionInject=full`, Codex receives the compact Memory Autopilot brief at session start instead of only listing recent text memories. Claude Code delivers an explicit continuation through its official `UserPromptSubmit` context channel, so a user saying “continue” receives the bounded prior-work brief even under the default minimal setting. Set `memory.inject = "silent"` to disable automatic hook delivery.
 
 The intended loop for agents is: get the project brief when it helps, inspect the suggested current files, use stale or unbound memory only as a lead, store durable outcomes after the work changes the project, and resolve obsolete memories.
 
@@ -220,6 +222,10 @@ require a joined coordination identity; a personal record is readable only by
 its creator and explicitly named recipients. Supplying a `topicKey` never
 lets an agent overwrite a record outside its write scope.
 
+When the current Autopilot task is read-only or explicitly says not to modify
+files, `memorix_store` returns without writing. Use `overrideReadOnly: true`
+only when the user explicitly asks to preserve a record during that task.
+
 Example:
 
 ```json
@@ -252,6 +258,8 @@ Important inputs:
 - `since`
 - `until`
 - `maxTokens`
+- `purpose` when deliberately expanding beyond the current Autopilot brief
+- `force: true` only when the user explicitly asks to re-read a record already represented in that brief
 
 Typical uses:
 
@@ -281,6 +289,8 @@ Global example:
 
 Fetch full observation detail.
 
+After `memorix_project_context`, use `purpose` only for a named missing fact. Set `force: true` only when the user explicitly asks for the full underlying record already represented in the brief.
+
 Supports two modes:
 
 - `ids` for current-project observations