recallium 1.2.6 → 2.0.8

package/bin/skills/cursor/team/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: team
+description: Answers questions about the people and the shared work on an enterprise Recallium deployment - who is on which team, what the team has been doing across the projects it owns, what is pending there, and which teammate wrote what. Use when the user asks "who's on my team", "what has the team been working on", "what's pending across our projects", "what did a teammate do last week", or before filtering a search by author; on a community deployment these tools are absent by design, not broken.
+---
+
+# Team
+
+## Quick start
+
+```
+list_team_members()                                   # every team you belong to; team_name="core" narrows
+team_recap(days_back=7)                               # all projects your team owns; project_name="my-api" narrows
+team_recap(project_name="my-api", include_tasks=True)
+search_memories(query="...", project_name="__all__", author_email="<exact email from list_team_members>")
+```
+
+## Why
+
+Team tools are the only view that crosses projects and people. `team_recap`
+aggregates recent memories and pending tasks over the projects the team OWNS
+and carries no per-user working state; `session_recap` is the personal view.
+The author filter on `search_memories` is an exact match, so the email must
+come from `list_team_members`, never from recollection.
+
+## Workflow
+
+1. **Gate:** enterprise. If the tool is not in the tool list, say so and fall
+   back to `session_recap` / `search_memories`; do not report it as broken.
+2. "Who is on the team" -> `list_team_members`. Takes no `project_name`;
+   `team_name` is a case-insensitive substring filter.
+3. "What has the team done" -> `team_recap`, 1-30 days back; narrow with
+   `project_name` when one project is meant.
+4. "What did X do" -> `list_team_members` for the exact email, then
+   `search_memories(author_email=..., project_name="__all__")`, because a
+   teammate's memories span projects.
+5. Patterns rather than activity ("what keeps going wrong across the team")
+   -> `get_insights` (see `resume`).
+6. **Gate:** report; store nothing. Someone's activity is not a new finding.
+
+## Anti-patterns
+
+WRONG: guessing a teammate's email for `author_email`.
+RIGHT: `list_team_members` first; the filter is exact.
+
+WRONG: `team_recap` for "where did I leave off".
+RIGHT: `resume`; the team view has no working state.
+
+## Checklist
+
+- [ ] Enterprise confirmed, or the fallback used
+- [ ] Right scope: every team project, or one
+- [ ] Author email taken from the tool, not recalled
+
+## See also
+
+`resume` (the personal view), `recall` (search by author), `project` (links
+between projects), `recallium-tools` (edition gates).

package/bin/skills/cursor/verdict/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: verdict
+description: Records one agent's judgment of another agent's output - a design, decision, answer, or memory - as a Recallium verdict on that target, so a parent agent can trust it without re-verifying. Use when you are acting as reviewer, critic, or judge of a specific memory and have reached a position on it; a verdict always names its target and is never stored as progress or a note.
+user-invocable: false
+---
+
+# Verdict
+
+## Quick start
+
+```
+expand_memories(memory_ids=["<target-uuid>"])
+store_verdict(target_memory_id="<target-uuid>",
+              decision="accept",            # accept | refute | revise
+              confidence=0.8,               # your certainty IN THIS JUDGMENT
+              reasoning="<self-contained evidence>",
+              project_name="my-api", workstream_slug="auth-hardening")
+```
+
+## Why
+
+A verdict is the convergence primitive: it is how a subtree of agents collapses
+to one trusted result. A false `accept` propagates unverified up the tree and
+poisons every ancestor that trusts it; a false `refute` costs one more round.
+So when in doubt, prefer a low-confidence `refute`. `confidence` is your
+certainty in the judgment, not the quality of the target: a confident refute is
+confidence 0.9 with decision `refute`.
+
+## Workflow
+
+1. **Gate:** `target_memory_id` is required and must be a real memory you can
+   see. Expand it first; judge what it says, not what you remember of it.
+2. Reach a position: `accept` (stands, build on it), `refute` (wrong or
+   unsound, do not build on it), `revise` (close; the changes are named in
+   your reasoning).
+3. Put the full evidence in `reasoning`. A parent may act on it without
+   re-checking, so it must be self-contained and must not present unverified
+   claims as established.
+4. One verdict per (you, target). A changed position is a new verdict that
+   supersedes your earlier reasoning; never edit the old one.
+5. Anchor it to the same `workstream_slug` as the target.
+
+## Anti-patterns
+
+WRONG: a review stored as `progress` or `note`.
+RIGHT: `store_verdict`; progress is a state timeline, not a judgment.
+
+WRONG: a verdict with no target, "the approach is fine".
+RIGHT: a verdict OF a specific memory UUID.
+
+WRONG: `accept` at confidence 0.5 because nothing looked wrong.
+RIGHT: if you are not sure, a low-confidence `refute` and the reason.
+
+## Checklist
+
+- [ ] Target UUID real and expanded
+- [ ] Decision and confidence set independently
+- [ ] Reasoning self-contained; no unverified claims as fact
+- [ ] Anchored to the target's workstream
+
+## See also
+
+`design` (what usually gets judged), `decide`, `capture`.

