recallium 1.2.6 → 2.0.8

package/skills/recallium-guidance/reference.md

@@ -0,0 +1,117 @@
+# Recallium reference
+
+Shapes, not rules. `SKILL.md` beside this file is the rulebook and carries the call shape needed to obey each rule it states; this file carries the worked `store_memory` examples, the footguns a tool schema does not tell you, and a six-row index. Parameter names themselves come from the tools' own input schemas — they are not repeated here.
+
+## Worked shapes
+
+### A bugfix
+
+```python
+store_memory(
+    content="""
+    ## Fixed: <short title>
+    **Problem:** <what was broken / why>
+    **Solution:** <what changed and why this approach>
+    **Files:** <key files + what changed in each>
+    **Testing:** <how verified>
+    """,
+    project_name="my-api",
+    workstream_slug="auth-hardening",
+    memory_type="bugfix",
+    related_files=["src/auth/token-manager.ts", "src/api/client.ts"],
+    tags=["authentication", "race-condition"],
+    relationships=[{"target": "<design-uuid the defect lived under>", "type": "related"}],
+    importance_score=0.8,
+)
+```
+
+### A decision
+
+```python
+store_memory(
+    content="""
+    ## Decided: recognition stays server-name-prefixed
+    **Context:** hook matcher must decide whether a tool call is recallium's store_memory.
+    **Options:** (a) match any mcp__*__store_memory; (b) keep mcp__recallium(-edition)?__ prefix; (c) thread a --server-name flag.
+    **Chosen:** (b). Installer owns the name; a generic match would capture other memory MCPs' stores.
+    **Consequences:** hand-renamed servers unsupported; (c) parked if custom names are ever needed.
+    """,
+    project_name="recallium-client",
+    workstream_slug="restructure-community",
+    memory_type="decision",
+    related_files=["src/cli/installer.ts", "src/adapter/canonical-events.ts"],
+    tags=["hooks", "server-naming"],
+    relationships=[
+        {"target": "<design uuid for the hook capture pipeline>", "type": "constrains"},
+        {"target": "<bugfix uuid for the 'nothing captured' defect>", "type": "related"},
+    ],
+    importance_score=0.8,
+)
+```
+
+### A commit checkpoint
+
+```python
+store_memory(
+    content="""
+    ## Landed: fix(hooks) match edition-suffixed server names
+    **SHA:** e436e0a4c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6
+    **Branch:** feature/restructure-community
+    **What it achieved:** settings.json matcher now fires for recallium-<edition> names; plain recallium still matches.
+    **Verified by:** vitest 1607/1607; regenerated matcher checked against recallium-saas-local; live capture in a fresh session.
+    **Next:** nothing on this branch; bin/ still parked.
+    """,
+    project_name="recallium-client",
+    workstream_slug="restructure-community",
+    memory_type="progress",
+    related_files=["src/cli/installer.ts", "src/adapter/canonical-events.ts", "test/installer.test.ts"],
+    tags=["hooks", "installer", "commit:e436e0a4"],
+    relationships=[
+        {"target": "01a06f00-4bdc-7158-b4ff-b43268b74e56", "type": "related"},
+        {"target": "01a06ee2-8c1d-7a90-b2e4-1f3a9c7d5e21", "type": "related"},
+    ],
+    importance_score=0.6,
+)
+```
+
+Net effect: `git log` → trailer → why. `search_memories(query="commit:e436e0a4", project_name="x")` → the checkpoint → what, how, files, and the why-edges. `get_workstream` → the whole journey.
+
+## Footguns
+
+Things the input schema will not warn you about:
+
+- `update_task(task_id=…, status="completed")` closes a task; `task_id` takes one UUID or a list, so several close in one call. Closing goes through the status field, never a separate tool.
+- `list_tasks` returns open tasks only; pass `include_completed=True` for history.
+- `update_task(status="inactive", reason=…)` and `modify_memory(action="inactivate")` are soft deletes. Nothing in Recallium is ever deleted.
+- `expand_memories` takes at most 10 memory ids per call.
+- `relationships` supersedes the deprecated `related_memory_ids`; keep using `relationships`.
+- `get_workstream` with an unknown slug returns fuzzy-matched candidates, not an empty result — read them before creating a second workstream.
+- `search_memories`: `recent_only=True` is a fixed last-30-days window while `days_back=N` is the last N days, and `file_path` takes ILIKE wildcards (`"%installer.ts%"`, `"src/auth/%"`).
+- `create_project` is idempotent and metadata-only; there is no delete, so `update_project(status="inactive")` retires a project and `status="active"` restores it.
+- `list_team_members` takes NO `project_name`; `team_recap` takes an optional one.
+- `get_insights(analysis_type=…)` accepts `comprehensive`, `patterns`, `quality`, `technical_debt`, `learning`, `productivity`, `progress`.
+
+### Rules
+
+The one signature worth writing out, because `scope` and `priority` are not reconstructable:
+
+```python
+store_rule(
+    body="Always use uv instead of pip",   # the rule text is `body`, not `content`
+    scope="project",                        # project | user | team (SaaS); project | install (community); global -> install
+    project_name="my-project",              # REQUIRED when scope="project"
+    priority="important",                   # critical | important | normal (a 0.0-1.0 float also works)
+)
+store_rule(rule_id="<id>", action="deactivate")   # remove; get the id from get_rules
+```
+
+## Index
+
+| Goal | Sequence |
+|------|----------|
+| Start a session | `recallium(project_name)` → `get_working_state` → `get_workstream` for the roster → `get_workstream(slug=…)` on the one you are resuming |
+| Record a checkpoint | a `progress` memory; tag it `commit:<short-sha>` if a commit landed; `update_task(task_id=…, memory_ids=[…])` if it sits inside a task |
+| Link a commit to its why | the `Recallium-Memory:` trailer on the commit, carrying the why-memory UUIDs |
+| Link a why back to its commit | the progress memory: `commit:<short-sha>` tag, the commit's files, and `related` edges to the same UUIDs |
+| Connect new work to old | search the workstream first, then `relationships=[{"target": "<uuid>", "type": "related" \| "constrains" \| "contradicts"}]` |
+| Replace something now wrong | `relationships=[{"target": "<uuid>", "type": "supersedes"}]` on the memory that replaces it |

