pi-weave 0.2.3 → 0.2.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-weave",
-  "version": "0.2.3",
-  "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
+  "version": "0.2.4",
+  "description": "Local-first Markdown memory and knowledge graph for Pi: preserve decisions, recall across sessions, and explore notes with code.",
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
@@ -9,10 +9,16 @@
   },
   "keywords": [
     "pi-package",
-    "knowledge-graph",
-    "agent",
+    "pi-coding-agent",
+    "agent-memory",
+    "persistent-memory",
+    "markdown",
     "notepad",
-    "repository-index"
+    "local-first",
+    "knowledge-graph",
+    "codebase-memory",
+    "obsidian",
+    "developer-tools"
   ],
   "license": "MIT",
   "author": "Eran Yonai <yonai.eran@gmail.com>",
@@ -50,6 +56,7 @@
     "build:web": "node scripts/build-web.mjs",
     "build:web:check": "node scripts/build-web.mjs --check",
     "check": "npm run typecheck && npm run build:web:check && npm run coverage",
+    "eval:notepad": "node scripts/eval-notepad-search.mjs",
     "rewrap:md": "node scripts/rewrap-md.mjs",
     "rewrap:md:check": "node scripts/rewrap-md.mjs --check",
     "prepublishOnly": "npm run check"

package/skills/weave-notepad/SKILL.md

@@ -114,8 +114,19 @@ The scan is opt-in and never runs on its own. Suggest it when the user asks why
 
 ## 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
-repository for facts about code and flag the discrepancy — the note may be stale intent.
+When the slug is known, use `weave_note` action=get directly. Otherwise use one targeted `search` with the user's key terms. A search with
+one result or one unique exact-title match returns the full note; that result is sufficient, so do not call `get` again. If several
+plausible candidates remain, fetch at most the three strongest slugs together in the next tool round. If the answer is still ambiguous,
+ask the user for another identifier instead of reformulating and repeating the search. Never list the vault to find a note.
+
+Search accepts ordinary multi-term queries and automatically falls back from an exact phrase to ranked lexical terms. Results are
+strongest-first and include match evidence, metadata, bounded note content, and connected notes found through links, backlinks, shared
+tags, and shared distinctive terms. A body marked `complete` is sufficient; call `get` only for content explicitly marked as an excerpt.
+Use that context before making another tool call. Connected notes are discovery context, not evidence that they match the query; include
+them in an answer only when their stated relationship is relevant. Connections are lexical and explicit, not semantic.
+
+When a note and the repository index disagree, trust the repository for facts about code and flag the discrepancy — the note may be stale
+intent.
 
 ## Repairing stale links
 

package/src/core/index.ts

@@ -64,8 +64,10 @@ export {
   type LinkRepairResult,
 } from "./vault";
 export {
+  relatedNotes,
   suggestLinks,
   type LinkSuggestion,
+  type RelatedNote,
   type SuggestOptions,
   type SuggestionReport,
 } from "./links/similar";

package/src/core/links/similar.ts

@@ -87,8 +87,9 @@ export interface SuggestOptions {
   evidence?: number;
 }
 
-/** Words too structural to carry meaning in any vault, in any domain. */
 const TERM_RE = /[\p{L}][\p{L}\p{N}_-]{2,}/gu;