package/commands/doctor.md

@@ -0,0 +1,15 @@
+---
+description: Diagnose a Recallium install — credentials, home directory, hook binary, MCP registration
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+Run the doctor and report every failing check with its exact message, then the single most likely fix.
+
+A non-zero exit is expected whenever a check fails — that is the result, not a
+tool error. The full report is on stdout either way: summarise it, and never
+report the command as broken or retry it.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/recallium-hooks.cjs" doctor
+```

package/commands/login.md

@@ -0,0 +1,17 @@
+---
+description: Sign in to Recallium and enrol this machine's session sensor (browser sign-in, or a device code when no browser is available)
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+Run the Recallium login flow with the plugin's bundled binary and relay its output to the user verbatim. If it prints a URL and a device code, show both and wait for the user to confirm they have finished in the browser before checking status.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/recallium-hooks.cjs" login
+```
+
+When it exits, run the status check and summarise in one line whether the MCP server is reachable and whether the sensor is enrolled:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/recallium-hooks.cjs" status
+```

package/commands/status.md

@@ -0,0 +1,11 @@
+---
+description: Show Recallium status for this machine — MCP reachability, sensor enrolment, hook health
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+Run the status check and present the result as a short table. Do not paraphrase error text; quote it.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/recallium-hooks.cjs" status
+```

package/hooks/hooks.json