package/skills/recallium-tools/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: recallium-tools
+description: Maps the Recallium MCP tool surface — every tool name, the handler that owns it, whether it reads or writes, and which ones are enterprise-only. Use when you need an exact tool name or its arguments, when a call fails as an unknown tool, when deciding whether a capability exists in this edition, or before reaching for a Recallium tool you have not used in this project.
+user-invocable: false
+---
+
+<!-- GENERATED by scripts/gen-tool-skill.mjs from packages/core/src/recallium_core/mcp/registry.py
+     and its handlers/ package. Do not edit by hand — run `npm run gen:tools`
+     (`npm run check:tools` fails CI on drift). -->
+
+# Recallium MCP tools
+
+## Quick start
+
+28 tools across 12 handlers. `R` reads · `W` writes · `E` enterprise-only.
+Argument schemas come from the live tool descriptions, not from here.
+
+- **Insights** — `get_insights` RE
+- **Memory** — `store_memory` W · `create_workstream` W · `get_workstream` R · `search_memories` R · `expand_memories` R · `modify_memory` W
+- **Project** — `create_project` W · `list_projects` R · `get_project` R · `update_project` W · `link_projects` W · `unlink_projects` W
+- **Rules** — `get_rules` R · `store_rule` W
+- **Session recap** — `session_recap` R
+- **Task** — `create_task` W · `list_tasks` R · `get_task` R · `update_task` W
+- **Team recap** — `team_recap` RE
+- **Teams** — `list_team_members` RE
+- **Thinking** — `start_thinking` W · `add_thought` W
+- **Validation** — `recallium` R
+- **Verdict** — `store_verdict` W
+- **Working state** — `set_working_state` W · `get_working_state` R
+
+## Why
+
+The surface is discovered, not declared: `HandlerRegistry.discover_handlers()`
+imports every `BaseHandler` subclass under `handlers/` and registers its
+`@mcp_tool` methods, skipping any handler whose `EDITION_REQUIRED` does not
+match the running edition. The list moves with the server, so it is generated
+from it rather than hand-maintained.
+
+## Workflow
+
+1. Find the tool by group above, then call it — its live description carries the
+   argument schema, always newer than any copy.
+2. **Gate:** `project_name` is required on nearly every tool.
+3. An `E` tool on a community server is not missing, it is gated; do not retry.
+4. **Gate:** `task`, `rule`, and `verdict` are not `store_memory` types —
+   they have their own tools above and soft-land as a `note` if you try.
+
+## Anti-patterns
+
+WRONG: guessing a tool name from a memory of the API.
+RIGHT: read it off this list; the generator keeps it true to the server.
+
+WRONG: editing this file when a tool is added.
+RIGHT: `npm run gen:tools` — hand edits are reverted by the next drift check.
+
+## Checklist
+
+- [ ] Tool name taken from this list, not recalled
+- [ ] `project_name` supplied
+- [ ] Edition gate considered before treating a tool as broken
+
+## See also
+
+`recallium-guidance` (the rules), `recall`, `capture`, `start-work`.

