@zosmaai/pi-llm-wiki 0.9.0 → 0.9.2

package/extensions/llm-wiki/lib/utils.ts

@@ -20,6 +20,7 @@ export interface VaultPaths {
   root: string;
   raw: string;
   rawSources: string;
+  rawTrajectories: string;
   wiki: string;
   meta: string;
   dotWiki: string;
@@ -157,6 +158,7 @@ export function getVaultPaths(root: string): VaultPaths {
     root,
     raw: join(root, ".llm-wiki", "raw"),
     rawSources: join(root, ".llm-wiki", "raw", "sources"),
+    rawTrajectories: join(root, ".llm-wiki", "raw", "trajectories"),
     wiki: join(root, ".llm-wiki", "wiki"),
     meta: join(root, ".llm-wiki", "meta"),
     dotWiki: join(root, ".llm-wiki"),
@@ -171,6 +173,7 @@ export function getLegacyVaultPaths(root: string): VaultPaths {
     root,
     raw: join(root, "raw"),
     rawSources: join(root, "raw", "sources"),
+    rawTrajectories: join(root, "raw", "trajectories"),
     wiki: join(root, "wiki"),
     meta: join(root, "meta"),
     dotWiki: join(root, ".wiki"),
@@ -192,6 +195,10 @@ export function resolveVaultPaths(cwd: string): VaultPaths {
 
 /** Ensure all vault directories exist. */
 export function ensureVaultStructure(paths: VaultPaths): void {
+  // NOTE: the agent-trajectory dirs (raw/trajectories, wiki/skills, wiki/cases)
+  // are intentionally NOT created here — they are created lazily on first
+  // capture/distill (issue #80), so a vault with the feature off carries no
+  // trace of it. All readers of these paths are existsSync-guarded.
   const dirs = [
     paths.rawSources,
     join(paths.raw, "assets"),
@@ -238,12 +245,22 @@ export function readText(path: string): string {
 
 /** Generate the next source ID. */
 export function nextSourceId(paths: VaultPaths): string {
+  return nextSequentialId(paths.rawSources, "SRC");
+}
+
+/** Generate the next trajectory ID. */
+export function nextTrajectoryId(paths: VaultPaths): string {
+  return nextSequentialId(paths.rawTrajectories, "TRJ");
+}
+
+/** Generate the next sequential, date-stamped packet ID for a raw subdir. */
+function nextSequentialId(dir: string, kind: string): string {
   const today = new Date().toISOString().split("T")[0];
-  const prefix = `SRC-${today}`;
+  const prefix = `${kind}-${today}`;
 
-  if (!existsSync(paths.rawSources)) return `${prefix}-001`;
+  if (!existsSync(dir)) return `${prefix}-001`;
 
-  const dirs = readdirSync(paths.rawSources)
+  const dirs = readdirSync(dir)
     .filter((d) => d.startsWith(prefix))
     .sort();
 

package/extensions/llm-wiki/lib/visible-status.ts

@@ -0,0 +1,51 @@
+import { MODEL_STATUS_KEY, formatActiveModelLabel } from "./model-command.js";
+import type { Runtime } from "./runtime.js";
+import { noticesEnabled } from "./task-config.js";
+
+/**
+ * Minimal sink for the two status keys this helper writes. Mirrors the slice
+ * of `ctx.ui` the extension uses; kept narrow so tests don't need to fake the
+ * whole pi UI surface.
+ */
+export interface StatusSink {
+  setStatus(key: string, value: string): void;
+}
+
+/**
+ * Apply the two post-session-start visible status lines (issue #77,
+ * regression-fixed in #83, comments + tests hardened in #84):
+ *
+ *   1. `🧠 LLM Wiki (… tools, … active)`     — the "wiki is loaded" badge
+ *   2. `🧠 wiki model: <label>`              — the active background task model
+ *
+ * Both are user-facing chat noise and are gated by `llm-wiki.notices`
+ * (default `true`). When `notices: false`, neither status is set — that's the
+ * contract the regression in #83 was about.
+ *
+ * Extracted from `index.ts` so the gating contract is unit-testable without
+ * faking the entire pi extension factory; see `test/visible-activity.test.ts`.
+ *
+ * Pure modulo `ui.setStatus`. Callers MUST run `runtime.ensureConfig(...)` for
+ * the current cwd before invoking this so `noticesEnabled(runtime.config)`
+ * sees the loaded project settings.
+ */
+export function applySessionStartStatus(opts: {
+  ui: StatusSink;
+  runtime: Runtime;
+  trajectoriesOn: boolean;
+  sessionModelId: string | undefined;
+}): void {
+  // Single gate for BOTH status lines (#83 added two adjacent guards; #84
+  // collapses them — same condition, same scope).
+  if (!noticesEnabled(opts.runtime.config)) return;
+
+  opts.ui.setStatus(
+    "llm-wiki",
+    opts.trajectoriesOn
+      ? "🧠 LLM Wiki (16 tools, trajectory + observe + recall active)"
+      : "🧠 LLM Wiki (13 tools, observe + recall active)",
+  );
+
+  const modelLabel = formatActiveModelLabel(opts.runtime.config, opts.sessionModelId);
+  opts.ui.setStatus(MODEL_STATUS_KEY, `🧠 wiki model: ${modelLabel}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",

package/prompts/wiki-record.md

@@ -0,0 +1,36 @@
+---
+description: Capture the just-completed task's tool-call trajectory into the wiki as agent working-memory, then optionally distill it into a reusable skill.
+argument-hint: "<title> [--outcome success|failure|partial]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-record
+
+Capture the trajectory of the task you just completed — the sequence of tool calls that solved it — into the wiki's working-memory layer.
+
+This is the counterpart to source capture: instead of recording what you *read*, it records what you *did*, so the wiki compounds over your own work.
+
+## User Arguments
+
+$ARGUMENTS
+
+Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the wiki conventions.
+
+## Steps
+
+1. Call `wiki_capture_trajectory` with:
+   - `title`: short descriptive phrase for the task (≤60 chars, noun phrase)
+   - `outcome`: optional — `success` (default), `failure`, or `partial`
+   - The extension auto-extracts the tool-call trajectory from the live session, so you usually do **not** pass `steps` manually.
+2. Open the generated skeleton case page in `wiki/cases/` and flesh out:
+   - **Task** — what was requested
+   - **Approach** — the key steps and decisions (not every tool call, just the meaningful ones)
+   - **Outcome** — the result, and anything worth reusing or avoiding next time
+3. If the task taught a reusable pattern, run `wiki_distill_skills` and create a `skill` page via `wiki_ensure_page(type="skill")` that cites `[[trajectories/TRJ-...]]`.
+4. Confirm the case (and any skill) will be surfaced by `wiki_recall` / `wiki_recall_skill` in future sessions.
+
+**Rules:**
+- Only record tasks worth learning from — non-trivial debugging, refactors, integrations, multi-step workflows. Skip trivial one-shot answers.
+- The raw trajectory packet under `raw/trajectories/` is immutable. Edit the `case`/`skill` pages, never the packet.
+- One trajectory per `wiki_capture_trajectory` call.

package/prompts/wiki-run.md

@@ -24,6 +24,8 @@ $ARGUMENTS
 
 ### Scheduling
 
-If `--schedule` is provided, call `wiki_watch(interval=<daily|weekly>)` to set up automatic updates.
+If `--schedule` is provided, call `wiki_watch(interval=<daily|weekly|hourly>)`.
 
-If `--schedule hourly` is provided, call `wiki_watch(interval=hourly)`.
+**Important:** `wiki_watch` does NOT install a schedule. It only prints a `crontab` line.
+Report the printed line to the user verbatim and tell them to install it themselves with
+`crontab -e`. Do not claim the schedule is active until they confirm they have done so.

package/prompts/wiki-skills.md

@@ -0,0 +1,26 @@
+---
+description: Search the wiki's distilled skills and past cases for patterns relevant to the current task — "have I done something like this before?".
+argument-hint: "[query] [--kind skill|case]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-skills
+
+Search the agent working-memory layer of the wiki: reusable **skills** distilled from past trajectories, and specific past **cases**.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+1. Call `wiki_recall_skill` with:
+   - `query`: the current task description or key terms (defaults to `$ARGUMENTS`)
+   - `kind`: optional — `skill`, `case`, or `any` (default)
+   - `max_results`: optional (default 5)
+2. Read the most relevant skill/case pages with `read`.
+3. Apply the recalled pattern to the current task, citing the source page with `[[skills/...]]` or `[[cases/...]]` where helpful.
+4. If no relevant skill/case exists, proceed with the task and consider running `/wiki-record` afterward so the next attempt benefits.
+
+**Tip:** Skills generalize across many trajectories ("how I do X"); cases are concrete past runs ("the time I did X for project Y"). Search `any` first, then narrow.

package/skills/llm-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: llm-wiki
-description: Build and maintain a persistent, interlinked Obsidian-compatible markdown wiki using Karpathy's LLM Wiki pattern. Extension-backed with auto-generated metadata, guardrails, and 12 custom tools.
-whenToUse: Call wiki_recall at task start to find relevant wiki pages. Call wiki_retro at task end to save new insights. The extension injects a brief status line, but explicit wiki_recall calls with task-specific terms get better results.
+description: Build and maintain a persistent, interlinked Obsidian-compatible markdown wiki using Karpathy's LLM Wiki pattern. Extension-backed with auto-generated metadata, guardrails, and 13 custom tools (+3 opt-in agent-trajectory tools).
+whenToUse: Call wiki_recall at task start to find relevant wiki pages. Call wiki_retro at task end to save new insights. When agent-trajectory working-memory is enabled (opt-in, /wiki-trajectories on), also call wiki_recall_skill at task start to find reusable skills / past cases ("have I done this before?") and wiki_capture_trajectory after non-trivial tasks to record how you solved them. The extension injects a brief status line, but explicit calls with task-specific terms get better results.
 ---
 
 # LLM Wiki for Pi
@@ -20,12 +20,18 @@ WIKI_ROOT/
     │   ├── original/
     │   ├── extracted.md
     │   └── attachments/
+    ├── raw/trajectories/TRJ-*/ # Immutable agent task packets (extension-owned)
+    │   ├── manifest.json      # Capture metadata (format: trajectory)
+    │   ├── packet.json        # Full tool-call sequence
+    │   └── extracted.md       # README summary
     ├── wiki/                  # Editable knowledge pages (you own this)
     │   ├── sources/           # One summary per source
     │   ├── entities/          # People, orgs, tools, products
     │   ├── concepts/          # Ideas, patterns, frameworks
     │   ├── syntheses/         # Cross-cutting analyses
-    │   └── analyses/          # Durable query answers
+    │   ├── analyses/          # Durable query answers
+    │   ├── cases/             # One specific past task per trajectory
+    │   └── skills/            # Reusable patterns distilled from trajectories
     ├── meta/                  # Auto-generated (extension-owned)
     │   ├── registry.json      # Master page catalog
     │   ├── backlinks.json     # Inbound link map
@@ -46,6 +52,49 @@ WIKI_ROOT/
 6. **CITE SOURCES.** Every claim links back to its raw source packet.
 7. **FLAG CONTRADICTIONS.** When sources disagree, document both sides.
 
+## Agent Working-Memory (Trajectories)
+
+The wiki captures not only what you *read* (sources) but what you *do*
+(trajectories). A completed task is just another kind of source, so it flows
+through the same pipeline:
+
+```
+raw/trajectories/TRJ-*  →  wiki/skills/*  (+ optional wiki/cases/*)  →  meta/*
+```
+
+> **Opt-in, off by default** (issue #80). The three tools below are only registered
+> when `llm-wiki.trajectories` is enabled. Turn it on with `/wiki-trajectories on`
+> (off with `/wiki-trajectories off`); toggling reloads the extension. When off, the
+> tools are absent entirely — no system-prompt cost.
+
+- `wiki_capture_trajectory` writes the immutable packet + a **self-contained summary**
+  (`extracted.md`), auto-extracting the tool-call sequence from the live session (you
+  usually only pass a `title`). It does **not** emit a to-be-fleshed skeleton — capture
+  is a single lightweight call.
+- `wiki_distill_skills` returns undistilled trajectories so you can generalize them
+  into reusable `skill` pages (and optionally `case` pages) via `wiki_ensure_page`.
+- `wiki_recall_skill` filters layered recall to `skill`/`case` pages —
+  "have I done something like this before?". Call it at task start.
+
+A **skill** generalizes across many trajectories ("how I do X"); a **case** is one
+concrete past run ("the time I did X for project Y"). Trajectory packets live under
+`raw/**` and are therefore immutable under the same guardrail as source packets —
+edit the `case`/`skill` pages, never the packet.
+
+### When to use which memory tool
+
+| Tool | Stores | Use for |
+|------|--------|---------|
+| `wiki_capture_trajectory` | A structured, **replayable** tool-call packet (`packet.json`: tool names + arguments + results + errors) | "How did I *mechanically* solve this?" — the exact step sequence, to distill into a repeatable skill |
+| `wiki_retro` | A durable prose **insight** (one markdown file) | "What did I learn?" — a lesson/gotcha worth keeping, not a step list |
+| `wiki_observe` | A timestamped prose **observation** | Lightweight running notes the extension reminds you to jot during a task |
+
+Why a separate trajectory store and not pi's built-in observational-memory? pi's
+observational-memory keeps **prose** for context-compaction survival — it does not
+persist the structured tool-call sequence (names, arguments, results). The trajectory
+packet is the only artifact that captures a task as a replayable record, which is what
+makes skill distillation possible.
+
 ## How the Extension Helps You
 
 | Task                        | Before (skill-only)          | Now (extension-backed)                |
@@ -87,6 +136,8 @@ Recall scales with vault size via **two-stage retrieval** (memex-style):
 
 The gate is the `recallLinksThreshold` setting (namespaced `llm-wiki`, default **50** pages). Page count is read from `meta/registry.json` (O(1), no page-body I/O). Set it to `0` to force links-first always, or a large number to always keep previews inline.
 
+**Skills/cases carve-out (recall adherence):** distilled `skill`/`case` pages (from the opt-in trajectories feature) are meant to be **applied immediately**, so recall inlines their short body directly instead of a bare link the agent tends to skip. The `recallSkillInlineMax` setting (namespaced `llm-wiki`, default **1600** chars, clamped to a non-negative integer) caps how much body is inlined; set it to `0` to disable inlining entirely (skills/cases fall back to pure links-first, and no page body is read at format time). Only relevant when `trajectories` is enabled.
+
 ### At End — Save Insights with wiki_retro
 
 After completing any meaningful task, call `wiki_retro` to save key insights:
@@ -150,6 +201,9 @@ Use these directly — they handle scaffolding, bookkeeping, recall, and capture
 - `wiki_rebuild_meta` — Force metadata rebuild
 - `wiki_log_event` — Record a custom event
 - `wiki_watch` — Schedule auto-updates
+- `wiki_capture_trajectory` — Capture the completed task's tool-call trajectory (working-memory)
+- `wiki_distill_skills` — Batch undistilled trajectories for skill synthesis
+- `wiki_recall_skill` — Recall distilled skills + similar past cases
 
 ## Workflows
 
@@ -180,6 +234,15 @@ Use these directly — they handle scaffolding, bookkeeping, recall, and capture
 4. Extension auto-updates metadata
 5. Next time, layered recall surfaces your saved insight
 
+### Task → Record → Distill (agent working-memory)
+
+1. Finish a non-trivial task (debug, refactor, integration)
+2. `wiki_capture_trajectory(title="...")` — auto-extracts the tool-call trajectory into `raw/trajectories/TRJ-*` with a self-contained summary (no skeleton)
+3. Flesh out the `wiki/cases/` page (Task → Approach → Outcome)
+4. `wiki_distill_skills()` — get undistilled trajectories
+5. `wiki_ensure_page(type="skill", title="...")` — generalize into a reusable skill citing `[[trajectories/TRJ-...]]`
+6. Next time, `wiki_recall_skill(query="...")` surfaces the skill/case before you start
+
 ## Page Conventions
 
 ### Naming
@@ -191,7 +254,7 @@ Use these directly — they handle scaffolding, bookkeeping, recall, and capture
 
 ```yaml
 ---
-type: entity | concept | source | synthesis | analysis
+type: entity | concept | source | synthesis | analysis | skill | case | trajectory
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
 sources: [sources/SRC-YYYY-MM-DD-NNN]
@@ -200,10 +263,13 @@ sources: [sources/SRC-YYYY-MM-DD-NNN]
 
 Entity: add `category: person | organization | tool | project | product`
 Concept: add `domain: ai | engineering | business | product | design | personal`
+Skill: add `trajectories: [trajectories/TRJ-YYYY-MM-DD-NNN]`
+Case: add `trajectory_id: TRJ-YYYY-MM-DD-NNN` and `outcome: success | failure | partial`
 
 ### Citations
 
 Use stable source IDs: `[[sources/SRC-2026-04-28-001]]`
+Cite trajectories with their stable IDs: `[[trajectories/TRJ-2026-04-28-001]]`
 
 ### Contradictions