@@ -0,0 +1,88 @@
+{
+  "description": "Recallium session sensor — counts, paths and ids only; no prompt or file content leaves the machine. Injects working state at SessionStart and a recall nudge at UserPromptSubmit.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact|fork|clear",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event session_start", "timeout": 10 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event pre_tool_use_edit", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": "mcp__recallium[a-z0-9-]*__store_memory",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event pre_tool_use_store", "timeout": 10 }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event post_tool_use", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": "mcp__recallium[a-z0-9-]*__store_memory|mcp__recallium[a-z0-9-]*__create_workstream|mcp__recallium[a-z0-9-]*__create_task|mcp__recallium[a-z0-9-]*__update_task|mcp__recallium[a-z0-9-]*__search_memories|mcp__recallium[a-z0-9-]*__set_working_state|mcp__recallium[a-z0-9-]*__start_thinking|mcp__recallium[a-z0-9-]*__add_thought",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event post_tool_use_recallium", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event post_tool_use_command", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event post_tool_use_read", "timeout": 10 }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event user_prompt_submit", "timeout": 10 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event stop", "timeout": 10 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event subagent_stop", "timeout": 10 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event pre_compact", "timeout": 10 }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/recallium-hooks.cjs\" --event session_end", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,43 +1,40 @@
 {
   "name": "recallium",
-  "version": "1.2.6",
-  "description": "MCP client for connecting Cursor/VS Code to Recallium AI Memory Server",
-  "author": "Recallium Team",
-  "license": "MIT",
+  "version": "2.0.8",
+  "description": "Recallium client for coding agents: wires Claude Code, Codex, Cursor and other agents to your team's Recallium memory with hooks, skills and the MCP connector, and keeps your Recallium server in sync. Zero dependencies, never blocks the agent.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://recallium.ai",
+  "keywords": [
+    "recallium",
+    "memory",
+    "team-memory",
+    "mcp",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "copilot",
+    "hooks"
+  ],
   "type": "module",
   "bin": {
-    "recallium": "./bin/recallium"
+    "recallium": "./bin/recallium-hooks.cjs"
   },
-  "main": "src/index.js",
   "files": [
     "bin/",
-    "src/",
+    ".claude-plugin/",
+    "hooks/",
+    "commands/",
+    "skills/",
+    "plugin-manifest.json",
+    "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "test": "node src/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0"
-  },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
-  "keywords": [
-    "mcp",
-    "cursor",
-    "ai",
-    "memory",
-    "recallium",
-    "model-context-protocol"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/recallium-ai/recallium.git"
-  },
-  "homepage": "https://recallium.ai",
-  "bugs": {
-    "url": "https://github.com/recallium-ai/recallium/issues"
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.0.0"
   },
   "publishConfig": {
     "access": "public"

package/plugin-manifest.json

@@ -0,0 +1,128 @@
+{
+  "v": 1,
+  "tree": "recallium-claude-plugin",
+  "version": "2.0.8",
+  "built_at": "2026-09-28T21:04:44.328Z",
+  "files": [
+    {
+      "path": ".claude-plugin/plugin.json",
+      "sha256": "c20164fc3e566f93b9f85cc48b7451baca294d0d9cfc9e998bd5f41fda46500f",
+      "bytes": 539
+    },
+    {
+      "path": "bin/manifest.json",
+      "sha256": "5a24f2d8598b44ba4ad53afa64a5c5d91864e9adeba8aff92b401091c0e993f1",
+      "bytes": 228
+    },
+    {
+      "path": "bin/recallium-hooks.cjs",
+      "sha256": "5c97cfa65d61bf194c6f34f4a0abadde8d9b4146ff1345268aaa9c017495a78b",
+      "bytes": 1910828
+    },
+    {
+      "path": "commands/doctor.md",
+      "sha256": "17cf9a1f9da3742c9eac1c21d87e82e77f8a3e12710c0c8a507d3a8a6914d86f",
+      "bytes": 554
+    },
+    {
+      "path": "commands/login.md",
+      "sha256": "fcef4630c1be7e424b5ae0b1a9147a532e1e5eb88ed4a633827ee9ad79a937bc",
+      "bytes": 739
+    },
+    {
+      "path": "commands/status.md",
+      "sha256": "4656dcb41345d549b4210d78786f6a32b2bd49f7e1d50f98462fb902ead32b92",
+      "bytes": 351
+    },
+    {
+      "path": "hooks/hooks.json",
+      "sha256": "94724c7f9fcab3e93acaf0c6b980824594970e4c1ea33617656d58b3f837a069",
+      "bytes": 3269
+    },
+    {
+      "path": "skills/capture/SKILL.md",
+      "sha256": "6b9b5bc22b901454d860b7a83c962e043948f36c687903548e806ad88b7a8430",
+      "bytes": 3068
+    },
+    {
+      "path": "skills/curate/SKILL.md",
+      "sha256": "768aad551c30dd359187e7fc02696ebb7d667d5448ee213a29d0f46c80de88b8",
+      "bytes": 3129
+    },
+    {
+      "path": "skills/decide/SKILL.md",
+      "sha256": "a885477c10cea231919e919f6e0fde93a13ca4cb5f4bd9459ead76dc30b86fa9",
+      "bytes": 3076
+    },
+    {
+      "path": "skills/design/SKILL.md",
+      "sha256": "9292b87af9305bdf68722aa9348646f4eaeaba4e19000df81222bd13661b9d3e",
+      "bytes": 3169
+    },
+    {
+      "path": "skills/finish/SKILL.md",
+      "sha256": "a383dd5853868dbcfad1fb51cc52ce162f8a723f204b5af2e3261c75f660ca70",
+      "bytes": 4564
+    },
+    {
+      "path": "skills/handoff/SKILL.md",
+      "sha256": "c756de71bad0dd6249afc2f34e5212d108f8d236e2e6b2aa412046d466448d12",
+      "bytes": 3078
+    },
+    {
+      "path": "skills/investigate/SKILL.md",
+      "sha256": "a01f9e8a7200df3dc91993d9efac10238327817a4e888dcb8ff242a107d77842",
+      "bytes": 4872
+    },
+    {
+      "path": "skills/project/SKILL.md",
+      "sha256": "40ad791f3966b37280b07bc393ac13bf0250142e0f6209e310a99bb874c397e5",
+      "bytes": 2962
+    },
+    {
+      "path": "skills/recall/SKILL.md",
+      "sha256": "edb4635630e1882d90bb706e908ea673dabe715b2219e447a62f25887ae8e609",
+      "bytes": 5278
+    },
+    {
+      "path": "skills/recallium-guidance/SKILL.md",
+      "sha256": "5fc11247ace5f4e8e9e545abbe2c7e854f2560ae7ffad6dafbe9813130c828d3",
+      "bytes": 17720
+    },
+    {
+      "path": "skills/recallium-guidance/reference.md",
+      "sha256": "69823d5d42244fddf36290ffc836f2a0d2d0f3e6b2c525831e016156bca7d6f9",
+      "bytes": 6109
+    },
+    {
+      "path": "skills/recallium-tools/SKILL.md",
+      "sha256": "f651cda91b645b29e320ec1849701be99d794f8a15631b263bc36b3b31ae7670",
+      "bytes": 2940
+    },
+    {
+      "path": "skills/resume/SKILL.md",
+      "sha256": "78e6b63f0fbaa07d37c19f1198f0c615e043257bf652279cdcf1d121f20a3c93",
+      "bytes": 3342
+    },
+    {
+      "path": "skills/rule/SKILL.md",
+      "sha256": "8c706e84f2fd0edaf07d66a80510daa5135f4064100d8022cdbf1a52c157554c",
+      "bytes": 2644
+    },
+    {
+      "path": "skills/start-work/SKILL.md",
+      "sha256": "6ff2952c9bc835e175c27b57fe07edd8dd62b6f5e95487454356b9abd7f28b56",
+      "bytes": 4523
+    },
+    {
+      "path": "skills/team/SKILL.md",
+      "sha256": "afde621571af67f437d470b2c65c8ecfadc8025fa697f13ade0840c53220d055",
+      "bytes": 2636
+    },
+    {
+      "path": "skills/verdict/SKILL.md",
+      "sha256": "712dc4a7c5a495e0527b7bfa30ae8bd6c08410cee5cd7f2f007a517f15c9ed14",
+      "bytes": 2624
+    }
+  ]
+}

package/skills/capture/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: capture
+description: Stores one durable why in Recallium - a learning from research or from a user correction, a constraint you hit, an experiment's numbers, a reusable snippet or runbook - behind the value gate, with its files and edges. Use when you found something out that a teammate could not reconstruct from the code and git log alone, or the user corrected you on how the system works; and use it to decide NOT to store when nothing new is being added - zero writes in a turn is valid.
+---
+
+# Capture
+
+## Quick start
+
+```
+store_memory(content="## Learned: <title>\n**Claim:** ...\n**Evidence:** ...\n**Consequence:** what to do differently",
+             project_name="my-api", workstream_slug="auth-hardening",
+             memory_type="learning", related_files=["src/auth/token-manager.ts"],
+             relationships=[{"target": "<design-uuid it bears on>", "type": "related"}])
+```
+
+## Why
+
+Two questions get confused, so separate them. **Cadence** asks when a real
+finding is written: one memory per finding as it lands, never batched. **The
+value gate** asks whether there is a finding at all: what NEW durable
+information does this add beyond the workstream already loaded? If none, skip.
+A second copy of the same state competes with the first in every future search,
+so storing it twice makes the original harder to find.
+
+## Workflow
+
+1. Gate it. Restated state, anything reproducible from a command, a paraphrase
+   of the diff, what you are about to do next: not a memory. The last one is
+   `set_working_state`.
+2. Type, first match wins: chose X over Y -> `decision` (`decide`) | imposed
+   bound -> `constraint` | ran a method, have numbers -> `experiment` | defect
+   -> `bugfix` (`investigate`) | architecture -> `design` (`design`) | reusable
+   code or command -> `code-snippet` | how to operate or roll back -> `runbook`
+   | durable claim about behaviour, incl. a user correction -> `learning` |
+   else -> `note`. `task`, `rule`, `verdict` have their own tools.
+3. **Gate:** `workstream_slug` is mandatory; none yet -> `start-work`.
+4. Search the workstream for what this builds on, replaces, bounds or
+   contradicts; attach those UUIDs. `supersedes` means the target is now WRONG.
+   `expand_memories` a hit before you cite it: an edge to a memory you have
+   not read is a guess.
+5. `related_files`: every file read or written. In a chat with no repository,
+   leave it empty; never invent paths.
+6. Read the store response: "unanchored" -> repair now with `modify_memory`;
+   a suggested file or edge -> take it.
+7. `importance_score` 0.9 / 0.7 / 0.5 / 0.3, auto-scored if omitted.
+
+## Anti-patterns
+
+WRONG: a code-related memory with empty `related_files`.
+RIGHT: every file touched, so `search_memories(file_path=...)` finds it later.
+
+## Checklist
+
+- [ ] Value gate applied; could this have been zero writes?
+- [ ] Canonical type, slug, files, at least one edge
+- [ ] Store response read; anchor and suggestions acted on
+
+## See also
+
+`investigate`, `finish` (the checkpoint half), `decide`, `design`, `curate`, `rule`.

package/skills/curate/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: curate
+description: Corrects, retires, or closes what Recallium already holds - a wrong memory superseded, a duplicate or mistaken memory inactivated, a stale task inactivated, a workstream marked shipped or abandoned when the effort ends. Use when the user says "that's wrong", "forget that", "we dropped that approach", when a PR merges or a branch is abandoned, or when a search returns two memories saying the same thing; never delete, and store nothing new unless the correction itself is a finding.
+---
+
+# Curate
+
+## Quick start
+
+```
+expand_memories(memory_ids=["<uuid>"])                                   # read before touching
+modify_memory(memory_id="<uuid>", action="update", content="...", related_files=[...])
+modify_memory(memory_id="<uuid>", action="inactivate", reason="duplicate of <uuid>")
+modify_memory(memory_id="<workstream-uuid>", action="update", status="shipped")   # or "abandoned"
+```
+
+A content edit gives the memory a new id; use the id the response names.
+
+## Why
+
+The value gate has two halves. Storing only new durable information is one; keeping
+what is stored true is the other. A wrong memory that stays visible is worse than
+none: the next agent acts on it. A duplicate competes with the original in every
+future search, so cleanup restores findability the gate was protecting. Nothing is
+ever deleted: `inactivate` keeps the row for undo, `supersedes` keeps the chain,
+and an abandoned workstream is information about a dead end.
+
+## Workflow
+
+1. `expand_memories` the target first; judge what it says.
+2. Pick the operation by what is wrong:
+   - factually wrong, but the shape is right -> `modify_memory(action="update")`
+     with new `content`; additive for `tags`, `related_files`, `relationships`.
+   - superseded by a better decision, design, learning or runbook -> a NEW
+     memory with a `supersedes` edge; the old one drops out of search and
+     stays in the chain. **Gate:** never supersede `progress`.
+   - duplicate or mistaken -> `modify_memory(action="inactivate", reason=...)`.
+     `reason` is required. `reactivate` undoes it.
+   - unanchored -> `modify_memory(..., workstream_slug=...)`.
+3. Effort over: `modify_memory(memory_id="<workstream-uuid>", action="update",
+   status="shipped")` on merge, `"abandoned"` on a dead end. Close its tasks:
+   `update_task(status="completed")` for done, `update_task(status="inactive",
+   reason=...)` for stale or duplicate; `task_id` takes a list.
+4. A user correction is a `rule` (preference) or a `learning` (fact); either
+   may also mean a wrong memory to fix here.
+
+## Anti-patterns
+
+WRONG: editing a decision in place when the choice changed.
+RIGHT: a new decision with `supersedes`; the chain is the history.
+
+WRONG: leaving a shipped effort `active`.
+RIGHT: status `shipped` at merge; the roster stays honest.
+
+## Checklist
+
+- [ ] Target expanded before any change
+- [ ] Right operation: update, supersede, inactivate, re-anchor
+- [ ] Nothing deleted; every inactivation has a reason
+- [ ] Workstream status and its tasks closed when the effort ended
+
+## See also
+
+`capture`, `decide`, `finish`, `rule`, `recall`.

package/skills/decide/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: decide
+description: "Compare implementation alternatives and recommend a choice with its rationale. Use when the user asks which option to choose, including a small or previously settled choice; the workflow determines whether new reasoning or storage is needed. Use design to form an architecture or approach, and recall to retrieve an earlier decision without reconsidering it."
+---
+
+# Decide
+
+## Quick start
+
+```
+r = start_thinking(goal="Choose the auth strategy for the mobile app",
+                   project_name="my-api", workstream_slug="auth-hardening")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="hypothesis")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="reasoning")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="conclusion")
+```
+
+## Why
+
+A `conclusion` thought auto-stores a `decision` memory, born anchored to the
+workstream passed at `start_thinking`, so the rationale is captured with the
+choice instead of reconstructed from the diff later. The sequence is the audit
+trail: the rejected options and why they lost are the reusable half. A sequence
+left open stores nothing; the Stop hook will say so.
+
+## Workflow
+
+1. **Gate:** is there a real alternative? No trade-off -> not a decision; use
+   `capture` with the right type, or store nothing.
+2. Retrieve prior decisions and constraints. If an applicable decision already settles the request, explain it and stop without starting a sequence or storing a duplicate. A constraint may have removed an option.
+   For a routine choice with no durable project consequence, answer with the relevant trade-off and store nothing. Use a thinking sequence for a new consequential choice.
+3. `start_thinking(goal=..., project_name=..., workstream_slug=...)`.
+   **Gate:** pass `workstream_slug` here; the auto-stored decision inherits
+   it. The server warns if you omit it; pass it now rather than backfilling.
+4. `add_thought` per step: `observation`, `hypothesis` (the options),
+   `question`, `reasoning` (what rules options out), `analysis`, `branch`,
+   `conclusion` (closes and stores; nothing can be added afterwards).
+5. The conclusion states Context / Options / Chosen and why / Consequences.
+6. Take its UUID. Edge it to the constraint that bounded it; put it in the
+   `Recallium-Memory:` trailer of the commit that implements it (`finish`).
+7. A later, better choice does not edit this one: a new `decision` with
+   `supersedes` pointing at it.
+
+## Anti-patterns
+
+WRONG: `start_thinking` without `workstream_slug`, then backfilling.
+RIGHT: pass the slug at `start_thinking`; the conclusion is born anchored.
+
+WRONG: recording only the option you picked.
+RIGHT: the rejected options and why they lost.
+
+## Checklist
+
+- [ ] A real alternative existed
+- [ ] Prior decisions and constraints searched
+- [ ] `workstream_slug` passed at `start_thinking`
+- [ ] Conclusion names options, choice, rationale, consequences
+- [ ] UUID captured for edges and the commit trailer
+
+## See also
+
+`recall`, `design`, `capture`, `finish`, `verdict`.