package/skills/resume/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: resume
+description: Rebuilds where the work stands from Recallium rather than from scrollback - working state, the workstream journey, open tasks, this session's recap, a timeline of recent sessions, or patterns across them. Use when the user asks "where did we leave off", "what did we do", "what's still open", "what have we been doing this week", "what keeps going wrong", when switching to another project, after days away, and after a compaction or /clear.
+---
+
+# Resume
+
+## Quick start
+
+```
+get_working_state(project_name="my-api")              # the raw note from last time
+get_workstream(project_name="my-api")                 # roster; "__all__" across projects
+get_workstream(slug="auth-hardening", project_name="my-api")
+list_tasks(project_name="my-api")                     # open only by default
+session_recap(project_name="my-api")                  # this session, or days_back=N
+search_memories(query=None, project_name="my-api", memory_type="progress", days_back=7)
+```
+
+## Why
+
+Scrollback vanishes at compaction. What Recallium holds is what was actually
+stored, so resuming from it is also a check: a recap thinner than the work means
+memories were never written. Progress memories are a timeline, so reading them
+in date order reconstructs how the work moved.
+
+## Workflow
+
+1. **Gate:** the `recallium` summon has returned this conversation; rules,
+   working state and open tasks arrive only with it. Switching project? Call it
+   again with the new `project_name`. No workspace and no project named?
+   Ask, else `"default"`.
+   If the resume buffer is a preview, tell the user what it holds, as a part of the note and not the whole state. End by saying, without character counts, that more context is available that gives the full picture, and offer to load it; when the user says "resume", call get_working_state first.
+2. Read `get_working_state`: branch, slug, in flight, parked, next action.
+3. Roster, then the slug you are continuing; constraints and decisions come
+   first and bound what you may do. `expand_memories` the ones that bound
+   this work and read them; a one-line title is not the decision.
+   **Gate:** slug loaded, and those read, before code.
+4. Triage `list_tasks`; `get_task` shows one task's linked memories. Pick up,
+   or hand stale ones to `curate`.
+5. Pick the window the question asks for: "this session" -> `session_recap`;
+   "this week" -> browse `progress` with `days_back` or `date_from`/`date_to`,
+   oldest first, `commit:<sha>` tags as the landed commits; "what keeps
+   recurring / what tech debt" -> `get_insights` (enterprise; an absent tool
+   is gated, not broken). Team-wide questions belong to `team`.
+6. **Gate:** report; store nothing. Reconstructing history is not new.
+
+## Anti-patterns
+
+WRONG: summarising from the conversation.
+RIGHT: `session_recap` first, then narrate what it returned.
+
+WRONG: `git log` as the history.
+RIGHT: the progress timeline has the why and the evidence; git confirms SHAs.
+
+## Checklist
+
+- [ ] Summon returned for the right project; working state read
+- [ ] Slug loaded before code; open tasks triaged
+- [ ] Right window and tool for the question
+- [ ] Any `<fun-lines>...</fun-lines>` in a result opened the reply verbatim
+
+## See also
+
+`start-work`, `recall`, `team`, `curate`, `handoff` (the other end), `recallium-guidance`.

