@hraness/wordcell 0.22.5 → 0.24.0

package/dist/workflows/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   decisionContextWorkflow
-} from "../index-n9kwenpt.js";
+} from "../index-1w0sp1q7.js";
 import {
   explainChangeWorkflow
 } from "../index-e4fagfjz.js";
@@ -9,25 +9,25 @@ import {
   planRadarWorkflow
 } from "../index-rdd5f7jj.js";
 import"../index-h170byqw.js";
-import"../index-42tb8qqp.js";
+import"../index-5d1rd5v9.js";
 import"../index-adx6khj5.js";
-import"../index-n57tewfr.js";
+import"../index-fp732bgg.js";
 import"../index-4j3tt0c3.js";
 import"../index-j70m75wd.js";
-import"../index-gtwqye5a.js";
-import"../index-qdb8f8va.js";
-import"../index-f75zmmdr.js";
-import"../index-pz2b2x0y.js";
+import"../index-tcaq1c7f.js";
+import"../index-bdwcjvr4.js";
+import"../index-1er88ckw.js";
+import"../index-pgtm2nhf.js";
 import"../index-1gwbassd.js";
-import"../index-aer0jdrq.js";
+import"../index-ahyhryb8.js";
 import"../index-1xxnjn0d.js";
-import"../index-8v6k9h4r.js";
+import"../index-1s8mc4hz.js";
 import"../index-d13v9ckt.js";
 import"../index-48pz4jpc.js";
 import"../index-06c9ctr6.js";
 import"../index-5vwpzb5a.js";
 import"../index-3rm7cz6h.js";
