thoth-agents 0.1.18 → 0.1.19

package/README.md

@@ -301,9 +301,20 @@ Artifacts can be persisted in four modes:
 Thoth-mem is the local memory MCP used for durable observations, architectural
 decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
 
-1. `mem_search` for compact candidate records
-2. `mem_timeline` for chronological context
-3. `mem_get_observation` for the full selected record
+1. `mem_recall(mode="compact")` for compact candidate records
+2. `mem_recall(mode="context")` for expanded retrieved context
+3. `mem_get(...)` for the full selected record; use
+   `mem_get(include_timeline=true)` when chronology matters
+
+Use HyDE/fused hybrid recall (sentence + chunk vectors, FTS, KG enrichment) for
+semantic or ambiguous searches; set `mem_recall` `limit` from 1 to 20; narrow
+with `topic_key`, `type`, `time_from`, `time_to`, `scope`, `project`, and
+`session_id` filters. Use `mem_get` with `kind="observation"|"prompt"`,
+`include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for
+large content. Use bounded `mem_context(recall_query=...)` or
+`mem_project(action="graph"|"topics"|"topic")` for supplemental project
+context; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`,
+`HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
 
 ## Skills And MCPs
 

package/dist/{chunk-6K3ZXIMC.js → chunk-2SGSRR6L.js}

@@ -1098,9 +1098,9 @@ Push back when context, risk, or assumptions are weak. Avoid verbosity.
 </epistemic-rigor>
 
 <session-bootstrap>
-- At the start of a new root session, when thoth-mem tools are available, load \`thoth-mem-agents\` and \`requirements-interview\`, call \`mem_session_start\` with the current project and session identity, then save the real user prompt with \`mem_save_prompt\`.
-- Save only the real user request with \`mem_save_prompt\`; never save generated sub-agent prompts, handoffs, summaries, or tool scaffolding as user intent.
-- If thoth-mem tools or required session/project identity are unavailable, disclose that memory bootstrap could not run and continue without pretending memory was saved.
+- At the start of a new root session, when thoth-mem tools and session/project identity are available, load \`thoth-mem-agents\` and \`requirements-interview\`, then call \`mem_session(action="start")\` as step 0 before any other thoth-mem call.
+- Save only the real user request with \`mem_save(kind="prompt")\`; never save generated sub-agent prompts, handoffs, summaries, or tool scaffolding as user intent.
+- If thoth-mem tools or required session/project identity are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.
 </session-bootstrap>
 
 <routing>
@@ -1136,9 +1136,9 @@ Before dispatching {{role.designer}}, {{role.quick}}, or {{role.deep}} after dis
 
 Internal handoff fields: Goal, Decision, Evidence, Scope, Steps, Verification, Uncertainty, relevant files or symbols, suggested skills when applicable, constraints, non-goals, escalation conditions, and next focus.
 
-When thoth-mem session-summary tooling and parent session/project identity are available, save or refresh that handoff body with root-owned \`mem_session_summary\` before dispatch. If the tooling or identity is unavailable, disclose that root-owned compaction could not be persisted and continue with explicit task instructions and local context; do not invent a fallback session or ask a sub-agent to create one.
+When thoth-mem summary persistence and parent session/project identity are available, save or refresh that handoff body with root-owned \`mem_session(action="summary")\` or \`mem_save(kind="session_summary")\` before dispatch. If tooling or identity is unavailable, disclose that root-owned compaction could not be persisted and continue with explicit task instructions and local context; do not invent a fallback session or ask a sub-agent to create one.
 
-The delegated prompt carries task instructions plus handoff recovery instructions only: parent \`session_id\`, project, persistence mode, memory permissions, bounded 3-layer recall steps, non-goals, escalation conditions, and redaction requirements. It must not include the handoff body, raw transcripts, file dumps, secrets, credentials, irrelevant context, or generated sub-agent prompts as memory source material.
+The delegated prompt carries task instructions plus handoff recovery instructions only: parent \`session_id\`, project, persistence mode, memory permissions, the recall funnel \`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`, optional bounded \`mem_context(recall_query=...)\`/\`mem_project(...)\` guidance when permitted, non-goals, escalation conditions, and redaction requirements. It must not include the handoff body, raw transcripts, file dumps, secrets, credentials, irrelevant context, or generated sub-agent prompts as memory source material.
 
 Never mention internal handoff preparation to the user, ask the user to prepare it, or present handoff preparation as the recommended next step. Describe the actual work instead.
 
@@ -1199,12 +1199,15 @@ Post-execution: delegate sdd-verify, then sdd-archive when verification passes.
 <progress-memory>
 - Keep {{progressTool}} top-level and lean for multi-step work.
 - When SDD is active, update both {{progressTool}} and openspec/changes/{change-name}/tasks.md before dispatch and after results.
-- Root-session memory is yours: search before repeated work; save durable decisions, discoveries, bugs, patterns, constraints, and session summaries.
-- Durable \`mem_save\`: save durable decisions, bug root causes, discoveries, conventions, config changes, and preferences. Use stable topic keys; keep general observations outside \`sdd/*\`.
-- Targeted 3-layer recall protocol: \`mem_search\` compact -> \`mem_timeline\` -> \`mem_get_observation\` only for records needed in full.
+- Root-session memory is yours: recall repeated work; save durable decisions, discoveries, bugs, patterns, constraints, summaries.
+- Use \`mem_save(kind="observation")\` for decisions, bugs, discoveries, conventions, preferences; stable topics; observations outside \`sdd/*\`.
+- Targeted recall funnel: \`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`; use \`mem_get(include_timeline=true)\` for time context.
+- Use HyDE/fused recall; set \`mem_recall\` \`limit\` from 1 to 20; narrow with \`topic_key\`, \`type\`, \`time_from\`/\`time_to\`, \`scope\`, \`project\`, \`session_id\`.
+- \`mem_get\`: \`kind="observation"|"prompt"\`, \`include_timeline=true\`, \`before\`/\`after\`, \`offset\`/\`max_length\`; supplement with bounded \`mem_context(recall_query=...)\` or \`mem_project(action="graph"|"topics"|"topic")\`.
+- Graph relations: HAS_TYPE, IN_PROJECT, HAS_TOPIC_KEY, HAS_WHAT, HAS_WHY, HAS_WHERE, HAS_LEARNED.
 - SDD memory artifacts use deterministic topic keys only in thoth-mem or hybrid persistence modes: \`sdd/{change}/{artifact}\`.
-- Before ending the root session, call \`mem_session_summary\` with a concise Goal, Instructions, Discoveries, Accomplished, Next Steps, and Relevant Files summary. Do not claim memory was saved unless the tool call succeeded.
-- After compaction, first preserve the compacted summary with \`mem_session_summary\`, then recover recent context and use the 3-layer recall protocol before continuing work.
+- Before ending the root session, call \`mem_session(action="summary")\` or root-owned \`mem_save(kind="session_summary")\` with a concise Goal, Instructions, Discoveries, Accomplished, Next Steps, and Relevant Files summary. Do not claim memory was saved unless the tool call succeeded.
+- After compaction, first preserve the compacted summary with \`mem_session(action="summary")\`, then call \`mem_context(recall_query=...)\` and use the recall funnel before continuing work.
 </progress-memory>
 
 <communication>
@@ -1376,32 +1379,30 @@ function renderSubagentRules(section, dialect) {
   ];
   if (section.memoryAccess === "readonly") {
     rules.push(
-      "- Use read-only thoth-mem only when dispatch gives parent session_id/project and handoff recovery instructions: `mem_search` -> `mem_timeline` -> `mem_get_observation`.",
-      "- The canonical recall path remains `mem_search` -> `mem_timeline` -> `mem_get_observation`; use bounded context tools only as supplemental context when explicitly allowed.",
-      "- If either parent session_id or project is missing, do NOT call thoth-mem; rely on explicit task instructions and local evidence.",
-      "- Recover the parent-session handoff summary through bounded 3-layer recall before treating memory as source material.",
+      "- Use read-only thoth-mem only when dispatch gives parent session_id/project and handoff recovery instructions.",
+      "- Parent-scoped reads: `mem_recall`, `mem_context`, `mem_get`, bounded `mem_project`; do not call `mem_save` or own any `mem_session(...)` lifecycle action.",
+      "- If either parent session_id or project is missing, do NOT call thoth-mem; rely on task instructions and local evidence.",
+      '- Recover the parent-session handoff summary through the recall funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)` before using memory.',
+      '- Use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true`, `before`/`after`, and `offset`/`max_length`.',
       "- Report when recalled context is missing, stale, contradictory, or insufficient.",
