pi-weave 0.1.20 → 0.1.21

package/README.md

@@ -13,20 +13,17 @@
 
 **A local knowledge workspace you can talk to.**
 
-pi-weave is an extension for [pi](https://github.com/earendil-works/pi). Ask Pi to take notes while you think out loud, keep your exact
-words alongside a useful summary, and explore everything in `/weave-view`.
+pi-weave is an extension for [pi](https://github.com/earendil-works/pi). Ask Pi to take notes while you think out loud, keep your exact words alongside a useful summary, and explore everything in `/weave-view`.
 
-It also understands the repository you are working in. Personal notes live in a Markdown vault; repository knowledge lives in a disposable
-`.okf` index. Both are plain files that humans and agents can read.
+It also understands the repository you are working in. Personal notes live in a Markdown vault; repository knowledge lives in a disposable `.okf` index. Both are plain files that humans and agents can read.
 
 ## Core capabilities
 
-- **Conversational note-taking.** Create and update notes through natural-language requests such as “start a note”, “add this”, or “remember
-  that”.
-- **Verbatim narration with structured summaries.** During dictation, Pi preserves each spoken passage in an append-only `## Raw` section
-  while maintaining an organized summary above it.
+- **Conversational note-taking.** Create and update notes through natural-language requests such as “start a note”, “add this”, or “remember that”.
+- **Verbatim narration with structured summaries.** During dictation, Pi preserves each spoken passage in an append-only `## Raw` section while maintaining an organized summary above it.
 - **Knowledge retrieval.** Pi searches existing notes when answering questions about previous decisions, people, projects, or meetings.
 - **Unified visual workspace.** `/weave-view` presents notes, links, repository structure, and provenance in a live browser interface.
+- **Optional session memory.** `/weave-scan sessions` turns changed pi transcripts into searchable notes with reusable technical takeaways.
 - **Repository exploration.** A lightweight, git-aware index gives Pi a structural overview of the current codebase before it reads files.
 
 Nothing is captured silently. pi-weave creates or extends a personal note only when you ask it to.
@@ -74,8 +71,7 @@ For each chunk, Pi:
 2. refreshes the structured summary above it;
 3. leaves the raw record untouched.
 
-This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation
-remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
+This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
 
 Useful requests include:
 
@@ -102,13 +98,21 @@ The browser workspace has four connected views:
 - **Graph** — a navigable map of notes, links, mentions, modules, and repository relationships. Selecting something updates every view.
 - **Context** — links, backlinks, tags, and code mentions for the current selection.
 
-Search with `⌘K` / `Ctrl K`. Press `?` for all shortcuts. The workspace updates as notes change on disk, so a note written by Pi appears
-without a reload. It follows the system theme by default and can be switched between light and dark.
+Search with `⌘K` / `Ctrl K`. Press `?` for all shortcuts. The workspace updates as notes change on disk, so a note written by Pi appears without a reload. It follows the system theme by default and can be switched between light and dark.
 
 The browser is read-only. Edit with `$EDITOR`, Obsidian, or the `weave_note` tool; unknown front-matter fields remain preserved.
 
 `/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
 
+## Remember past pi sessions
+
+```bash
+/weave-scan sessions                    # pi history (default)
+/weave-scan sessions /path/to/history   # explicit history root
+```
+
+This opt-in scan treats a supplied file—or every bounded text file under a supplied directory—as opaque session material for the active model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. That makes it usable with Claude Code, opencode, Codex, or exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable technical takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
+
 ## Repository knowledge
 
 Inside a Git repository, pi-weave detects whether `<repo>/.okf/` is missing, fresh, or stale.
@@ -118,11 +122,9 @@ Inside a Git repository, pi-weave detects whether `<repo>/.okf/` is missing, fre
 /weave-scan deep    # also summarize changed files with the active model
 ```
 
-The light index covers languages, packages, modules, entry points, and Git state. A deep scan adds short per-file summaries and only
-revisits files whose content changed.
+The light index covers languages, packages, modules, entry points, and Git state. A deep scan adds short per-file summaries and only revisits files whose content changed.
 
-The repository index is a cache, not a source of truth. Delete `.okf`, scan again, and nothing important is lost. pi-weave excludes it
-locally from Git by default.
+The repository index is a cache, not a source of truth. Delete `.okf`, scan again, and nothing important is lost. pi-weave excludes it locally from Git by default.
 
 ## Commands and tools
 
@@ -134,7 +136,8 @@ Most people only need natural language and `/weave-view`.
 | Command | `/weave` | Show vault and repository status |
 | Command | `/weave-scan` | Build or refresh the repository index |
 | Command | `/weave-scan deep` | Add incremental model-written file summaries |
-| Command | `/weave-scan-cancel` | Stop a deep scan |
+| Command | `/weave-scan sessions [path]` | Turn changed session-history files into durable memory notes |
+| Command | `/weave-scan-cancel` | Stop a deep or session scan |
 | Tool | `weave_note` | List, read, add, append, finalize, and search notes |
 | Tool | `weave_repo` | Check, scan, and summarize the repository index |
 
@@ -178,8 +181,7 @@ We probably want OIDC next quarter…
 
 Set `PI_WEAVE_VAULT` to use a different vault location.
 
-Reading, writing, searching, and viewing notes are local operations. Deep repository scans send bounded input to whichever model you
-configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi session.
+Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to whichever model you configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi session.
 
 The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no pi-specific imports.
 
@@ -199,8 +201,7 @@ npm run coverage
 npm run build:web
 ```
 
-Coverage must remain at or above **95%** for lines, branches, functions, and statements. If browser source changes, rebuild and commit
-`src/web/client/dist/app.js`.
+Coverage must remain at or above **95%** for lines, branches, functions, and statements. If browser source changes, rebuild and commit `src/web/client/dist/app.js`.
 
 Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do not commit directly to `main`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "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,

package/skills/weave-explore/SKILL.md

@@ -34,6 +34,8 @@ directly.
 and incremental**: it never runs implicitly, and it only re-summarizes files whose content hash changed since their last summary. If
 summaries are missing or stale, offer `/weave-scan deep` to create or refresh them before diving into full files.
 
+Its sibling `/weave-scan sessions` is a different scope: it summarizes past *session transcripts* into the vault (`notes/sessions/`), not the repository. See the `weave-notepad` skill — nothing it writes lands in `.okf/`.
+
 ## On-disk layout
 
 ```text

package/skills/weave-notepad/SKILL.md

@@ -95,6 +95,16 @@ down". Never promote conversation into a note on your own initiative — capture
    for user-scribbled notes. Notes you draft from scratch are `source: agent` (the default). Never overwrite a `source: human` note's
    meaning; append with a dated "Agent addendum" section instead.
 
+## Session memory (`notes/sessions/`)
+
+`/weave-scan sessions` summarizes past agent session transcripts into generated notes under `notes/sessions/`. These are ordinary vault notes — `search` and `get` reach them like any other — with three differences worth knowing:
+
+- They are `source: generated`, not human knowledge. Treat one as a recollection of what a past session did, not as a decision record; a human note that contradicts it wins.
+- Each carries a `## Takeaways` section: reusable technical lessons (gotchas, root causes, non-obvious rules) from that session. When the user hits a problem that smells familiar, search the vault before re-deriving the answer — a previous session may already have paid for it.
+- They are re-derivable. The scan rewrites a note in place when its transcript changes, preserving human edits above the raw tail, so no session note is the only copy of anything.
+
+The scan is opt-in and never runs on its own. Suggest it when the user asks why the agent keeps forgetting across sessions, or wants history from another tool (`/weave-scan sessions <path>` accepts any history file or directory). Never run it unprompted: it spends model tokens per changed session.
+
 ## Retrieving knowledge
 
 Use `weave_note` action=search with the user's key terms, then `get` the best hits. When a note and the repository index disagree, trust the

package/src/core/concurrency.ts

@@ -1,5 +1,5 @@
 /**
- * Bounded-concurrency task runner shared by repository scans.
+ * Bounded-concurrency task runner shared by repository and session scans.
  *
  * Keeping the scheduler here gives every scan the same cancellation behavior.
  */

package/src/core/frontmatter.ts

@@ -301,6 +301,36 @@ export function parseFrontMatter(text: string): ParsedFrontMatter | null {
   return { fields, body, lines };
 }
 
+/** Upsert generated scalar fields while preserving unrelated front matter. */
+export function upsertFrontMatterFields(
+  lines: NoteFrontMatter,
+  fields: Record<string, string>,
+): NoteFrontMatter {
+  const wanted = new Set(Object.keys(fields));
+  const written = new Set<string>();
+  const out: string[] = [];
+  let droppingBlock = false;
+  for (const line of scanFrontMatter(lines)) {
+    if (droppingBlock) {
+      if (/^\s/.test(line.text)) continue;
+      droppingBlock = 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);
+        droppingBlock = !line.scalar;
+      }
+      continue;
+    }
+    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/index.ts

@@ -4,7 +4,7 @@
  * NO harness imports allowed in this tree (see docs/design.md §21).
  */
 export type { WorkspaceStatus } from "./types";
-export { NOTES_DIR, repoIndexDir, resolveVaultRoot } from "./paths";
+export { NOTES_DIR, SESSIONS_DIR, repoIndexDir, resolveVaultRoot } from "./paths";
 export { findGitRoot } from "./git";
 export {
   assessStaleness,
@@ -14,6 +14,29 @@ export {
   writeRepoIndex,
 } from "./repoIndex";
 export { runDeepScan, type DeepScanOptions, type DeepScanResult, type SummarizeFn } from "./summaries";
+export {
+  DEFAULT_SESSIONS_ROOT,
+  SESSIONS_ENV_VAR,
+  deriveSessionTitle,
+  listSessionFiles,
+  migrateLegacySessionNotes,
+  parseSessionDigest,
+  peekSessionHeader,
+  projectTagOf,
+  readSessionNoteIndex,
+  renderSessionDigest,
+  resolveSessionsRoot,
+  runSessionScan,
+  sessionHasContent,
+  sessionNoteBody,
+  sessionNoteFields,
+  sessionNoteTags,
+  writeSessionNote,
+  type SessionChain,
+  type SessionDigest,
+  type SessionScanOptions,
+  type SessionScanResult,
+} from "./sessions";
 export {
   addNote,
   appendToNote,
@@ -34,6 +57,7 @@ export {
   resolveHtmlPath,
   resolveNotePath,
   searchNotes,
+  upsertNote,
 } from "./vault";
 export type { HtmlArtifact } from "./types";
 export { withMutationQueue } from "./mutex";

package/src/core/paths.ts

@@ -14,6 +14,7 @@ import { join } from "node:path";
 export const OKF_DIR = ".okf";
 export const OKF_MANIFEST = "okf.json";
 export const NOTES_DIR = "notes";
+export const SESSIONS_DIR = "sessions";
 export const REPOSITORY_DIR = "repository";
 export const VAULT_ENV_VAR = "PI_WEAVE_VAULT";