+/** Link prose too structural to connect otherwise unrelated notes. */
+const STRUCTURAL_TERMS = new Set(["and", "see", "the"]);
 
 /**
  * Smallest document-frequency ceiling, whatever `maxDocFrequency` computes.
@@ -114,7 +115,10 @@ export const MIN_TERM_CEILING = 10;
 function terms(note: Pick<Note, "title" | "tags" | "body">): Set<string> {
   const text = `${note.title} ${note.tags.join(" ")} ${note.body}`;
   const out = new Set<string>();
-  for (const match of text.matchAll(TERM_RE)) out.add(match[0].toLowerCase());
+  for (const match of text.matchAll(TERM_RE)) {
+    const term = match[0].toLowerCase();
+    if (!STRUCTURAL_TERMS.has(term)) out.add(term);
+  }
   return out;
 }
 
@@ -123,6 +127,49 @@ export interface SuggestInput {
   notes: readonly Pick<Note, "slug" | "title" | "tags" | "body">[];
 }
 
+/** One deterministic neighbour of a note, with reviewable evidence. */
+export interface RelatedNote {
+  slug: string;
+  score: number;
+  reasons: string[];
+}
+
+function resolvedLinks(notes: SuggestInput["notes"]): {
+  pairs: Set<string>;
+  outgoing: Map<string, Set<string>>;
+} {
+  const pairs = new Set<string>();
+  const outgoing = new Map<string, Set<string>>();
+  const bySlug = new Set(notes.map((note) => note.slug));
+  const byBasename = new Map<string, string[]>();
+  const byTitle = new Map<string, string[]>();
+  for (const note of notes) {
+    const base = note.slug.split("/").pop()!;
+    byBasename.set(base, [...(byBasename.get(base) ?? []), note.slug]);
+    const title = slugify(note.title);
+    if (title.length > 0) byTitle.set(title, [...(byTitle.get(title) ?? []), note.slug]);
+  }
+  for (const note of notes) {
+    for (const link of scanLinks(note.body)) {
+      const byBase = byBasename.get(link.target) ?? [];
+      const byTtl = byTitle.get(link.target) ?? [];
+      const target = bySlug.has(link.target)
+        ? link.target
+        : byBase.length === 1
+          ? byBase[0]!
+          : byTtl.length === 1
+            ? byTtl[0]!
+            : null;
+      if (target === null) continue;
+      pairs.add(pairKey(note.slug, target));
+      const targets = outgoing.get(note.slug);
+      if (targets) targets.add(target);
+      else outgoing.set(note.slug, new Set([target]));
+    }
+  }
+  return { pairs, outgoing };
+}
+
 /**
  * Rank pairs of notes that share distinctive vocabulary but no link.
  *
@@ -175,34 +222,7 @@ export function suggestLinks(input: SuggestInput, options: SuggestOptions = {}):
 
   // Existing links, both directions, so a connection the user already made
   // is never offered back to them.
-  const linked = new Set<string>();
-  const bySlug = new Set(notes.map((note) => note.slug));
-  const byBasename = new Map<string, string[]>();
-  const byTitle = new Map<string, string[]>();
-  for (const note of notes) {
-    const base = note.slug.split("/").pop()!;
-    byBasename.set(base, [...(byBasename.get(base) ?? []), note.slug]);
-    const title = slugify(note.title);
-    if (title.length > 0) byTitle.set(title, [...(byTitle.get(title) ?? []), note.slug]);
-  }
-  for (const note of notes) {
-    for (const link of scanLinks(note.body)) {
-      // The same three-rung ladder `auditLinks` walks — exact slug, unique
-      // basename, unique title. It has to be all three: a link repair would
-      // resolve counts as a connection that already exists, so resolving a
-      // rung short here would suggest a pair the vault has already linked.
-      const byBase = byBasename.get(link.target) ?? [];
-      const byTtl = byTitle.get(link.target) ?? [];
-      const target = bySlug.has(link.target)
-        ? link.target
-        : byBase.length === 1
-          ? byBase[0]!
-          : byTtl.length === 1
-            ? byTtl[0]!
-            : null;
-      if (target !== null) linked.add(pairKey(note.slug, target));
-    }
-  }
+  const { pairs: linked } = resolvedLinks(notes);
 
   // Candidate generation through an inverted index on distinctive terms
   // only. Comparing every pair is O(n²) and mostly compares notes with
@@ -252,6 +272,53 @@ export function suggestLinks(input: SuggestInput, options: SuggestOptions = {}):
   return { considered: vectors.size, suggestions: suggestions.slice(0, limit) };
 }
 
+/**
+ * Rank the explicit and lexical neighbours of one note.
+ *
+ * This is deliberately not semantic search: every result cites a link,
+ * backlink, shared tag, or shared term already present in the vault.
+ */
+export function relatedNotes(input: SuggestInput, slug: string, limit = 20): RelatedNote[] {
+  if (limit <= 0) return [];
+  const focus = input.notes.find((note) => note.slug === slug);
+  if (!focus) return [];
+
+  const related = new Map<string, RelatedNote>();
+  const add = (target: string, score: number, reason: string) => {
+    if (target === slug) return;
+    const existing = related.get(target);
+    if (existing) {
+      existing.score = Math.max(existing.score, score);
+      if (!existing.reasons.includes(reason)) existing.reasons.push(reason);
+    } else {
+      related.set(target, { slug: target, score, reasons: [reason] });
+    }
+  };
+
+  const { outgoing } = resolvedLinks(input.notes);
+  for (const target of outgoing.get(slug) ?? []) add(target, 400, `linked from ${slug}`);
+  for (const [source, targets] of outgoing) {
+    if (targets.has(slug)) add(source, 400, `links to ${slug}`);
+  }
+
+  const focusTags = new Map(focus.tags.map((tag) => [tag.toLowerCase(), tag]));
+  for (const note of input.notes) {
+    const shared = [...new Set(note.tags.map((tag) => tag.toLowerCase()))]
+      .filter((tag) => focusTags.has(tag))
+      .map((tag) => focusTags.get(tag)!);
+    if (shared.length > 0) add(note.slug, 300 + shared.length, `shared tags: ${shared.join(", ")}`);
+  }
+
+  for (const suggestion of suggestLinks(input, { slug, limit: Math.max(limit, 20) }).suggestions) {
+    const target = suggestion.a === slug ? suggestion.b : suggestion.a;
+    add(target, 200 + suggestion.score, `shared terms: ${suggestion.shared.join(", ")}`);
+  }
+
+  return [...related.values()]
+    .sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug))
+    .slice(0, limit);
+}
+
 /** Order-independent key for an unordered pair. */
 function pairKey(a: string, b: string): string {
   return a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;

package/src/core/vault.ts

@@ -978,21 +978,51 @@ export async function noteCount(root: string): Promise<number> {
   return (await listNoteFiles(root)).filter(isMarkdown).length;
 }
 
+const SEARCH_TERM_RE = /[\p{L}\p{N}]+(?:[._/:\-][\p{L}\p{N}]+)*/gu;
+
+/** Terms models naturally put in a search query, including code-ish tokens. */
+function searchTerms(value: string): string[] {
+  const terms = new Set<string>();
+  for (const match of value.toLowerCase().matchAll(SEARCH_TERM_RE)) {
+    const term = match[0];
+    if (term.length > 1) terms.add(term);
+    for (const part of term.split(/[._/:\-]+/)) {
+      if (part.length > 1) terms.add(part);
+    }
+  }
+  return [...terms];
+}
+
+function matchingTerm(terms: ReadonlySet<string>, query: string): string | undefined {
+  if (terms.has(query)) return query;
+  if (query.length < 5 || !/^\p{L}+$/u.test(query)) return undefined;
+  // ponytail: cheap inflection tolerance; use stemming only if false matches become measurable.
+  const prefix = query.slice(0, 4);
+  return [...terms].find((term) => term.length >= 5 && /^\p{L}+$/u.test(term) && term.startsWith(prefix));
+}
+
 /**
- * Substring search over title, tags, and body.
- * Score: title match = 3, tag match = 2, body match = 1 each (capped).
- * Case-insensitive. Deterministic ordering: score desc, then slug asc.
+ * Search slug, title, tags, and body.
+ *
+ * Exact substring behaviour stays first and unchanged. When a natural
+ * multi-term query has no literal match, an IDF-weighted lexical fallback
+ * ranks notes by term coverage: title/slug above tags above body. This makes
+ * one model-style query useful without adding a second search mode.
  */
 export async function searchNotes(root: string, query: string): Promise<NoteSearchHit[]> {
   const q = query.toLowerCase().trim();
   if (q.length === 0) return [];
 
+  const notes = (await readVault(root)).notes;
   const hits: NoteSearchHit[] = [];
   // One pass: `listNotes` + a `getNote` per slug would read every file twice.
-  for (const note of (await readVault(root)).notes) {
+  for (const note of notes) {
     let score = 0;
-    if (note.title.toLowerCase().includes(q)) score += 3;
-    if (note.tags.some((t) => t.toLowerCase().includes(q))) score += 2;
+    const title = note.title.toLowerCase();
+    const slug = note.slug.toLowerCase();
+    if (title === q || slug === q) score += 100;
+    else if (title.includes(q) || slug.includes(q)) score += 30;
+    if (note.tags.some((t) => t.toLowerCase().includes(q))) score += 20;
 
     const bodyLower = note.body.toLowerCase();
     let bodyMatches = 0;
@@ -1006,6 +1036,48 @@ export async function searchNotes(root: string, query: string): Promise<NoteSear
     if (score === 0) continue;
     hits.push({ summary: summarizeNote(note), score, snippet: makeSnippet(note.body, q) });
   }
+  if (hits.length > 0) return hits.sort((a, b) => b.score - a.score || a.summary.slug.localeCompare(b.summary.slug));
+
+  const indexed = notes.map((note) => {
+    const title = new Set(searchTerms(note.title));
+    const slug = new Set(searchTerms(note.slug));
+    const tags = new Set(note.tags.flatMap(searchTerms));
+    const body = new Set(searchTerms(note.body));
+    return { note, title, slug, tags, body, all: new Set([...title, ...slug, ...tags, ...body]) };
+  });
+  const terms = searchTerms(q).flatMap((term) => {
+    const frequency = indexed.filter((entry) => matchingTerm(entry.all, term) !== undefined).length;
+    return frequency === 0 ? [] : [{ term, frequency }];
+  });
+  if (terms.length === 0) return [];
+
+  for (const entry of indexed) {
+    let score = 0;
+    let matched = 0;
+    let snippetTerm = "";
+    for (const { term, frequency } of terms) {
+      const idf = Math.log((indexed.length + 1) / (frequency + 1)) + 1;
+      const bodyTerm = matchingTerm(entry.body, term);
+      const fieldScore = matchingTerm(entry.title, term) !== undefined || matchingTerm(entry.slug, term) !== undefined
+        ? 30
+        : matchingTerm(entry.tags, term) !== undefined
+          ? 20
+          : bodyTerm !== undefined
+            ? 5
+            : 0;
+      if (fieldScore === 0) continue;
+      score += fieldScore * idf;
+      matched++;
+      if (snippetTerm === "" && bodyTerm !== undefined) snippetTerm = bodyTerm;
+    }
+    if (matched === 0) continue;
+    score += 20 * matched / terms.length;
+    hits.push({
+      summary: summarizeNote(entry.note),
+      score,
+      snippet: makeSnippet(entry.note.body, snippetTerm || q),
+    });
+  }
   return hits.sort((a, b) => b.score - a.score || a.summary.slug.localeCompare(b.summary.slug));
 }
 

package/src/pi/tools/noteTool.ts

@@ -12,6 +12,7 @@ import {
   getNote,
   listNotes,
   NOTES_DIR,
+  relatedNotes,
   repairVaultLinks,
   resolveNotePath,
   withMutationQueue,
@@ -20,8 +21,10 @@ import {
   suggestLinks,
   readVault,
   type LinkRepairResult,
+  type RelatedNote,
   type SuggestionReport,
 } from "../../core";
+import type { Note, NoteSearchHit } from "../../core/types";
 
 /** Cap on how many rows of each link-audit category get printed. */
 const LINK_REPORT_CAP = 20;
@@ -29,6 +32,12 @@ const LINK_REPORT_CAP = 20;
 /** Cap on notes printed by `list`; `details.notes` still carries them all. */
 const LIST_CAP = 50;
 
+/** Keep search useful without flooding the model on a broad query. */
+const SEARCH_REPORT_CAP = 10;
+const RELATED_REPORT_CAP = 5;
+const COMPLETE_BODY_CAP = 2_000;
+const COMPLETE_BODY_RESULTS = 3;
+
 function capped<T>(items: readonly T[], render: (item: T) => string): string[] {
   const lines = items.slice(0, LINK_REPORT_CAP).map(render);
   if (items.length > LINK_REPORT_CAP) lines.push(`  … and ${items.length - LINK_REPORT_CAP} more`);
@@ -63,6 +72,77 @@ function formatSuggestions(report: SuggestionReport, focus: string | undefined):
   ].join("\n");
 }
 
+function searchReasons(hit: NoteSearchHit, query: string): string[] {
+  const q = query.trim().toLowerCase();
+  const title = hit.summary.title.toLowerCase();
+  const slug = hit.summary.slug.toLowerCase();
+  const reasons: string[] = [];
+  if (title === q) reasons.push("exact title");
+  else if (slug === q) reasons.push("exact slug");
+  else if (title.includes(q)) reasons.push("title");
+  else if (slug.includes(q)) reasons.push("slug");
+  const tags = hit.summary.tags.filter((tag) => tag.toLowerCase().includes(q));
+  if (tags.length > 0) reasons.push(`tags: ${tags.join(", ")}`);
+  if (hit.snippet.toLowerCase().includes(q)) reasons.push("body");
+  if (reasons.length === 0) {
+    const haystack = `${title} ${slug} ${hit.summary.tags.join(" ").toLowerCase()} ${hit.snippet.toLowerCase()}`;
+    const terms = [...new Set(q.match(/[\p{L}\p{N}_-]{2,}/gu) ?? [])].filter((term) => haystack.includes(term));
+    if (terms.length > 0) reasons.push(`query terms: ${terms.join(", ")}`);
+  }
+  return reasons;
+}
+
+function searchContent(note: Note | undefined, snippet: string, complete: boolean): string {
+  const body = note?.body.trim() ?? "";
+  if (complete && body.length <= COMPLETE_BODY_CAP) return `[complete body]\n  ${body}`;
+  return `[excerpt${body.length > COMPLETE_BODY_CAP ? "; use get for the full note" : ""}]\n  ${snippet}`;
+}
+
+function formatSearchHits(
+  hits: readonly NoteSearchHit[],
+  query: string,
+  relations: ReadonlyMap<string, RelatedNote>,
+  notes: ReadonlyMap<string, Note>,
+): string {
+  const shown = hits.slice(0, SEARCH_REPORT_CAP);
+  const lines = shown.map((hit, index) => {
+    const tags = hit.summary.tags.length > 0 ? `; tags: ${hit.summary.tags.join(", ")}` : "";
+    const relation = relations.get(hit.summary.slug);
+    const connected = relation ? `; connected: ${relation.reasons.join("; ")}` : "";
+    const content = searchContent(notes.get(hit.summary.slug), hit.snippet, index < COMPLETE_BODY_RESULTS);
+    return `- ${hit.summary.slug}: ${hit.summary.title}\n  matched: ${searchReasons(hit, query).join(", ")}${connected}; source: ${hit.summary.source}; updated: ${hit.summary.updated}${tags}\n  ${content}`;
+  });
+  if (hits.length > shown.length) lines.push(`… and ${hits.length - shown.length} more direct match(es).`);
+  return lines.join("\n");
+}
+
+function preview(body: string): string {
+  const flat = body.trim().replace(/\s+/g, " ");
+  return flat.length > 180 ? `${flat.slice(0, 180)}…` : flat;
+}
+
+function formatRelatedNotes(
+  relations: readonly RelatedNote[],
+  notes: ReadonlyMap<string, Note>,
+  direct: ReadonlySet<string>,
+  anchor: Note,
+): string {
+  const shown = relations
+    .filter((relation) => !direct.has(relation.slug))
+    .flatMap((relation) => {
+      const note = notes.get(relation.slug);
+      return note ? [{ relation, note }] : [];
+    })
+    .slice(0, RELATED_REPORT_CAP);
+  if (shown.length === 0) return "";
+  const lines = shown.map(({ relation, note }, index) => {
+    const tags = note.tags.length > 0 ? `; tags: ${note.tags.join(", ")}` : "";
+    const content = searchContent(note, preview(note.body), index < COMPLETE_BODY_RESULTS);
+    return `- ${note.slug}: ${note.title}\n  connected: ${relation.reasons.join("; ")}; source: ${note.source}; updated: ${note.updated}${tags}\n  ${content}`;
+  });
+  return `Connected notes to '${anchor.title}' (discovery context only — not direct query matches or evidence about the query):\n${lines.join("\n")}`;
+}
+
 /** Render a link audit (and any repair) as the text the model reads. */
 function formatLinkReport(result: LinkRepairResult, applied: boolean): string {
   const { audit } = result;
@@ -120,14 +200,14 @@ export function registerNoteTool(pi: ExtensionAPI): void {
       "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
       "of Markdown notes. Actions: list (all notes — avoid on large vaults, prefer search), get (one note by slug), add (new note), " +
       "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail), " +
-      "finalize (restructure a note above its raw tail), search (title/tags/body), " +
+      "finalize (restructure a note above its raw tail), search (ranked slug/title/tags/body matches plus linked, tagged, and lexically related notes; returns the full note when one result or one exact identity resolves), " +
       "links (audit stale [[wiki-links]]; fix=true repairs the unambiguous ones), " +
       "suggest (rank unlinked notes that share distinctive vocabulary; reports only, never writes). " +
       "Use it to remember decisions, facts, and user preferences across sessions.",
     promptSnippet: "Remember and retrieve durable knowledge in the pi-weave vault",
     promptGuidelines: [
       "Use weave_note to store durable knowledge (decisions, preferences, key facts) that should survive the session, marking source as agent-written knowledge.",
-      "Use weave_note with action=search before answering questions about past decisions, people, or projects; generated notes under sessions/ carry takeaways from earlier sessions.",
+      "Use weave_note with action=get when the slug is known; otherwise use one targeted action=search before answering questions about past decisions, people, or projects. A resolved search already contains the full note; do not fetch it again or retry with reformulated queries.",
       "Use weave_note with action=links to find and repair stale [[wiki-links]] deterministically instead of rereading the vault to reconnect notes by hand; add fix=true to apply the unambiguous repairs.",
       "Use weave_note with action=suggest to discover notes that belong together but are not linked (optionally scoped to one slug); it only reports — propose the links to the user rather than writing them.",
     ],
@@ -280,12 +360,43 @@ export function registerNoteTool(pi: ExtensionAPI): void {
               details: { action: "search", hits: [] },
             };
           }
-          const lines = hits.map(
-            (h) => `- ${h.summary.slug}: ${h.summary.title} (score ${h.score})\n  ${h.snippet}`,
+          const { notes } = await readVault(vault);
+          const bySlug = new Map(notes.map((note) => [note.slug, note]));
+          const direct = new Set(hits.map((hit) => hit.summary.slug));
+          const anchor = bySlug.get(hits[0]!.summary.slug);
+          const related = anchor ? relatedNotes({ notes }, anchor.slug) : [];
+          const relatedBySlug = new Map(related.map((relation) => [relation.slug, relation]));
+          const connected = anchor ? formatRelatedNotes(related, bySlug, direct, anchor) : "";
+          const query = params.query.trim().toLowerCase();
+          const exact = hits.filter((hit) =>
+            hit.summary.title.trim().toLowerCase() === query || hit.summary.slug.toLowerCase() === query
           );
+          const resolved = hits.length === 1 ? hits[0] : exact.length === 1 ? exact[0] : undefined;
+          if (resolved) {
+            const note = bySlug.get(resolved.summary.slug);
+            if (note) {
+              const others = hits.filter((hit) => hit.summary.slug !== note.slug);
+              const otherMatches = others.length > 0
+                ? `Other direct matches (${others.length}):\n${formatSearchHits(others, params.query, relatedBySlug, bySlug)}`
+                : "";
+              return {
+                content: [{
+                  type: "text",
+                  text: [formatNote(note).trimEnd(), otherMatches, connected].filter(Boolean).join("\n\n") + "\n",
+                }],
+                details: { action: "search", hits, resolved: note, related },
+              };
+            }
+          }
           return {
-            content: [{ type: "text", text: `${hits.length} hit(s) for '${params.query}':\n${lines.join("\n")}` }],
-            details: { action: "search", hits },
+            content: [{
+              type: "text",
+              text: [
+                `${hits.length} direct match(es) for '${params.query}', strongest first:\n${formatSearchHits(hits, params.query, relatedBySlug, bySlug)}`,
+                connected,
+              ].filter(Boolean).join("\n\n"),
+            }],
+            details: { action: "search", hits, related },
           };
         }