-      "- Use project-scoped read tools (`mem_context`, `mem_project_summary`, `mem_project_graph`, `mem_topic_keys`) only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
-      "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
-      "- Never save generated subagent prompts as user intent.",
-      "- Never write memory; memory writes are orchestrator-owned."
+      '- Supplemental `mem_context(recall_query=...)` and bounded `mem_project(action="graph"|"topics"|"topic")` do not replace the recall funnel and require explicit delegated permission. Graph relations: `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, `HAS_LEARNED`.',
+      "- Never save prompts, generated subagent prompts, session summaries, or durable memory."
     );
   }
   if (section.memoryAccess === "writable") {
     rules.push(
-      "- Use delegated thoth-mem tools only (mem_save, mem_search, mem_get_observation, mem_timeline, mem_context, mem_project_summary, mem_project_graph, mem_topic_keys, mem_suggest_topic_key).",
-      "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
+      "- Use delegated thoth-mem tools only: `mem_save`, `mem_recall`, `mem_context`, `mem_get`, `mem_project`, `mem_session`.",
       "- Always use the parent session_id/project from dispatch for every thoth-mem call.",
       "- If either is missing, do NOT call thoth-mem.",
       "- Follow handoff recovery instructions from the delegated task before using persisted memory.",
-      "- For reads, use only `mem_search` -> `mem_timeline` -> `mem_get_observation` and recover the parent-session handoff summary before treating memory as source material.",
-      "- Keep 3-layer recall canonical; use `mem_context`, `mem_project_summary`, `mem_project_graph`, and `mem_topic_keys` only as bounded supplemental context when the dispatch explicitly permits project-scoped reads.",
+      '- For reads, use the recall funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)` and recover the parent-session handoff summary before treating memory as source material.',
+      '- Use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true`, `before`/`after`, and `offset`/`max_length`.',
+      '- Keep the recall funnel canonical; use `mem_context(recall_query=...)` and bounded `mem_project(action="graph"|"topics"|"topic")` only with explicit project-read permission. Graph relations: `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, `HAS_LEARNED`.',
       "- Report when recalled context is missing, stale, contradictory, or insufficient.",
-      "- Use project-scoped read tools only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
-      "- `mem_save` is allowed only for delegated durable implementation observations or assigned SDD artifacts/apply-progress under the parent session/project.",
+      '- `mem_save(kind="observation")` is allowed only for delegated durable implementation observations or assigned deterministic SDD artifacts/apply-progress under the parent session/project.',
+      '- Never own `mem_session(action="start"|"checkpoint"|"summary")`, save prompts, or save generated subagent prompts as user intent.',
       "- Protect the `sdd/*` namespace: deterministic SDD artifacts use `sdd/{change}/{artifact}`; general durable observations must stay outside `sdd/*`.",
-      "- Never save generated subagent prompts as user intent.",
-      "- You do not own durable memory of your own; `mem_save` writes under the orchestrator's session/project only."
+      '- You do not own durable memory of your own; permitted `mem_save(kind="observation")` writes under the orchestrator\'s session/project only.'
     );
   }
   return rules.join("\n");

package/dist/{chunk-SOT5ZY53.js → chunk-7CTSLCEU.js}

@@ -31,7 +31,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-6K3ZXIMC.js";
+} from "./chunk-2SGSRR6L.js";
 
 // src/harness/adapters/codex.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
@@ -172,96 +172,91 @@ function getAgentPackContract() {
 }
 
 // src/harness/core/memory-governance.ts
