pi-weave 0.1.8 → 0.1.9

package/README.md

@@ -1,7 +1,7 @@
 # pi-weave
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.jpg" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
+  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.png" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
 </p>
 
 <p align="center">
@@ -28,7 +28,7 @@ format. Every generated artefact carries provenance (`human`, `agent` or `genera
 something you wrote.
 
 ```
-🧵 vault:12 · my-project:ok      ← pi's status line when weave is active
+🕸️ vault:12 · my-project:ok      ← pi's status line when weave is active
 ```
 
 See [docs/design.md](docs/design.md) for the reasoning behind all of it.
@@ -56,7 +56,8 @@ On session start pi-weave detects the repository you are in, checks whether `.ok
 | Command | `/weave-view` | open the knowledge workspace in your browser |
 | Command | `/weave-scan` | build or refresh the repository index (light) |
 | Command | `/weave-scan deep` | light index plus model-written per-file summaries (opt-in, incremental, background) |
-| Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` run |
+| Command | `/weave-scan sessions` | summarize pi session history into the vault as memory notes (incremental, background) |
+| Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` or `sessions` run |
 | Skill | `weave-notepad` | how the agent should take good notes |
 | Skill | `weave-explore` | how the agent should explore repositories |
 
@@ -64,6 +65,11 @@ On session start pi-weave detects the repository you are in, checks whether `.ok
 whose content hash has not changed since their last summary. It costs tokens, so it never runs implicitly — and it runs in the background,
 so `/weave-scan-cancel` can stop it mid-flight.
 
+`/weave-scan sessions` is the repo-agnostic sibling (docs/session-scan.md): it reads every pi session transcript under
+`~/.pi/agent/sessions/`, hashes each file while reading it, and writes one generated vault note per changed session under
+`~/.okf/notes/sessions/` — pi's memory as first-class, wikilinked notes in an inner folder of the vault graph. Unchanged transcripts cost no
+LLM calls at all, and older layouts migrate automatically on the next scan.
+
 ## The workspace
 
 `/weave-view` opens a browser knowledge workspace over the same graph the tools see — the vault and the repository index as one model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
   "type": "module",
   "sideEffects": false,
@@ -41,7 +41,7 @@
     "skills": [
       "./skills"
     ],
-    "image": "https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.jpg"
+    "image": "https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.png"
   },
   "scripts": {
     "test": "vitest run",

package/skills/weave-notepad/SKILL.md

@@ -15,10 +15,17 @@ In pi, use the `weave_note` tool. In other harnesses (or when the tool is not av
 - **Notes** live at `~/.okf/notes/<slug>.md` (vault root overridable via `PI_WEAVE_VAULT`).
 - Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601), `tags: [..]`, and `source: human | agent | generated`.
 - `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`. `finalize` restructures the body *above* the `## Raw` tail and
-  preserves the tail verbatim.
+  preserves the tail verbatim — a body with no tail yet is preserved **in full** as a newly created tail, so finalization never destroys
+  dictation.
+- **Dictation appends**: use `append` with `raw: true` — the tool appends the text verbatim into the `## Raw` tail as a dated fenced block,
+  creating the tail if the note has none. In pi, never hand-format the raw tail; the tool maintains it.
 
 ## Raw Tail Format
 
+In pi you rarely format this by hand: `weave_note` append with `raw: true` appends a dated fenced block into the tail (and creates the whole
+tail — separator, heading, notice — when the note has none). The format below is what that produces, and what to write when editing files
+directly or working in other harnesses.
+
 Every note maintains a verbatim, append-only raw section at the bottom separated by a horizontal rule (`---`):
 
 ---
@@ -50,7 +57,8 @@ Every note maintains a verbatim, append-only raw section at the bottom separated
 During live dictation / interview note-taking (see the skill description), Pi does **not** wait until the end to organize the note. Every
 interactive append is immediately compiled into the body:
 
-1. **Append the raw words verbatim** to the `## Raw` tail as usual (a dated `<!-- appended YYYY-MM-DD HH:MM -->` code block).
+1. **Append the raw words verbatim** into the `## Raw` tail (`weave_note` action=append with `raw: true` — the tool adds the dated code block
+   and creates the tail if missing).
 2. **Then immediately finalize** (`weave_note` action=finalize): rewrite the body *above* the `## Raw` tail — front-loaded summary,
    sections, decisions, questions, tasks, entities, links — so the compiled document reflects everything said so far.
 3. **Never rewrite or remove the `## Raw` tail.** It stays append-only and verbatim; only the body above it changes.
@@ -74,13 +82,14 @@ down". Never promote conversation into a note on your own initiative — capture
 1. **Search first** (`weave_note` action=search): if a note exists, `append` to it rather than creating a duplicate.
 2. Title: short noun phrase ("Auth boundary decision", not "Notes").
 3. **Scribble in, verbatim.** When the user is dictating, append their words to the note as rough, verbatim scribbles — no silent rewording.
-   Keep them under the `## Raw` tail format at the end of the note.
+   Append with `raw: true` so they land under the `## Raw` tail at the end of the note (the tail is created automatically if missing).
 4. **Compile continuously during dictation.** After *every* interactive append in dictation mode, immediately finalize the body *above* the
    raw tail so the compiled doc stays current (see [Dictation mode](#dictation-mode-continuous-compile)). Outside dictation mode,
    compilation stays on request.
 5. **Finalize on request.** When the user says "finalize this" / "clean this up", restructure the body *above* the raw tail: front-loaded
    summary, sections, entities, links. Use `weave_note` action=finalize (or edit the file directly in other harnesses). Move nothing out of
-   `## Raw` — it is append-only and never rewritten.
+   `## Raw` — it is append-only and never rewritten. A note with no `## Raw` tail yet gets its entire pre-finalize body preserved as a new
+   raw tail: finalization is editorial, never destructive.
 6. Tags: 1–4 lowercase tags; reuse existing tags when possible.
 7. Provenance: notes the user scribbled stay `source: human` (finalization is editorial, not authorship) — pass `source: "human"` to `add`
    for user-scribbled notes. Notes you draft from scratch are `source: agent` (the default). Never overwrite a `source: human` note's

package/src/core/concurrency.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounded-concurrency task runner shared by the deep scan (summaries.ts) and
+ * the session scan (sessions.ts).
+ *
+ * Extracted from summaries.ts so the two scanners cannot drift: a second copy
+ * of the scheduler is a second place for an off-by-one or a lost
+ * cancellation check.
+ */
+
+/**
+ * Map `items` through `fn` with at most `concurrency` tasks in flight.
+ *
+ * Results keep input order. `shouldStop` is checked before each item is
+ * taken; when it returns true, workers drain immediately and unprocessed
+ * entries keep their slot in the results array (untouched — callers that
+ * care about partial output must check `shouldStop` themselves, exactly as
+ * the abort-aware scanners do).
+ */
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>,
+  shouldStop?: () => boolean,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      if (shouldStop?.()) return;
+      const i = next++;
+      results[i] = await fn(items[i] as T, i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
+  return results;
+}

package/src/core/frontmatter.ts

@@ -289,6 +289,59 @@ export function parseFrontMatter(text: string): ParsedFrontMatter | null {
   return { fields, body, lines };
 }
 
+/**
+ * Upsert owned scalar fields into a front-matter block, preserving order.
+ *
+ * For each wanted key: the **first** line declaring it is replaced with a
+ * fresh `key: value` line in place, and any later declarations are dropped —
+ * mirroring how duplicate managed keys collapse in `replayBlock` (the
+ * subset parser keeps the last occurrence, so collapsing to one line with
+ * the fresh value is the consistent outcome). A key introducing a block
+ * construct (`scalar: false`) is replaced too: the value this function writes
+ * is a scalar, and leaving the old block head in place would orphan its
+ * indented children under a duplicated key.
+ *
+ * Wanted keys the block never declared are appended at the end, in the order
+ * given. Everything else — unknown keys, blank lines, junk — is carried
+ * through byte-identically, the same round-trip contract `serializeNote`
+ * honors for the note engine's writes.
+ *
+ * Keys arrive from pi-weave's own generated-note writers (`session_id`,
+ * `session_hash`, …); there is no escaping for the *key* because a key is
+ * caller-controlled code, not user input — `quoteField` guards the value.
+ */
+export function upsertFrontMatterFields(
+  lines: NoteFrontMatter,
+  fields: Record<string, string>,
+): NoteFrontMatter {
+  const wanted = new Set(Object.keys(fields));
+  const out: string[] = [];
+  const written = new Set<string>();
+  let inDroppedBlock = false;
+  for (const line of scanFrontMatter(lines)) {
+    // Continuation lines of a block construct whose head we replaced: their
+    // parent key is gone, so carrying them would leave orphaned YAML children
+    // under a scalar. The block ends at the first non-indented line.
+    if (inDroppedBlock) {
+      if (/^\s/.test(line.text)) continue;
+      inDroppedBlock = false;
+    }
+    if (line.key !== null && wanted.has(line.key)) {
+      if (!written.has(line.key)) {
+        out.push(`${line.key}: ${quoteField(fields[line.key] ?? "")}`);
+        written.add(line.key);
+        if (!line.scalar) inDroppedBlock = true; // swallow the block body too
+      }
+      continue; // later duplicates collapse into the first occurrence
+    }
+    out.push(line.text);
+  }
+  for (const [key, value] of Object.entries(fields)) {
+    if (!written.has(key)) out.push(`${key}: ${quoteField(value)}`);
+  }
+  return out;
+}
+
 /**
  * Parse a note file. Throws on missing/invalid front matter so callers can
  * treat the file as malformed rather than guessing.

package/src/core/graph/build.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Note, RepoIndex, StalenessReport, VaultStatus } from "../types";
+import { createHash } from "node:crypto";
 import type { SummaryRecord } from "../summaries";
 import type { EdgeKind, GraphEdge, GraphModel, GraphNode } from "./model";
 import { buildPathIndex, resolveMentions, type PathIndex } from "./mentions";
@@ -30,6 +31,30 @@ export interface BuildGraphInput {
 const SHORT_SHA_LEN = 7;
 const PREVIEW_LEN = 240;
 
+/** Hex length of {@link noteBodyDigest} and of the model's `contentDigest`. */
+const DIGEST_HEX_LEN = 32;
+
+/**
+ * Content fingerprint of one note body. Pure, deterministic, truncated to
+ * 128 bits — a change-detection key, not a security boundary.
+ */
+export function noteBodyDigest(body: string): string {
+  return createHash("sha256").update(body).digest("hex").slice(0, DIGEST_HEX_LEN);
+}
+
+/**
+ * The model's `contentDigest`: one hash over every note's slug and body
+ * digest, slug-sorted so it does not depend on note order. Empty when there
+ * are no notes — which is still a distinct value from any non-empty vault.
+ */
+export function noteContentDigest(notes: readonly Note[]): string {
+  const hash = createHash("sha256");
+  for (const note of [...notes].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0))) {
+    hash.update(`${note.slug}\u0000${noteBodyDigest(note.body)}\n`);
+  }
+  return hash.digest("hex").slice(0, DIGEST_HEX_LEN);
+}
+
 function moduleDetail(
   path: string,
   fileCount: number,
@@ -107,6 +132,37 @@ function buildVaultSide(
   nodes.push({ id: "vault", kind: "vault", label: "Vault", provenance: null, detail: vaultDetail });
 
   const keptSlugs = new Set(kept.map((n) => n.slug));
+
+  // Nested notes (`sessions/foo` — session memory, docs/session-scan.md) nest
+  // under synthesized folder nodes so the vault tree groups them the way the
+  // repository tree groups directories. Ids are prefixed `vfolder:` because a
+  // repository module could legitimately share the path (`module:sessions`);
+  // the tree renders any `contains` chain, so the kind reuse needs no client
+  // change. Deterministic: dirs sorted, parents before children.
+  const folderIds = new Map<string, string>();
+  const noteDirs = [...new Set(kept.map((n) => n.slug.split("/").slice(0, -1).join("/")))]
+    .filter((d) => d.length > 0)
+    .sort();
+  const notesIn = (dir: string): number => kept.filter((n) => n.slug.startsWith(`${dir}/`)).length;
+  for (const dir of noteDirs) {
+    const id = `vfolder:${dir}`;
+    folderIds.set(dir, id);
+    nodes.push({
+      id,
+      kind: "module",
+      label: dir.split("/").pop() ?? dir,
+      provenance: null,
+      detail: { path: dir, notes: String(notesIn(dir)) },
+    });
+    const parentDir = dir.split("/").slice(0, -1).join("/");
+    const parent = folderIds.get(parentDir) ?? "vault";
+    edges.push({ source: parent, target: id, kind: "contains" });
+  }
+  const parentOf = (slug: string): string => {
+    const dir = slug.split("/").slice(0, -1).join("/");
+    return (dir.length > 0 && folderIds.get(dir)) || "vault";
+  };
+
   for (const note of kept) {
     const links = extractWikilinks(note.body);
     const resolved = links.filter((slug) => keptSlugs.has(slug));
@@ -127,7 +183,7 @@ function buildVaultSide(
     detail.preview = preview(note.body);
 
     nodes.push({ id: `note:${note.slug}`, kind: "note", label: note.title, provenance: note.source, detail });
-    edges.push({ source: "vault", target: `note:${note.slug}`, kind: "contains" });
+    edges.push({ source: parentOf(note.slug), target: `note:${note.slug}`, kind: "contains" });
     for (const target of resolved) {
       edges.push({ source: `note:${note.slug}`, target: `note:${target}`, kind: "links-to" });
     }
@@ -284,6 +340,9 @@ export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number
     nodes,
     edges,
     danglingLinks,
+    // The same slice the vault side kept, so the digest describes exactly
+    // the notes that have nodes. Slug-ordered inside, hence order-stable.
+    contentDigest: noteContentDigest(input.notes.slice(0, maxNotes)),
   };
 }
 

package/src/core/graph/model.ts

@@ -84,4 +84,19 @@ export interface GraphModel {
    * unchanged inputs.
    */
   danglingLinks: Record<string, string[]>;
+  /**
+   * Content fingerprint of the note bodies the graph was built from
+   * (SHA-256 over `slug\0body-digest` pairs in slug order, truncated to
+   * 128 bits of hex).
+   *
+   * Exists so the wire payload's stamp — the digest the ETag and the SSE
+   * dedupe both key on — is sensitive to a **body-only** edit. The payload
+   * itself carries only display excerpts of a note (`detail.preview`, the
+   * first 240 flattened characters), so an edit below the fold with
+   * unchanged front matter used to leave the payload byte-identical: the
+   * frame was deduped away and the open note stayed stale until a manual
+   * reload. The digest is a function of content only, so it keeps the
+   * byte-determinism contract.
+   */
+  contentDigest: string;
 }

package/src/core/graph/wikilinks.ts

@@ -12,6 +12,10 @@ const WIKILINK_RE = /\[\[([^\][|]+)(?:\|[^\]]*)?\]\]/g;
  * `[[some-note]]` and aliased `[[Some Note|alias]]` (alias ignored for
  * linking). Targets are slugified so `[[Release Plan]]` matches the note
  * `release-plan`. Duplicates are removed, order of first appearance kept.
+ *
+ * Path separators survive: a nested note's slug is its path relative to
+ * `notes/` (`sessions/foo`), so `[[sessions/foo]]` targets the session note,
+ * not a flattened name. Each path segment is slugified independently.
  */
 export function extractWikilinks(body: string): string[] {
   const out: string[] = [];
@@ -19,7 +23,7 @@ export function extractWikilinks(body: string): string[] {
   for (const match of body.matchAll(WIKILINK_RE)) {
     const raw = (match[1] ?? "").trim();
     if (raw.length === 0) continue;
-    const slug = slugify(raw);
+    const slug = raw.split("/").map((part) => slugify(part)).join("/");
     if (seen.has(slug)) continue;
     seen.add(slug);
     out.push(slug);

package/src/core/index.ts

@@ -13,6 +13,8 @@ export * from "./git";
 export * from "./vault";
 export * from "./repoIndex";
 export * from "./summaries";
+export * from "./sessions";
+export * from "./concurrency";
 export * from "./workspace";
 export * from "./openInEditor";
 export * from "./graph/model";

package/src/core/paths.ts

@@ -14,6 +14,13 @@ import { join } from "node:path";
 export const OKF_DIR = ".okf";
 export const OKF_MANIFEST = "okf.json";
 export const NOTES_DIR = "notes";
+/**
+ * Vault collection for generated session memory (docs/session-scan.md).
+ * A sibling of `notes/` rather than a subdirectory of it: session notes are
+ * machine-derived memory, not hand-curated knowledge, so they stay out of
+ * the note graph's flat listing — and out of its slug namespace.
+ */
+export const SESSIONS_DIR = "sessions";
 export const REPOSITORY_DIR = "repository";
 export const VAULT_ENV_VAR = "PI_WEAVE_VAULT";