package/skills/rule/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: rule
+description: Stores or retires a standing behavioural rule in Recallium's tiered rule store - never as a memory - and only when the user asks for one. Use when the user says "always do X from now on", "remember this rule", "add a rule that", "stop doing Y", or corrects you in a way they want kept across sessions; check get_rules first so an existing rule is never stored twice, and never author a rule on your own initiative.
+---
+
+# Rule
+
+## Quick start
+
+```
+get_rules(project_name="my-api")            # above-project tiers + this project's
+store_rule(body="Always use uv instead of pip", scope="project",
+           project_name="my-api", priority="important")
+store_rule(rule_id="<id>", action="deactivate")
+```
+
+## Why
+
+Rules load with every `recallium` summon and are enforced as rules, not
+suggestions. A rule the agent invented is the agent legislating for the user.
+A duplicate is two guardrails that drift apart. And `store_memory(memory_type=
+"rule")` does not create a rule; it silently lands a `note`, so you will think
+a rule exists and it will not.
+
+## Workflow
+
+1. **Gate:** the user asked, in words: "always", "never", "from now on",
+   "remember this rule". A one-off instruction for this task is not a rule.
+2. `get_rules(project_name=...)`. The tiers above the project are always
+   returned unfiltered. If the rule is already there, say so; do not re-store.
+   Never re-store a rule the summon returned.
+3. Scope: `project` when a project is named (requires `project_name`);
+   `user`/`team` on SaaS; `install` on community. Omit and it defaults to the
+   narrowest safe tier.
+4. Priority: `critical` | `important` | `normal` (a 0.0-1.0 float also works).
+   The rule text is `body`.
+5. Removing one: `store_rule(rule_id=..., action="deactivate")`. There is no
+   delete.
+6. A correction the user wants kept but that is project-specific behaviour
+   rather than a guardrail is often a `learning` (see `capture`) plus a rule,
+   not a rule alone.
+
+## Anti-patterns
+
+WRONG: turning "use the other endpoint this time" into a rule.
+RIGHT: follow it; rules are for "from now on".
+
+WRONG: `store_memory(memory_type="rule", ...)`.
+RIGHT: `store_rule(body=...)`.
+
+WRONG: storing the fun-line rule again because it appeared in a result.
+RIGHT: the summon says which rules already exist; those are never re-stored.
+
+## Checklist
+
+- [ ] User asked explicitly
+- [ ] `get_rules` checked; nothing duplicated
+- [ ] Scope and priority chosen; `body` is the text
+- [ ] Nothing the summon returned was re-stored
+
+## See also
+
+`capture` (a learning, not a rule), `resume` (rules arrive with the summon),
+`recallium-guidance`.