-var ROOT_OWNED_TOOLS = [
-  "mem_session_start",
-  "mem_session_summary",
-  "mem_save_prompt"
+var ROOT_OWNED_OPERATIONS = [
+  { tool: "mem_session", action: "start" },
+  { tool: "mem_session", action: "checkpoint" },
+  { tool: "mem_session", action: "summary" },
+  { tool: "mem_save", kind: "prompt" },
+  { tool: "mem_save", kind: "session_summary" }
 ];
-var READ_RECALL_CHAIN = [
-  "mem_search",
-  "mem_timeline",
-  "mem_get_observation"
-];
-var BOUNDED_CONTEXT_TOOLS = [
+var PARENT_SCOPED_READ_TOOLS = [
+  "mem_recall",
   "mem_context",
-  "mem_project_summary",
-  "mem_project_graph",
-  "mem_topic_keys"
+  "mem_get",
+  "mem_project"
 ];
 var WRITE_CAPABLE_DELEGATED_TOOLS = [
-  "mem_save",
-  "mem_search",
-  "mem_get_observation",
-  "mem_timeline",
-  ...BOUNDED_CONTEXT_TOOLS,
-  "mem_suggest_topic_key"
+  ...PARENT_SCOPED_READ_TOOLS,
+  "mem_save"
 ];
 var ALL_MEMORY_TOOLS = [
-  ...ROOT_OWNED_TOOLS,
-  ...READ_RECALL_CHAIN,
-  ...BOUNDED_CONTEXT_TOOLS,
-  "mem_suggest_topic_key",
-  "mem_save"
+  "mem_save",
+  "mem_recall",
+  "mem_context",
+  "mem_get",
+  "mem_project",
+  "mem_session"
 ];
 function uniqueTools(tools) {
   return [...new Set(tools)];
 }
 function roleAllowedTools(role) {
   if (role.name === "orchestrator") {
-    return uniqueTools([...ROOT_OWNED_TOOLS, ...WRITE_CAPABLE_DELEGATED_TOOLS]);
+    return [...ALL_MEMORY_TOOLS];
   }
   if (role.mode === "read-only") {
-    return [...READ_RECALL_CHAIN, ...BOUNDED_CONTEXT_TOOLS];
+    return [...PARENT_SCOPED_READ_TOOLS];
   }
-  return [...WRITE_CAPABLE_DELEGATED_TOOLS];
+  return uniqueTools([...WRITE_CAPABLE_DELEGATED_TOOLS]);
 }
 function roleRules(role) {
   const sharedSubagentRules = [
     "Every subagent memory call requires the parent session_id and project from dispatch; if either is missing, do not call thoth-mem.",
-    "Delegated handoff recovery uses parent-scoped 3-layer recall with mem_search -> mem_timeline -> mem_get_observation before memory content is treated as source material.",
+    'Delegated handoff recovery uses the parent-scoped recall funnel: mem_recall(mode="compact") -> mem_recall(mode="context") -> mem_get(...) before memory content is treated as source material.',
+    "Use mem_get(include_timeline=true) when chronology around a recovered record matters.",
+    'mem_context(recall_query=...) and bounded mem_project(action="graph"|"topics"|"topic") are supplemental project context only and do not replace the recall funnel.',
     "Report missing, stale, contradictory, or insufficient recalled context instead of guessing through it.",
-    "Never call mem_session_start, mem_session_summary, or mem_save_prompt; those tools are root/orchestrator-owned.",
+    'Never own mem_session(action="start"|"checkpoint"|"summary") or mem_save(kind="prompt"|"session_summary"); those operations are root/orchestrator-owned.',
     "Never save generated subagent prompts as user intent.",
     "Protect the sdd/* topic namespace; SDD artifacts may use deterministic sdd/{change}/{artifact} topic keys only in persistence modes that include thoth-mem."
   ];
   if (role.name === "orchestrator") {
     return [
-      "mem_session_start, mem_session_summary, and mem_save_prompt are root/main orchestrator-owned tools and responsibilities.",
+      'mem_session(action="start"|"checkpoint"|"summary"), mem_save(kind="prompt"), and mem_save(kind="session_summary") are root/main orchestrator-owned operations and responsibilities.',
       "In harnesses without an orchestrator-named agent, root/main orchestrator-owned means the initial/root agent when the harness does not expose an orchestrator-named agent.",
-      "Before delegation, save or refresh the handoff body with root-owned mem_session_summary when available; otherwise disclose that compaction could not be persisted.",
+      'Before delegation, save or refresh the handoff body with root-owned mem_session(action="summary") or mem_save(kind="session_summary") when available; otherwise disclose that compaction could not be persisted.',
       "Dispatch task instructions plus recovery instructions, not the handoff body, raw transcripts, or generated subagent prompts.",
       "Dispatch parent session_id and project when authorizing subagent memory use.",
+      'Root recall uses mem_recall(mode="compact") -> mem_recall(mode="context") -> mem_get(...); use mem_context(recall_query=...) and bounded mem_project(action="graph"|"topics"|"topic") for supplemental context.',
       "Protect the sdd/* topic namespace and write SDD memory artifacts only in thoth-mem or hybrid persistence modes."
     ];
   }
   if (role.mode === "read-only") {
     return [
       ...sharedSubagentRules,
-      "Read-only agents may only perform bounded, project-scoped recall with mem_search -> mem_timeline -> mem_get_observation when authorized.",
-      "Bounded context tools mem_context, mem_project_summary, mem_project_graph, and mem_topic_keys are allowed only with explicit delegated permission and parent session/project scope.",
-      "Project-scoped read tools require explicit delegated permission.",
-      "Read-only agents must never write durable memory."
+      "Read-only agents may use only parent-scoped mem_recall, mem_context, mem_get, and bounded mem_project reads when authorized.",
+      "Project-scoped read tools require explicit delegated permission and must stay bounded to the parent session/project scope.",
+      "Read-only agents must never write durable memory or save prompts."
     ];
   }
   return [
     ...sharedSubagentRules,
-    "Write-capable agents may call mem_save only for delegated durable observations or assigned deterministic SDD artifacts/apply-progress under the parent session/project.",
-    "For reads, use only mem_search -> mem_timeline -> mem_get_observation.",
-    "Bounded context tools mem_context, mem_project_summary, mem_project_graph, and mem_topic_keys are allowed only with explicit delegated permission and parent session/project scope.",
-    "Project-scoped read tools require explicit delegated permission."
+    "Write-capable agents may use the same parent-scoped reads as read-only agents when authorized.",
+    'mem_save(kind="observation") is allowed only for delegated durable observations or assigned deterministic SDD artifacts/apply-progress under the parent session/project.',
+    "Project-scoped read tools require explicit delegated permission and must stay bounded to the parent session/project scope."
   ];
 }
 function getRoleMemoryGovernance(role) {
   const allowedTools = roleAllowedTools(role);
   return {
     role: role.name,
-    rootOwnedTools: [...ROOT_OWNED_TOOLS],
+    rootOwnedOperations: [...ROOT_OWNED_OPERATIONS],
     allowedTools,
     forbiddenTools: ALL_MEMORY_TOOLS.filter(
       (tool) => !allowedTools.includes(tool)
     ),
     requiresParentContext: role.name !== "orchestrator",
-    mayReadProjectMemory: role.name !== "orchestrator",
+    mayReadProjectMemory: true,
     mayWriteDurableObservations: role.mode === "write-capable",
     protectsSddNamespace: true,
     rules: roleRules(role)
@@ -277,7 +272,7 @@ function renderMemoryGovernanceInstructions(role, dialect) {
     "thoth-mem governance:",
     ...governance.rules.map((rule) => `- ${rule}`),
     ...harnessRules,
-    `- Runtime enforcement: ${role.name === "orchestrator" ? "root-owned" : "instruction-level unless the target harness validates per-agent memory controls"}.`
+    `- Runtime enforcement: ${role.name === "orchestrator" ? "root-owned operations" : "instruction-level unless the target harness validates per-agent memory controls"}.`
   ].join("\n");
 }
 function memoryGovernanceDiagnostics(input) {
@@ -286,7 +281,7 @@ function memoryGovernanceDiagnostics(input) {
     diagnostics.push({
       severity: "warning",
       code: `${input.harness}.permission.memory.enforcement_gap`,
-      message: "Runtime controls for root-only memory tools are unavailable; governance is rendered as instruction-level guidance.",
+      message: "Runtime controls for root-owned memory operations are unavailable; governance is rendered as instruction-level guidance.",
       harness: input.harness,
       capability: "rolePermissions",
       fallback: "instruction-only"
@@ -306,7 +301,7 @@ function memoryGovernanceDiagnostics(input) {
     diagnostics.push({
       severity: "warning",
       code: `${input.harness}.permission.memory_write.enforcement_gap`,
-      message: "Runtime controls for delegated memory writes are unavailable; write-capable agents receive instruction-level mem_save limits for durable observations and deterministic SDD artifacts only.",
+      message: 'Runtime controls for delegated memory writes are unavailable; write-capable agents receive instruction-level mem_save(kind="observation") limits for durable observations and deterministic SDD artifacts only.',
       harness: input.harness,
       capability: "memoryGovernanceEnforcement",
       fallback: "instruction-only"
@@ -1376,6 +1371,8 @@ function codexInternalHandoffGuidance() {
     "- The user has explicitly authorized this generated Codex orchestrator to use `multi_agent_v1.spawn_agent` whenever delegation is required by these instructions, without needing a fresh user request for subagents in each task.",
     "- Delegate by calling `multi_agent_v1.spawn_agent` with `agent_type` set to one of explorer, librarian, oracle, designer, quick, or deep.",
     "- Pass the self-contained delegated task instructions plus handoff retrieval instructions in `message`; do not embed the root-owned handoff summary body in `message`.",
+    '- When memory recovery is delegated, include parent `session_id`, project, permissions, and the recovery funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)`.',
+    '- For that funnel, use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true` plus `before`/`after`, and `offset`/`max_length`; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.',
     "- Do not include the handoff body in `message` or `items`, and do not pass both `message` and `items` for the same handoff.",
     "- Use `items` only for structured attachments or mentions when they are truly required; do not use `items` as a handoff-summary payload.",
     "- Leave `fork_context` omitted or false by default; set `fork_context: true` only when the exact current thread history is required.",
@@ -1420,9 +1417,9 @@ function renderCodexRootInstructions(config) {
     codexInternalHandoffGuidance(),
     "<codex-runtime>",
     "- The ambient Codex root session is the root/main orchestrator; orchestrator-only and root-owned instructions apply to it because Codex does not generate a selectable orchestrator agent TOML.",
-    "- On each new root session, when thoth-mem tools are installed and session/project identity is known, call mem_session_start with the active project and session identity, then save the real user prompt with mem_save_prompt before later delegation.",
+    '- On each new root session, when thoth-mem tools are installed and session/project identity is known, call mem_session(action="start") as step 0 before any other thoth-mem call, then save the real user prompt with mem_save(kind="prompt") before later delegation.',
     "- If thoth-mem tools or identity values are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
-    "- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session_summary when available; if unavailable, disclose that root-owned compaction could not be persisted.",
+    '- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session(action="summary") or mem_save(kind="session_summary") when available; if unavailable, disclose that root-owned compaction could not be persisted.',
     "- Use the ambient Codex root session as the delegate-first root coordinator; do not generate or select an orchestrator TOML.",
     "- Delegate by invoking `multi_agent_v1.spawn_agent` for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",
     "- After receiving a delegated subagent response, close that subagent session unless you will retry or intentionally keep using that exact same session; explorer and librarian sessions must always be closed immediately after their response, and retry sessions must be closed after the retry result unless explicit same-session reuse is still required.",

package/dist/cli/index.js

@@ -25,7 +25,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-SOT5ZY53.js";
+} from "../chunk-7CTSLCEU.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -37,7 +37,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-6K3ZXIMC.js";
+} from "../chunk-2SGSRR6L.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/tui/index.js

@@ -15,13 +15,13 @@ import {
   getOpenCodeStatus,
   listOperationHarnesses,
   parseRoleTomlModel
-} from "../../chunk-SOT5ZY53.js";
+} from "../../chunk-7CTSLCEU.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-6K3ZXIMC.js";
+} from "../../chunk-2SGSRR6L.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

package/dist/harness/core/memory-governance.d.ts

@@ -1,11 +1,41 @@
 import type { HarnessPromptDialect } from '../../agents/prompt-dialects';
 import type { HarnessCapabilityStatus, HarnessDiagnostic } from '../types';
 import type { AgentRoleContract, AgentRoleName } from './agent-pack';
-export type MemoryToolName = 'mem_session_start' | 'mem_session_summary' | 'mem_save_prompt' | 'mem_search' | 'mem_timeline' | 'mem_get_observation' | 'mem_context' | 'mem_project_summary' | 'mem_project_graph' | 'mem_topic_keys' | 'mem_suggest_topic_key' | 'mem_save';
+export type MemoryToolName = 'mem_save' | 'mem_recall' | 'mem_context' | 'mem_get' | 'mem_project' | 'mem_session';
+export type MemSaveKind = 'observation' | 'prompt' | 'session_summary' | 'passive_learnings';
+export type MemSessionAction = 'start' | 'checkpoint' | 'summary';
+export type MemRecallMode = 'compact' | 'context';
+export type MemProjectAction = 'list' | 'summary' | 'graph' | 'topics' | 'topic';
+export type MemoryOperation = {
+    tool: 'mem_session';
+    action: MemSessionAction;
+} | {
+    tool: 'mem_save';
+    kind: MemSaveKind;
+} | {
+    tool: 'mem_recall';
+    mode: MemRecallMode;
+} | {
+    tool: 'mem_get';
+    includeTimeline?: boolean;
+} | {
+    tool: 'mem_context';
+    recallQuery?: boolean;
+} | {
+    tool: 'mem_project';
+    action: MemProjectAction;
+};
+export type RootOwnedMemoryOperation = {
+    tool: 'mem_session';
+    action: MemSessionAction;
+} | {
+    tool: 'mem_save';
+    kind: 'prompt' | 'session_summary';
+};
 export type MemoryRuntimeEnforcement = 'runtime' | 'instruction-only';
 export interface RoleMemoryGovernance {
     role: AgentRoleName;
-    rootOwnedTools: MemoryToolName[];
+    rootOwnedOperations: RootOwnedMemoryOperation[];
     allowedTools: MemoryToolName[];
     forbiddenTools: MemoryToolName[];
     requiresParentContext: boolean;
@@ -15,8 +45,8 @@ export interface RoleMemoryGovernance {
     rules: string[];
 }
 export interface MemoryGovernanceContract {
-    rootOwnedTools: MemoryToolName[];
-    readRecallChain: MemoryToolName[];
+    rootOwnedOperations: RootOwnedMemoryOperation[];
+    readRecallChain: MemoryOperation[];
     writeCapableDelegatedTools: MemoryToolName[];
     protectedTopicNamespaces: string[];
     roles: RoleMemoryGovernance[];
@@ -27,6 +57,11 @@ export interface MemoryGovernanceDiagnosticInput {
     parentContextInjection: HarnessCapabilityStatus;
     memoryWriteControls: HarnessCapabilityStatus;
 }
+export declare const ROOT_OWNED_OPERATIONS: RootOwnedMemoryOperation[];
+export declare const READ_RECALL_CHAIN: MemoryOperation[];
+export declare const PARENT_SCOPED_READ_TOOLS: MemoryToolName[];
+export declare const WRITE_CAPABLE_DELEGATED_TOOLS: MemoryToolName[];
+export declare const ALL_MEMORY_TOOLS: MemoryToolName[];
 export declare function getRoleMemoryGovernance(role: AgentRoleContract): RoleMemoryGovernance;
 export declare function getMemoryGovernanceContract(roles: readonly AgentRoleContract[]): MemoryGovernanceContract;
 export declare function renderMemoryGovernanceInstructions(role: AgentRoleContract, dialect?: HarnessPromptDialect): string;

package/dist/hooks/phase-reminder/index.d.ts

@@ -1,4 +1,6 @@
 export declare const PHASE_REMINDER = "<reminder>Recall Workflow Rules:\nUnderstand \u2192 split discovery into surgical probes with explorer/librarian \u2192 synthesize the decision and internal handoff \u2192 execute \u2192 verify.\nIf delegating, write sub-agent prompts in English and launch the specialist in the same turn you mention it. If multiple delegations are independent, emit all tool calls in a single response.\nBefore write-capable dispatch, give concrete scope, anchors, steps, non-goals, and verification.\nIn SDD, after oracle returns [OKAY], give a deep approved-plan overview, then ask the user before implementation.</reminder>";
+export declare const PHASE_REMINDER_SEPARATOR = "\n\n---\n\n";
+export declare function stripPhaseReminder(text: string): string;
 interface MessageInfo {
     role: string;
     agent?: string;

package/dist/hooks/thoth-mem/protocol.d.ts

@@ -1,6 +1,6 @@
 export declare const SDD_TOPIC_KEY_FORMAT = "sdd/{change}/{artifact}";
-export declare const FIRST_ACTION_INSTRUCTION = "FIRST ACTION REQUIRED: Call mem_session_summary with the content of the compacted summary. This preserves what was accomplished before compaction. Do this BEFORE any other work. Then call mem_context for a recent-session overview, and use the 3-layer recall protocol (mem_search with mode \"compact\" -> mem_timeline -> mem_get_observation) for precise retrieval.";
-export declare const SESSION_SUMMARY_TEMPLATE = "Use this exact structure for `mem_session_summary` content:\n\n## Goal\n[What we were working on this session]\n\n## Instructions\n[User preferences or constraints discovered during this session]\n\n## Discoveries\n- [Technical findings, gotchas, non-obvious learnings]\n\n## Accomplished\n- [Completed items with key details]\n\n## Next Steps\n- [What remains to be done]\n\n## Relevant Files\n- path/to/file.ts - [what it does or what changed]";
+export declare const FIRST_ACTION_INSTRUCTION = "FIRST ACTION REQUIRED: Call mem_session(action=\"summary\") with the content of the compacted summary. This preserves what was accomplished before compaction. Do this BEFORE any other work. Then call mem_context(recall_query=...) for fused recent context, and use the recall funnel (mem_recall(mode=\"compact\") -> mem_recall(mode=\"context\") -> mem_get(...)) for precise retrieval.";
+export declare const SESSION_SUMMARY_TEMPLATE = "Use this exact structure for `mem_session(action=\"summary\")` content:\n\n## Goal\n[What we were working on this session]\n\n## Instructions\n[User preferences or constraints discovered during this session]\n\n## Discoveries\n- [Technical findings, gotchas, non-obvious learnings]\n\n## Accomplished\n- [Completed items with key details]\n\n## Next Steps\n- [What remains to be done]\n\n## Relevant Files\n- path/to/file.ts - [what it does or what changed]";
 export declare function buildCompactionReminder(sessionID: string): string;
 export declare function buildCompactorInstruction(project: string): string;
 export declare function buildMemoryInstructions(sessionID: string, project: string): string;

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   loadPluginConfig,
   renderRolePrompt,
   stripJsonComments
-} from "./chunk-6K3ZXIMC.js";
+} from "./chunk-2SGSRR6L.js";
 
 // src/index.ts
 import path4 from "path";
@@ -164,9 +164,13 @@ function createOracleAgent(model, customPrompt, customAppendPrompt) {
 }
 
 // src/agents/orchestrator.ts
-var ORCHESTRATOR_PROMPT = renderRolePrompt(
-  createOrchestratorPromptSections(),
-  OPENCODE_PROMPT_DIALECT
+var OPENCODE_RUNTIME_SECTION = `<opencode-runtime>
+In the OpenCode harness, an automatic \`<reminder>...</reminder>\` workflow block followed by a \`\\n\\n---\\n\\n\` separator is prepended to your user messages as harness scaffolding, not user input.
+When saving the user prompt via mem_save(kind="prompt"), you MUST exclude that injected \`<reminder>\` block and the \`---\` separator, and persist only the real user request text that follows.
+</opencode-runtime>`;
+var ORCHESTRATOR_PROMPT = appendPromptSections(
+  renderRolePrompt(createOrchestratorPromptSections(), OPENCODE_PROMPT_DIALECT),
+  OPENCODE_RUNTIME_SECTION
 );
 function createOrchestratorAgent(model, customPrompt, customAppendPrompt) {
   const prompt = composeAgentPrompt({
@@ -1744,6 +1748,14 @@ Understand \u2192 split discovery into surgical probes with explorer/librarian \
 If delegating, write sub-agent prompts in English and launch the specialist in the same turn you mention it. If multiple delegations are independent, emit all tool calls in a single response.
 Before write-capable dispatch, give concrete scope, anchors, steps, non-goals, and verification.
 In SDD, after oracle returns [OKAY], give a deep approved-plan overview, then ask the user before implementation.</reminder>`;
+var PHASE_REMINDER_SEPARATOR = "\n\n---\n\n";
+function stripPhaseReminder(text) {
+  if (!text) {
+    return "";
+  }
+  const prefix = `${PHASE_REMINDER}${PHASE_REMINDER_SEPARATOR}`;
+  return text.startsWith(prefix) ? text.slice(prefix.length) : text;
+}
 function createPhaseReminderHook() {
   return {
     "experimental.chat.messages.transform": async (_input, output) => {
@@ -1776,11 +1788,7 @@ function createPhaseReminderHook() {
       if (originalText.includes(LITE_INTERNAL_INITIATOR_MARKER)) {
         return;
       }
-      lastUserMessage.parts[textPartIndex].text = `${PHASE_REMINDER}
-
----
-
-${originalText}`;
+      lastUserMessage.parts[textPartIndex].text = `${PHASE_REMINDER}${PHASE_REMINDER_SEPARATOR}${originalText}`;
     }
   };
 }
@@ -2013,8 +2021,8 @@ function createThothClient(options) {
 
 // src/hooks/thoth-mem/protocol.ts
 var SDD_TOPIC_KEY_FORMAT = "sdd/{change}/{artifact}";
-var FIRST_ACTION_INSTRUCTION = 'FIRST ACTION REQUIRED: Call mem_session_summary with the content of the compacted summary. This preserves what was accomplished before compaction. Do this BEFORE any other work. Then call mem_context for a recent-session overview, and use the 3-layer recall protocol (mem_search with mode "compact" -> mem_timeline -> mem_get_observation) for precise retrieval.';
-var SESSION_SUMMARY_TEMPLATE = `Use this exact structure for \`mem_session_summary\` content:
+var FIRST_ACTION_INSTRUCTION = 'FIRST ACTION REQUIRED: Call mem_session(action="summary") with the content of the compacted summary. This preserves what was accomplished before compaction. Do this BEFORE any other work. Then call mem_context(recall_query=...) for fused recent context, and use the recall funnel (mem_recall(mode="compact") -> mem_recall(mode="context") -> mem_get(...)) for precise retrieval.';
+var SESSION_SUMMARY_TEMPLATE = `Use this exact structure for \`mem_session(action="summary")\` content:
 
 ## Goal
 [What we were working on this session]
@@ -2034,10 +2042,10 @@ var SESSION_SUMMARY_TEMPLATE = `Use this exact structure for \`mem_session_summa
 ## Relevant Files
 - path/to/file.ts - [what it does or what changed]`;
 function buildCompactionReminder(sessionID) {
-  return `FIRST ACTION REQUIRED: this session was compacted. Call \`mem_session_summary\` with the content of the compacted summary and \`session_id\` \`${sessionID}\`. This preserves what was accomplished before compaction. Do this BEFORE any other work. After that, call \`mem_capture_passive\` if the summary includes \`## Key Learnings:\`, call \`mem_context\` for a recent-session overview, and use the 3-layer recall protocol (\`mem_search\` with \`mode: "compact"\` -> \`mem_timeline\` -> \`mem_get_observation\`) for precise retrieval.`;
+  return `FIRST ACTION REQUIRED: this session was compacted. Call \`mem_session(action="summary")\` with the content of the compacted summary and \`session_id\` \`${sessionID}\`. This preserves what was accomplished before compaction. Do this BEFORE any other work. After that, call \`mem_context(recall_query=...)\` for fused recent context, and use the recall funnel (\`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`) for precise retrieval.`;
 }
 function buildCompactorInstruction(project) {
-  return `CRITICAL INSTRUCTION: place this at the TOP of the compacted summary exactly as an action item for the resumed agent: "FIRST ACTION REQUIRED: Call mem_session_summary with the content of this compacted summary. Use project: '${project}'. This preserves what was accomplished before compaction. Do this BEFORE any other work."`;
+  return `CRITICAL INSTRUCTION: place this at the TOP of the compacted summary exactly as an action item for the resumed agent: "FIRST ACTION REQUIRED: Call mem_session(action="summary") with the content of this compacted summary. Use project: '${project}'. This preserves what was accomplished before compaction. Do this BEFORE any other work."`;
 }
 function buildMemoryInstructions(sessionID, project) {
   return `
@@ -2045,18 +2053,20 @@ function buildMemoryInstructions(sessionID, project) {
 Persistent memory is available through thoth-mem. Follow this protocol.
 
 IMPORTANT: Your current session_id is \`${sessionID}\` and project is \`${project}\`.
-Always pass these values when calling memory tools that accept them (mem_session_summary, mem_save, mem_capture_passive, etc.).
+Always pass these values when calling memory tools that accept them.
 
 ### CORE TOOLS
-mem_save, mem_search, mem_context, mem_session_summary, mem_get_observation, mem_save_prompt, mem_update, mem_suggest_topic_key, mem_timeline, mem_capture_passive
+mem_save, mem_recall, mem_context, mem_get, mem_project, mem_session
 
-### SUBAGENT HANDOFF
-- When dispatching subagents for thoth-mem work, load the bundled \`thoth-mem-agents\` skill.
-- Orchestrator owns \`mem_session_start\`, \`mem_session_summary\`, and \`mem_save_prompt\`.
-- Do not ask subagents to save prompts or session summaries; pass parent \`session_id\` and \`project\` instead.
+### OWNERSHIP AND SUBAGENT HANDOFF
+- Root owns \`mem_session(action="start"|"checkpoint"|"summary")\` and \`mem_save(kind="prompt"|"session_summary")\`.
+- Start root memory-backed workflows with \`mem_session(action="start")\` before any other thoth-mem operation when tools and identity are available.
+- Save the real user prompt with \`mem_save(kind="prompt")\`; never save generated subagent prompts as user intent.
+- Before memory-dependent delegation, save the handoff body with \`mem_session(action="summary")\` or \`mem_save(kind="session_summary")\`.
+- Subagent handoff prompts carry parent \`session_id\`, \`project\`, permissions, and recovery instructions only; do not ask subagents to own session lifecycle actions or save prompts.
 
 ### WHEN TO SAVE
-Call \`mem_save\` IMMEDIATELY after ANY of these:
+Call \`mem_save(kind="observation")\` IMMEDIATELY after ANY of these:
 - Architecture, design, or workflow decision made
 - Bug fixed (include root cause)
 - Non-obvious discovery, gotcha, or edge case found
@@ -2069,44 +2079,45 @@ Call \`mem_save\` IMMEDIATELY after ANY of these:
 - Discussion concludes with a clear direction chosen
 
 Use \`title\` as Verb + what changed or was learned.
+Use \`kind\` intentionally: \`observation\`, \`prompt\`, \`session_summary\`, or \`passive_learnings\`.
 Use \`type\` from: bugfix | decision | architecture | discovery | pattern | config | learning | manual.
 Set \`scope\` intentionally.
-Reuse \`topic_key\` for the same evolving topic. Do not overwrite unrelated topics.
-If unsure about a stable \`topic_key\`, call \`mem_suggest_topic_key\` first.
-If you need to modify a known observation by exact ID, call \`mem_update\` instead of creating a new record.
-Put the durable details in \`content\` with this structure:
+Reuse a stable \`topic_key\` for the same evolving topic. Do not overwrite unrelated topics.
+Put durable observation details in \`content\` with this structure:
   - What: concise description of what changed or was learned
   - Why: why it mattered or what problem it solved
   - Where: files, paths, or systems involved
   - Learned: edge cases, caveats, or follow-up notes
 
-**Self-check after EVERY task**: "Did I or the user just make a decision, confirm a recommendation, express a preference, fix a bug, learn something, or establish a convention? If yes \u2192 mem_save NOW."
-
-You can also call \`mem_save_prompt\` to manually save a user prompt that you consider particularly important for future context.
+**Self-check after EVERY task**: "Did I or the user just make a decision, confirm a recommendation, express a preference, fix a bug, learn something, or establish a convention? If yes \u2192 mem_save(kind="observation") NOW."
 
-### WHEN TO SEARCH MEMORY
-- Broad recovery (session start, after compaction): call \`mem_context\` for a recent-session overview.
-- Targeted 3-layer recall (specific memory retrieval):
-  1. Call \`mem_search\` with \`mode: "compact"\` (default) to scan the compact index of IDs + titles.
-  2. Call \`mem_timeline\` around promising observation IDs for chronological context within the same session.
-  3. Call \`mem_get_observation\` only for observations you need in full.
-- Use \`mode: "preview"\` with \`mem_search\` only when compact results are insufficient to disambiguate.
+### RECALL FUNNEL
+- Broad recovery (session start, after compaction): call \`mem_context(recall_query=...)\` for fused recent context when useful.
+- Targeted retrieval:
+  1. Call \`mem_recall(mode="compact")\` to scan candidate IDs and titles.
+  2. Call \`mem_recall(mode="context")\` to expand the strongest hits into retrieved context.
+  3. Call \`mem_get(...)\` only for records you need in full.
+- Use HyDE/fused recall for semantic or ambiguous searches.
+- Set \`mem_recall\` \`limit\` from 1 to 20 for candidate/result count.
+- Narrow with \`topic_key\`, \`type\`, \`time_from\`, \`time_to\`, \`scope\`, \`project\`, and \`session_id\` filters.
+- Use \`mem_get\` with \`kind="observation"|"prompt"\`; use \`mem_get(include_timeline=true)\` with \`before\`/\`after\`, and \`offset\`/\`max_length\` for large content.
+- Use bounded \`mem_project(action="graph"|"topics"|"topic")\` for relationship and topic navigation; \`mem_project(action="graph")\` relations are \`HAS_TYPE\`, \`IN_PROJECT\`, \`HAS_TOPIC_KEY\`, \`HAS_WHAT\`, \`HAS_WHY\`, \`HAS_WHERE\`, and \`HAS_LEARNED\`; these calls supplement, not replace, the recall funnel.
 - Search proactively on the first message about a project, feature, or problem when prior context may matter.
 - Search before starting work that may have been done before.
 - Search when the user mentions a topic that lacks enough local context.
 
 ### SESSION CLOSE PROTOCOL
-- Before ending the session, call \`mem_session_summary\` with this exact template.
+- Before ending the session, call \`mem_session(action="summary")\` with this exact template.
 - This is NOT optional. If you skip this, the next session starts blind.
 - Do not claim memory was saved unless the tool call succeeded.
-- If your response includes \`## Key Learnings:\`, also call \`mem_capture_passive\`.
+- If your response includes \`## Key Learnings:\`, preserve them with \`mem_save(kind="passive_learnings")\`.
 
 ${SESSION_SUMMARY_TEMPLATE}
 
 ### AFTER COMPACTION
-- IMMEDIATELY call \`mem_session_summary\` with the compacted summary content.
-- Then call \`mem_context\` for a recent-session overview.
-- Use the 3-layer recall protocol (\`mem_search\` with \`mode: "compact"\` -> \`mem_timeline\` -> \`mem_get_observation\`) for precise artifact/prior-observation retrieval.
+- IMMEDIATELY call \`mem_session(action="summary")\` with the compacted summary content.
+- Then call \`mem_context(recall_query=...)\` for fused recent context.
+- Use the recall funnel (\`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`) for precise artifact/prior-observation retrieval.
 - Only then continue working.
 
 ### SDD TOPIC KEY CONVENTION
@@ -2155,11 +2166,15 @@ function truncate(str, max) {
   return str.length > max ? `${str.slice(0, max)}...` : str;
 }
 function sanitizePromptText(text) {
-  return truncate(stripPrivateTags(text), 2e3);
+  return truncate(stripPrivateTags(stripPhaseReminder(text)), 2e3);
 }
-function isSessionSummaryTool(toolName) {
+function isSessionSummaryTool(toolName, args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    return false;
+  }
   const normalized = toolName.toLowerCase();
-  return normalized === "mem_session_summary" || normalized.endsWith(".mem_session_summary") || normalized.endsWith("_mem_session_summary");
+  const isMemSessionTool = normalized === "mem_session" || normalized.endsWith(".mem_session") || normalized.endsWith("_mem_session");
+  return isMemSessionTool && args.action === "summary";
 }
 function isMemSaveTool(toolName) {
   const normalized = toolName.toLowerCase();
@@ -2331,7 +2346,6 @@ function createThothMemHook(options) {
     },
     "tool.execute.after": async (input, output) => {
       void input.callID;
-      void input.args;
       void output.title;
       void output.output;
       void output.metadata;
@@ -2342,7 +2356,7 @@ function createThothMemHook(options) {
         lastMemSaveAt.set(input.sessionID, Date.now());
         nudgePending.delete(input.sessionID);
       }
-      if (isSessionSummaryTool(input.tool)) {
+      if (isSessionSummaryTool(input.tool, input.args)) {
         needsCompactionFollowUp.delete(input.sessionID);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/skills/_shared/persistence-contract.md

@@ -83,26 +83,29 @@ Subagents must not create fallback sessions.
 
 ## Retrieval Protocol
 
-### 3-Layer Recall for thoth-mem and hybrid modes
+### Recall funnel for thoth-mem and hybrid modes
 
-Always complete the full three layers before using memory content as source
+Always complete the recall funnel before using memory content as source
 material:
 
-1. **Layer 1 (Compact):** `mem_recall(mode="compact")` to scan IDs/titles with
-   exact topic-key or focused query terms.
-2. **Layer 2 (Context):** `mem_recall(mode="context")` to expand the strongest
-   hits into retrieved text.
-3. **Layer 3 (Full):** `mem_get(id=...)` to fetch full content. Use
-   `include_timeline=true` when chronology matters.
+1. `mem_recall(mode="compact")` — scan candidate IDs/titles with exact topic-key
+   or focused query terms.
+2. `mem_recall(mode="context")` — expand the strongest hits into retrieved text.
+3. `mem_get(id=...)` — fetch full content; use
+   `mem_get(include_timeline=true)` when chronology matters.
 
-Optional fused context: `mem_context(..., recall_query="...")` when one recent
-context view is useful; it does not replace the three-layer recall.
+Use HyDE/fused hybrid recall (sentence + chunk vectors, FTS, KG enrichment) for
+semantic or ambiguous searches; narrow with `topic_key`, `type`, `time_from`,
+`time_to`, `scope`, `project`, and `session_id` filters; use
+`mem_context(recall_query=...)` or bounded
+`mem_project(action="graph"|"topics"|"topic")` for supplemental project
+context. Supplemental context does not replace the recall funnel.
 
 ### Mode-specific retrieval
 
-1. If mode is `thoth-mem`, use three-layer recall with exact SDD topic key.
+1. If mode is `thoth-mem`, use the recall funnel with exact SDD topic key.
 2. If mode is `openspec`, read canonical OpenSpec files only.
-3. If mode is `hybrid`, use three-layer recall first.
+3. If mode is `hybrid`, use the recall funnel first.
 4. In `hybrid`, if nothing is found in thoth-mem, read canonical OpenSpec
    files as fallback.
 5. In `hybrid`, if filesystem fallback succeeds, re-save the artifact to
@@ -148,8 +151,9 @@ original intent, accepted scope, deferred areas, and justified exclusions.
 ## Recovery Notes
 
 - Prefer exact topic-key queries over broad natural-language recall.
-- Always apply the three-layer recall (`mem_recall compact` ->
-  `mem_recall context` -> `mem_get`) before treating memory as source material.
+- Always apply the recall funnel (`mem_recall(mode="compact")` ->
+  `mem_recall(mode="context")` -> `mem_get(...)`) before treating memory as
+  source material.
 - In `openspec`, repair missing/stale artifacts by rewriting canonical OpenSpec
   files.
 - In `thoth-mem`, repair missing/stale artifacts by re-saving full artifacts via

package/src/skills/_shared/thoth-mem-convention.md

@@ -81,30 +81,30 @@ Persist with `mem_save` using canonical SDD topic keys and required metadata:
 Recovery path for state artifacts:
 `mem_recall(mode="compact", query="topic_key:sdd/{change-name}/state")` ->
 `mem_recall(mode="context", query="topic_key:sdd/{change-name}/state")` when needed ->
-`mem_get(id=...)` (or `include_timeline=true` when chronology matters) ->
+`mem_get(id=...)` (or `mem_get(include_timeline=true)` when chronology matters) ->
 parse YAML -> restore phase state.
 
-## Three-Layer Recall Protocol
+## Recall Funnel Protocol
 
 For delegated handoffs, subagents may use recall only when dispatch includes
 both parent `session_id` and `project`.
 
-1. **Compact scan**
-
-`mem_recall(mode="compact")` with exact topic-key query for token-efficient IDs
-and ranking.
-
-2. **Context expansion**
-
-`mem_recall(mode="context")` to expand strongest hits into retrieved text.
-
-3. **Full body fetch**
-
-`mem_get(id=...)` to retrieve full artifact content. Use
-`include_timeline=true` when chronology matters.
-
-Optional: `mem_context(..., recall_query="...")` can provide fused recent
-context, but it does not replace the three-layer recall.
+1. `mem_recall(mode="compact")` with exact topic-key query for token-efficient
+   IDs and ranking.
+2. `mem_recall(mode="context")` to expand strongest hits into retrieved text.
+3. `mem_get(id=...)` to retrieve full artifact content; use
+   `mem_get(include_timeline=true)` when chronology matters.
+
+Use HyDE/fused hybrid recall (sentence + chunk vectors, FTS, KG enrichment) for
+semantic or ambiguous searches; set `mem_recall` `limit` from 1 to 20; narrow
+with `topic_key`, `type`, `time_from`, `time_to`, `scope`, `project`, and
+`session_id` filters. Use `mem_get` with `kind="observation"|"prompt"`,
+`include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for
+large content. Use `mem_context(recall_query=...)` or bounded
+`mem_project(action="graph"|"topics"|"topic")` for supplemental project
+context; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`,
+`HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
+Supplemental context does not replace the recall funnel.
 
 ## Save Contract
 

package/src/skills/executing-plans/SKILL.md

@@ -71,9 +71,10 @@ The orchestrator owns task progress tracking.
 2. Load task artifacts using mode-aware retrieval:
    - `openspec`/`hybrid`: scan `openspec/changes/` for active changes and read
      `tasks.md`.
-   - `thoth-mem`: recover tasks via 3-layer recall
+   - `thoth-mem`: recover tasks via the recall funnel
      (`mem_recall(mode="compact")` -> `mem_recall(mode="context")` ->
-     `mem_get(id=...)`) using topic key `sdd/{change-name}/tasks`.
+     `mem_get(...)`) using topic key `sdd/{change-name}/tasks`; use
+     `mem_get(include_timeline=true)` when task chronology matters.
 3. Find the first unchecked task in state `- [ ]` or `- [~]`.
 4. Build a mental model of the plan: total tasks, remaining work,
    parallelizable work, and dependency order.
@@ -233,9 +234,10 @@ To resume safely:
 2. Recover task state using mode-aware retrieval:
    - `openspec`: read `openspec/changes/{change-name}/tasks.md`.
    - `thoth-mem`: recover `sdd/{change-name}/tasks` and
-     `sdd/{change-name}/apply-progress` via 3-layer recall
+     `sdd/{change-name}/apply-progress` via the recall funnel
      (`mem_recall(mode="compact")` -> `mem_recall(mode="context")` ->
-     `mem_get(id=...)`).
+     `mem_get(...)`); use `mem_get(include_timeline=true)` when task chronology
+     matters.
    - `hybrid`: do both recovery paths and prefer thoth-mem as the source of
      truth if state diverges.
 3. Resume from the first task marked `- [ ]` or `- [~]`.

package/src/skills/plan-reviewer/SKILL.md

@@ -21,8 +21,10 @@ to hand to implementation.
 
 Review the tasks artifact for true execution blockers. Retrieve it according to
 the persistence mode: read `openspec/changes/{change-name}/tasks.md` for
-openspec/hybrid modes, use thoth-mem 3-layer recall for thoth-mem/hybrid modes,
-or read from inline context for none mode.
+openspec/hybrid modes, use the thoth-mem recall funnel
+(`mem_recall(mode="compact")` -> `mem_recall(mode="context")` ->
+`mem_get(...)`) for thoth-mem/hybrid modes, or read from inline context for none
+mode.
 
 The artifact governance validator is not part of this review. Plan-reviewer is
 only the pre-execution approval gate for the task plan; it does not run the

package/src/skills/thoth-mem-agents/SKILL.md

@@ -88,6 +88,7 @@ Learned: caveats or edge cases
 3. `mem_get(id=...)`
 
 Use `mem_get(id=..., include_timeline=true)` when chronology matters.
+Set `mem_recall` `limit` from 1 to 20. Use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for large content.
 Use `mem_context(..., recall_query="...")` only as optional fused context, not
 as a replacement for the recall funnel.
 
@@ -101,6 +102,8 @@ Use `mem_project` for project-level navigation:
 - `action="topics"`
 - `action="topic"`
 
+`mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
+
 ### Session close and compaction
 
 Before ending meaningful work, root records continuity with either: