thoth-agents 0.1.18 → 0.2.0

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:

package/thoth-agents.schema.json

@@ -466,6 +466,22 @@
           "type": "boolean"
         }
       }
+    },
+    "claudeCode": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "outputRoot": {
+          "type": "string"
+        },
+        "dryRun": {
+          "default": true,
+          "type": "boolean"
+        }
+      }
     }
   },
   "title": "thoth-agents",

package/dist/chunk-DYGVRAMS.js

@@ -1,182 +0,0 @@
-// src/utils/subprocess.ts
-import {
-  spawn as nodeSpawn,
-  spawnSync as nodeSpawnSync
-} from "child_process";
-import { Readable } from "stream";
-function emptyReadableStream() {
-  return new ReadableStream({
-    start(controller) {
-      controller.close();
-    }
-  });
-}
-function toWebReadable(stream) {
-  if (!stream) {
-    return emptyReadableStream();
-  }
-  return Readable.toWeb(
-    stream
-  );
-}
-function fallbackStdin() {
-  return {
-    write: () => void 0,
-    end: () => void 0
-  };
-}
-function spawn(command, options = {}) {
-  const child = nodeSpawn(command[0], command.slice(1), {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: [
-      options.stdin ?? "pipe",
-      options.stdout ?? "pipe",
-      options.stderr ?? "pipe"
-    ]
-  });
-  const managed = {
-    stdin: child.stdin ?? fallbackStdin(),
-    stdout: toWebReadable(child.stdout),
-    stderr: toWebReadable(child.stderr),
-    exited: new Promise((resolve) => {
-      child.on("exit", (code) => {
-        managed.exitCode = code;
-        resolve(code ?? 1);
-      });
-      child.on("error", () => {
-        managed.exitCode = 1;
-        resolve(1);
-      });
-    }),
-    exitCode: child.exitCode,
-    kill: () => {
-      child.kill();
-    }
-  };
-  return managed;
-}
-function spawnSync(command, options = {}) {
-  const result = nodeSpawnSync(command[0], command.slice(1), {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: [
-      options.stdin ?? "ignore",
-      options.stdout ?? "pipe",
-      options.stderr ?? "pipe"
-    ]
-  });
-  return { exitCode: result.status };
-}
-
-// src/cli/system.ts
-import { statSync } from "fs";
-var cachedOpenCodePath = null;
-function getOpenCodePaths() {
-  const home = process.env.HOME || process.env.USERPROFILE || "";
-  return [
-    // PATH (try this first)
-    "opencode",
-    // User local installations (Linux & macOS)
-    `${home}/.local/bin/opencode`,
-    `${home}/.opencode/bin/opencode`,
-    `${home}/bin/opencode`,
-    // System-wide installations
-    "/usr/local/bin/opencode",
-    "/opt/opencode/bin/opencode",
-    "/usr/bin/opencode",
-    "/bin/opencode",
-    // macOS specific
-    "/Applications/OpenCode.app/Contents/MacOS/opencode",
-    `${home}/Applications/OpenCode.app/Contents/MacOS/opencode`,
-    // Homebrew (macOS & Linux)
-    "/opt/homebrew/bin/opencode",
-    "/home/linuxbrew/.linuxbrew/bin/opencode",
-    `${home}/homebrew/bin/opencode`,
-    // macOS user Library
-    `${home}/Library/Application Support/opencode/bin/opencode`,
-    // Snap (Linux)
-    "/snap/bin/opencode",
-    "/var/snap/opencode/current/bin/opencode",
-    // Flatpak (Linux)
-    "/var/lib/flatpak/exports/bin/ai.opencode.OpenCode",
-    `${home}/.local/share/flatpak/exports/bin/ai.opencode.OpenCode`,
-    // Nix (Linux/macOS)
-    "/nix/store/opencode/bin/opencode",
-    `${home}/.nix-profile/bin/opencode`,
-    "/run/current-system/sw/bin/opencode",
-    // Cargo (Rust toolchain)
-    `${home}/.cargo/bin/opencode`,
-    // npm/npx global
-    `${home}/.npm-global/bin/opencode`,
-    "/usr/local/lib/node_modules/opencode/bin/opencode",
-    // Yarn global
-    `${home}/.yarn/bin/opencode`,
-    // PNPM
-    `${home}/.pnpm-global/bin/opencode`
-  ];
-}
-function resolveOpenCodePath() {
-  if (cachedOpenCodePath) {
-    return cachedOpenCodePath;
-  }
-  const paths = getOpenCodePaths();
-  for (const opencodePath of paths) {
-    if (opencodePath === "opencode") continue;
-    try {
-      const stat = statSync(opencodePath);
-      if (stat.isFile()) {
-        cachedOpenCodePath = opencodePath;
-        return opencodePath;
-      }
-    } catch {
-    }
-  }
-  return "opencode";
-}
-async function isOpenCodeInstalled() {
-  const paths = getOpenCodePaths();
-  for (const opencodePath of paths) {
-    try {
-      const proc = spawn([opencodePath, "--version"], {
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      await proc.exited;
-      if (proc.exitCode === 0) {
-        cachedOpenCodePath = opencodePath;
-        return true;
-      }
-    } catch {
-    }
-  }
-  return false;
-}
-async function getOpenCodeVersion() {
-  const opencodePath = resolveOpenCodePath();
-  try {
-    const proc = spawn([opencodePath, "--version"], {
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-    if (proc.exitCode === 0) {
-      return output.trim();
-    }
-  } catch {
-  }
-  return null;
-}
-function getOpenCodePath() {
-  const path = resolveOpenCodePath();
-  return path === "opencode" ? null : path;
-}
-
-export {
-  spawn,
-  spawnSync,
-  isOpenCodeInstalled,
-  getOpenCodeVersion,
-  getOpenCodePath
-};