package/skills/start-work/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: start-work
+description: "Set up a new named feature or effort before implementation: retrieve settled context, establish its workstream and continuation plan, offer tasks when the work has two or more units, and write working state. Use for an explicit kickoff or when a body of work needs that setup. A bounded mechanical edit alone does not start a new effort. Create persistent tasks only when the user asks or says yes to the offer."
+---
+
+# Start work
+
+## Quick start
+
+```
+search_memories(query="<what this work is about>", project_name="my-api",
+                file_path="src/auth/%")
+get_workstream(project_name="my-api")                          # roster
+create_workstream(project_name="my-api", title="Auth hardening",
+                  status="active", attach=["<orphan-memory-uuid>"])
+# two or more units? ask once: "This is 3 units — rotate tokens, revoke on logout,
+# audit log. Track them as tasks?"  → on yes, one task per unit:
+create_task(project_name="my-api", task_description="Rotate refresh tokens",
+            workstream_slug="auth-hardening", memory_ids=["<design-uuid>"])
+set_working_state(project_name="my-api", content="branch / slug / in flight / next")
+```
+
+## Why
+
+Three traps live at the start of work. Re-deriving something a past session
+settled produces a second, conflicting answer. A store with no workstream does
+not fail; it lands where no `get_workstream` will replay it, so the next session
+re-derives what you just settled. A Recallium task persists, links to the
+memories that explain it, and resurfaces at the next summon - which is exactly
+why tasks are created only when the user chose to track the work; unchosen
+agent plans go in working state, where they expire harmlessly. But a task is
+also the best checkpoint for multi-part work: closing it on the commit that
+finishes it IS the checkpoint (see `finish`), so when the effort has several
+units the user must at least be offered them — one question, their answer.
+
+## Workflow
+
+1. Confirm a new effort needs setup. A self-contained edit with a specified result can be completed directly; its required memory lookup does not by itself require this workflow or a new workstream.
+   For an effort, search by intent and file. A prior decision or constraint may settle part of it. `expand_memories` the hits and read them before opening the files they name: a summary line is not the memory. Keep the UUIDs for edges.
+2. `get_workstream(project_name=...)` for the roster. Continuing something?
+   Open its slug. Nothing fits? `create_workstream(..., status="active")`.
+   **Gate:** the workstream exists before the first store, never after.
+   `attach` takes MEMORY UUIDs (never task ids) to adopt earlier orphans.
+3. Tasks. Did the user ask to create or track tasks? Then `create_task` per
+   requested piece, within the request's scope, slug at creation time
+   (`update_task` ignores `workstream_slug`). No request, but the effort
+   resolves into TWO OR MORE units (PRs, phases, deliverables)? **Gate:** offer
+   them once, naming the units — "This is N units: A, B, C. Track them as
+   tasks?" — and create one task per unit only on a yes, linked to the design
+   memory when one exists. A single unit, a no, or silence: the plan stays in
+   `set_working_state`. Never create tasks the user did not ask for or agree to.
+4. Work spans two repos? Link them once via `project`; a link is full
+   one-hop search visibility both ways.
+5. If a plan or design formed, store it now: see `design`. If not, store
+   nothing; setup is not a finding.
+6. `set_working_state`: branch, slug, in flight, parked, next action.
+
+## Anti-patterns
+
+WRONG: storing three memories, then creating the workstream.
+RIGHT: `create_workstream` first; every store carries the slug.
+
+WRONG: silently creating tasks from an ordinary implementation request.
+RIGHT: tasks only for what the user asked to track or said yes to; findings as
+memories; the rest in working state.
+
+WRONG: a three-PR plan kept only in working state because nobody said "track".
+RIGHT: "This is 3 units: … Track them as tasks?" — asked once, then their call.
+
+## Checklist
+
+- [ ] Topic and file-scoped search run; hits read in full before the code; UUIDs kept
+- [ ] Slug loaded or workstream created before any store
+- [ ] Two or more units → tasks offered once by name; created only on a yes, with the slug, linked to the design if one exists
+
+## See also
+
+`resume`, `recall`, `project`, `design`, `investigate`, `capture`, `finish`, `recallium-tools`.

package/skills/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/skills/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/bin/recallium

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import '../src/index.js';