-import"../index-zy7an84p.js";
+import"../index-jvb7w0gg.js";
 import"../index-z1w83f81.js";
 export {
   planRadarWorkflow,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.22.5",
-  "description": "A local Markdown knowledge base with superpowers. Save decisions, sources, and plans as files you own, then find them by exact words or, with an optional local model, by meaning.",
+  "version": "0.24.0",
+  "description": "Wordcell keeps decisions, plans, and sources as Markdown beside your code, so coding agents can find them from the file they are about to change.",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -321,6 +321,7 @@
     "src/agent-context.ts",
     "src/agent-guide-audit.ts",
     "src/authoring.ts",
+    "src/authoring-import.ts",
     "src/authoring-model.ts",
     "src/authoring-platform.ts",
     "src/authoring-program.ts",
@@ -331,6 +332,8 @@
     "src/url-intelligence.ts",
     "src/cli.ts",
     "src/cli-intro.ts",
+    "src/cli-help.ts",
+    "src/cli-style.ts",
     "src/cli-program.ts",
     "src/clip/acquire.ts",
     "src/clip/archive-today.ts",
@@ -341,6 +344,7 @@
     "src/clip/bundle-reader.ts",
     "src/clip/capture.ts",
     "src/clip/cli.ts",
+    "src/clip/cookie-permission.ts",
     "src/clip/cookies.ts",
     "src/clip/doctor.ts",
     "src/clip/jobs.ts",
@@ -381,7 +385,10 @@
     "src/evaluation-v2.ts",
     "src/evaluation.ts",
     "src/graph.ts",
+    "src/mcp-server.ts",
+    "src/mcp-tools.ts",
     "src/mention-index.ts",
+    "src/import-supermemory.ts",
     "src/index.ts",
     "src/init.ts",
     "src/navigation.ts",
@@ -430,6 +437,7 @@
     "src/semantic.ts",
     "src/serve.ts",
     "src/sdk.ts",
+    "src/selected-passage.ts",
     "src/source-inbox.ts",
     "src/untrusted-content.ts",
     "src/vault.ts",
@@ -480,8 +488,8 @@
     "check": "bun run check:worker && bun run check:effect && bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
     "prepack": "bun run check",
     "check:effect": "bun run scripts/check-effect-policy.ts",
-    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
-    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz wordcell search --root kb --mode exact",
+    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.24.0/hraness-wordcell-0.24.0.tgz wordcell search --root kb --mode exact --selected-passage --rerank typesafe --rerank-limit 25",
+    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.24.0/hraness-wordcell-0.24.0.tgz wordcell search --root kb --mode exact --selected-passage",
     "check:worker": "tsc -p worker/tsconfig.json --noEmit"
   },
   "dependencies": {

package/skills/wordcell/AGENTS.md

@@ -2,6 +2,7 @@
 
 - `SKILL.md` – public entrypoint, runtime contract, and intent router for all hraness/wordcell agent workflows.
 - `references/query.md` – scoped retrieval through exact metadata, hybrid search, graph structure, and Git provenance.
+- `references/session-memory.md` – authored session notes, their relationships, and maintained profile notes with Stable and Recent sections.
 - `references/customize.md` and `companion-skills.md` – interview-first Wordcell setup, explicit approval boundaries, and contracts for optional recurring rituals.
 - `references/save-url.md`, `url-authentication.md`, and `url-platforms.md` – auditable web capture, signed-in source handling, and platform-specific completeness boundaries.
 - `references/save-pdf.md` and `pdf-review.md` – PDF ingestion, OCR, image evidence, and mixed-media review.

package/skills/wordcell/SKILL.md

@@ -7,7 +7,8 @@ description: >-
   repository context, plans, decisions, concepts, backlinks, semantic search,
   or Git provenance from an earlier coding session; save, clip, scrape, or
   archive a URL, article, social thread, signed-in browser page, or PDF as
-  auditable Markdown; create or update a durable plan in the vault; or refresh,
+  auditable Markdown; create or update a durable plan in the vault; save or
+  remember a conversation as a session note or keep a profile note; or refresh,
   check, percolate, and maintain its knowledge graph. Do not use for generic
   web research, generic PDF reading, or ordinary planning that will not use a
   hraness/wordcell vault.
@@ -29,7 +30,8 @@ selected.
 | User intent | Read |
 | --- | --- |
 | Design, set up, or evolve a Wordcell; choose its boundaries and conventions; or define a recurring Wordcell ritual | [Customize a Wordcell setup](references/customize.md); add [Companion skill contracts](references/companion-skills.md) only when the proposal includes a new or revised skill |
-| Recover work from an earlier session, find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Recover work from an earlier session, read a profile or recall what you remember about the user, find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Save or remember this conversation, record a session summary at session end, or create or update a profile of the user or another person, team, or project | [Save session memory and profiles](references/session-memory.md) |
 | Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
 | Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
 | Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |
@@ -56,7 +58,7 @@ missing:
 ```sh
 command -v wordcell >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.5/hraness-wordcell-0.22.5.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.24.0/hraness-wordcell-0.24.0.tgz
 }
 wordcell --help
 ```

package/skills/wordcell/references/query.md

@@ -14,16 +14,47 @@ authority; search scores, metadata rows, and graph results are derived views.
 - Pass the resolved path to every `--root`; do not scan a repository root merely
   because that is where the agent session started.
 
+## Read the profile first
+
+When the user asks what you remember about them, asks about their preferences,
+or resumes earlier work, read the profile and the latest session notes before
+searching:
+
+```sh
+wordcell list --root "$KB_ROOT" --where type=profile --json
+wordcell list --root "$KB_ROOT" --where type=session --sort date \
+  --order desc --limit 5 --json
+wordcell list --root "$KB_ROOT" --where type=session \
+  --scope packages/parser/src/index.ts --json
+```
+
+Read `$KB_ROOT/notes/profile.md` for the vault owner. Treat its Stable section
+as standing context and its Recent section as dated context to confirm.
+`--scope` matches the exact path a session note declares, not a parent
+directory. `--sort date` lists a session note without a `date` field, such as
+one saved over MCP alone, after every dated session, so a `--limit` can hide
+it. When the vault may hold such notes, list sessions again without `--sort`
+or `--limit`.
+
+Over the local MCP server that `wordcell mcp --root "$KB_ROOT"` starts, call
+`list_notes` with
+`"where": [{"path": "type", "value": "profile"}]`, then `get_note`. For recent
+sessions, pass `"where": [{"path": "type", "value": "session"}]`,
+`"sort": "metadata.date"`, and `"order": "desc"`.
+[The session-memory guide](session-memory.md) describes how these notes are
+written.
+
 ## Recover a stopped session
 
-When the user asks to resume earlier work, begin with the path being changed.
+When the user asks to resume earlier work, read the profile and recent
+sessions as described above, then continue with the path being changed.
 Keep each retrieval signal separate so the agent can inspect why a record was
 returned:
 
 ```sh
 wordcell context packages/parser/src/index.ts --root "$KB_ROOT" --repo "$KB_REPO"
 wordcell search "why parser retries stop" --root "$KB_ROOT" --mode exact \
-  --history --repo "$KB_REPO" --json
+  --selected-passage --history --repo "$KB_REPO" --json
 wordcell backlinks notes/parser-contract --root "$KB_ROOT" --json
 wordcell history notes/parser-contract --root "$KB_ROOT" \
   --repo "$KB_REPO" --json
@@ -34,6 +65,9 @@ Read the inherited guides and authoritative Markdown returned by these views.
 Use the backlink to inspect related plans and use Git history as provenance,
 not as proof that the note remains correct. This workflow recovers only context
 that was persisted in files or Git; it does not reconstruct private chat.
+`wordcell context` does not list `type: session` or `type: profile` notes, so
+read them with the commands under
+[Read the profile first](#read-the-profile-first).
 
 ## Choose the retrieval lane
 
@@ -46,7 +80,7 @@ that was persisted in files or Git; it does not reconstruct private chat.
   resolve note identities before returning authored relationships.
 - A whole-vault structural question or relationship audit: use `wordcell graph --json`,
   then inspect the smallest relevant portion of its canonical output.
-- A phrase, identity, or concept expressed with different vocabulary: use `wordcell search`, whose default hybrid result preserves exact and QMD evidence separately.
+- A phrase, identity, or concept expressed with different vocabulary: use `wordcell search`, whose default hybrid result preserves exact and QMD evidence separately. Add `--selected-passage` when you will read, quote, or act on results: each hit then carries the note's best-matching excerpt with its line range and section headings.
 - Direct provenance for one note or repository path: use `wordcell history` or
   `wordcell history search` without changing authored metadata or links.
 - Recent captures awaiting maintained disposition: use the advisory `wordcell inbox` view.
@@ -62,7 +96,7 @@ wordcell backlinks "Plan title or path" --root "$KB_ROOT" --json
 wordcell links "Plan title or path" --root "$KB_ROOT" --direction both --depth 1 --limit 25 --json
 wordcell relation list "Plan title or path" --root "$KB_ROOT" --json
 wordcell graph --root "$KB_ROOT" --json
-wordcell search "why browser capture uses the current tab" --root "$KB_ROOT" --json
+wordcell search "why browser capture uses the current tab" --root "$KB_ROOT" --selected-passage --json
 wordcell search "accepted ingestion plans" --root "$KB_ROOT" --where type=plan --where status=accepted --tag ingestion --json
 wordcell search "notes/write-path" --root "$KB_ROOT" --mode exact --no-history --json
 wordcell history "notes/write-path" --root "$KB_ROOT" --repo "$KB_REPO" --json
@@ -177,6 +211,20 @@ For a repository's ordinary KB searches, prefer its approved, pinned
 choice. Read returned notes before acting; model probabilities are ranking
 signals, not proof of truth. Explicit priority rules still run last.
 
+Add `--selected-passage` to attach one source excerpt to each returned note.
+Wordcell chooses it locally, without model calls: the paragraph, or window of
+at most 512 UTF-8 bytes, that contains the most distinct query words, outside
+frontmatter. The excerpt is unedited note text with its byte offsets, line
+range, the SHA-256 of the note text, and the enclosing Markdown headings as
+separate spans. Offsets count from the start of the note text, after any
+byte-order mark. Ranking, scores, the `snippet` field, and reranker input do not
+change. A note without matching body text reports `status: "none"`; a note
+past a size limit reports `status: "unavailable"` with a reason. Both keep
+their snippet. Terminal output shows CRLF as LF and tabs as four spaces, and
+reports `display-sanitized` instead of an excerpt that credential redaction
+would alter. An excerpt shows where query words appear; it is not a verified
+answer. SDK and MCP `search` callers pass `selectedPassage: true`.
+
 `wordcell history <note>` returns the bounded commit history already associated with
 one resolved note. `wordcell history search <query-or-path>` searches the bounded Git
 projection directly and retains hashes, subjects, matched paths, co-change

package/skills/wordcell/references/session-memory.md

@@ -0,0 +1,207 @@
+# Save session memory and profiles
+
+Save what a conversation settled as an ordinary `type: session` note, link it
+to the notes it changed, and keep a maintained `type: profile` note. You write
+every note and relationship, on request or at a session close that the user or
+the vault's instructions ask for. Wordcell extracts no facts and writes no note
+on its own.
+
+## Locate the vault
+
+- Resolve `KB_ROOT` and `KB_REPO` as in [the query guide](query.md), then read
+  the vault's applicable agent instructions and note conventions.
+- Pass the resolved path to every `--root`.
+- `note create --body-file -` reads the body from standard input, and
+  `--body-file <path>` reads it from a file.
+- Write each body file outside the vault, for example under `${TMPDIR:-/tmp}`,
+  and delete it after `note create`. A Markdown file left in the vault becomes
+  a note at the next refresh.
+
+## Decide what to keep
+
+- Keep the outcome, each decision and who made it, open threads, the
+  repository paths touched, and the notes or plans the session changed.
+- Leave out the raw transcript unless the user asks for it. Also leave out tool
+  logs, secrets, credentials, and guesses nobody confirmed.
+- Quote the user only when the exact wording matters.
+- Write one session note per working session. When the same session continues,
+  update its note as described under [Update a note](#update-a-note).
+
+## Write the session note
+
+1. List recent sessions, and update the note this session continues instead of
+   creating another:
+
+```sh
+wordcell list --root "$KB_ROOT" --where type=session --sort date \
+  --order desc --limit 5 --json
+```
+
+2. Choose the ID `notes/sessions/<YYYY-MM-DD>-<topic>` and the title
+   `Session <YYYY-MM-DD>: <topic>`. When another session holds that ID, choose
+   a distinct topic or add a suffix such as `-2`, and link the earlier note with
+   `continues` when both belong to one thread. `note create` refuses an
+   existing ID whose body differs.
+3. Create the directory, because `note create` does not create directories:
+
+```sh
+mkdir -p "$KB_ROOT/notes/sessions"
+```
+
+4. Write the body file with these sections, and link each note the session
+   changed:
+
+```md
+# Session 2026-09-26: bound parser retries
+
+## Outcome
+
+- `src/parser.ts` stops after three attempts.
+- [[notes/parser-retries|Parser retries]] records the new bound.
+
+## Decisions
+
+- Three attempts, confirmed by the user.
+
+## Open threads
+
+- Whether the backoff needs jitter.
+```
+
+5. Create the note from the body file, or pipe the body with `--body-file -`:
+
+```sh
+wordcell note create notes/sessions/2026-09-26-bound-parser-retries \
+  --root "$KB_ROOT" --title "Session 2026-09-26: bound parser retries" \
+  --type session --body-file "${TMPDIR:-/tmp}/session.md"
+```
+
+6. Edit the frontmatter. Directly after `type: session`, add the date and each
+   exact repository-relative file or directory path the session touched,
+   without globs:
+
+```yaml
+type: session
+date: 2026-09-26
+repository_scopes:
+  - src/parser.ts
+```
+
+Declare at most 16 paths, with no duplicates and no two paths that differ only
+by case. A longer list gets only a check advisory, and `--scope` stops
+returning the note. When the session touched more, keep the paths a later
+reader will ask about, or declare a directory they share. `--scope` then
+matches that directory's path, not the files in it. Omit `repository_scopes`
+when the session touched no repository path.
+
+`wordcell list --scope` matches a declared path exactly, and `wordcell context`
+does not list session or profile notes, so recall them with `wordcell list` as
+[the query guide](query.md#read-the-profile-first) describes. Do not tag every
+session `session`. The type is the query surface, and a tag that every session
+shares makes percolate propose a concept note for it.
+
+Over MCP, `create_note` with `"type": "session"` takes the ID, title, and body.
+It cannot set `date` or `repository_scopes`, and it does not create
+directories. Without file access, keep the date in the title, list the paths
+under Outcome, and use `notes/session-<YYYY-MM-DD>-<topic>` when
+`notes/sessions/` is missing. Without those two fields, `--sort date` lists the
+note after every dated session and `--scope` never returns it. Add both fields
+the next time you have file access.
+
+## Update a note
+
+Update a session or profile note in one of two ways:
+
+- Edit the file, then refresh and check as described under [Finish](#finish).
+- Over MCP, call `get_note`, then `update_note_body` with the `revision` it
+  returned as `expected_revision`. On a revision conflict, call `get_note`
+  again and merge your change into the current body. When `get_note` reports
+  `truncated: true`, edit the file instead. A server started with
+  `--read-only` has no write tools.
+
+## Link the session
+
+Write each relationship from the session note. Never add the reverse edge to
+the target.
+
+```sh
+wordcell relation add notes/sessions/2026-09-26-bound-parser-retries \
+  updates notes/parser-retries --root "$KB_ROOT"
+```
+
+- `updates`: the session changed that note or plan.
+- `informed-by`: the session relied on that note without changing it.
+- `continues`: the target is an earlier session on the same thread.
+
+The MCP `add_relation` tool takes the same source, predicate, and target.
+
+## Review percolation before replacing a claim
+
+```sh
+wordcell percolate notes/sessions/2026-09-26-bound-parser-retries \
+  --root "$KB_ROOT" --limit 25 --json
+```
+
+Open the cited notes before acting on a candidate. Add `supersedes` or
+`contradicts` only when the new note's prose establishes the replacement or
+the conflict. When a maintained note is the current account, update it in place
+instead of recording a replacement.
+
+## Keep a profile note
+
+Look for existing profiles first, and read one as
+[the query guide](query.md#read-the-profile-first) describes:
+
+```sh
+wordcell list --root "$KB_ROOT" --where type=profile --json
+```
+
+Update the profile that listing returns for the person, team, or project, as
+described under [Update a note](#update-a-note). When none exists, create
+`notes/profile` for the vault owner, or `notes/profile-<entity>` for anyone
+else:
+
+```md
+# Profile
+
+## Stable
+
+- Uses Bun for tests.
+
+## Recent
+
+- 2026-09-26: capped [[notes/parser-retries|parser retries]] at three attempts
+  ([[notes/sessions/2026-09-26-bound-parser-retries]]).
+```
+
+- Put role, preferences, environment, and standing decisions under Stable.
+  Put dated items under Recent, each linking the session that established it.
+- Move a Recent item to Stable once it keeps holding. Delete items that stop
+  applying; Git keeps the history.
+- Record only what the person stated or confirmed. Ask before recording
+  sensitive personal details.
+
+Create the profile the same way as a session note:
+
+```sh
+wordcell note create notes/profile --root "$KB_ROOT" --title Profile \
+  --type profile --body-file "${TMPDIR:-/tmp}/profile.md"
+```
+
+## Finish
+
+```sh
+wordcell refresh --root "$KB_ROOT"
+wordcell check --root "$KB_ROOT" --repo "$KB_REPO"
+```
+
+- Check names an absent repository path in an advisory only for current
+  records, such as maintained notes and active plans. For session notes it only
+  counts absent paths in its `Repository scopes:` summary line, so compare that
+  count with the paths you declared. Neither changes the exit code.
+- In parallel edit lanes, run `wordcell check --root "$KB_ROOT" --no-catalog`
+  and leave the refresh to the integrating agent.
+- The MCP tools cannot run percolate, refresh, or check. Over MCP alone, add no
+  `supersedes` or `contradicts` relation, and ask the user to run
+  `wordcell refresh` and then `wordcell check` from the CLI, because an MCP
+  write leaves a managed catalog stale.

package/src/authoring-import.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal Promise facades for importers that own frontmatter fields.
+ *
+ * They match `createNote` and `updateNoteBody` in `authoring.ts`, plus the
+ * internal `fields` parameter, which the public facades do not expose. Each
+ * call enters one finite authoring runtime.
+ */
+import type {
+  AuthoringOptions,
+  CreateNoteInput,
+  FrontmatterFields,
+  FrontmatterFieldUpdates,
+  NoteAuthoringResult,
+  UpdateNoteBodyOptions,
+} from "./authoring-model.js";
+import { nativeAuthoringPlatform } from "./authoring-platform.js";
+import { createNoteProgram, updateNoteBodyProgram } from "./authoring-program.js";
+import { runAuthoring } from "./authoring-runtime.js";
+
+/** Create a note whose frontmatter also carries `fields` after `title` and `tags`. */
+export async function createNoteWithFields(
+  root: string, input: CreateNoteInput, options: AuthoringOptions, fields: FrontmatterFields,
+): Promise<NoteAuthoringResult> {
+  return runAuthoring(createNoteProgram(nativeAuthoringPlatform, root, input, options, fields));
+}
+
+/** Replace a note body and set or delete top-level `fields` in the same revision-checked write. */
+export async function updateNoteBodyWithFields(
+  root: string, id: string, body: string, options: UpdateNoteBodyOptions, fields: FrontmatterFieldUpdates,
+): Promise<NoteAuthoringResult> {
+  return runAuthoring(updateNoteBodyProgram(nativeAuthoringPlatform, root, id, body, options, fields));
+}