@jefuriiij/synthra 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.15.0] — 2026-07-02
+
+### Added
+
+- **Your remembered context now talks back.** Synthra's second brain was
+  write-only — decisions and gotchas went in via `context_remember` and never
+  resurfaced. Now they appear exactly where they're relevant:
+  - `graph_read` of a file (or a symbol in it) shows a `📌 Remembered for this
+    file` block with the entries linked to that file.
+  - `graph_continue` packs include `Remembered:` lines for entries matching the
+    query.
+- **Memories know when they might be wrong.** Entries linked to files are now
+  *anchored* to those files' content hashes at capture time. When the code
+  changes afterwards (tracked live by auto-reindex), every surfacing of that
+  entry — graph_read, graph_continue, context_recall — carries
+  `⚠ possibly stale — <file> changed since stored`. Old entries without anchors
+  keep working and are never flagged; the shared context-store format is
+  unchanged (additive optional field).
+
+---
+
 ## [0.14.1] — 2026-07-02
 
 ### Added

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.14.1",
+      version: "0.15.0",
       publishConfig: {
         access: "public"
       },
@@ -3882,7 +3882,8 @@ async function rememberEntry(paths, input) {
     content: input.text,
     tags: input.tags ?? [],
     files: input.files ?? [],
-    date: (/* @__PURE__ */ new Date()).toISOString()
+    date: (/* @__PURE__ */ new Date()).toISOString(),
+    ...input.anchors && input.anchors.length > 0 ? { anchors: input.anchors } : {}
   };
   await appendEntry(active.paths.contextStore, entry);
   const entries = await readEntries(active.paths.contextStore);
@@ -4184,7 +4185,7 @@ var TOOLS = [
         files: {
           type: "array",
           items: { type: "string" },
-          description: "Optional project-relative file paths this entry relates to."
+          description: "Optional project-relative file paths this entry relates to. Linked files also anchor the entry: recall flags it 'possibly stale' if they change, and graph_read of those files surfaces it automatically."
         }
       },
       required: ["text", "kind"]
@@ -4726,9 +4727,28 @@ async function graphContinue(args, ctx) {
 Files: ${retrieval.files.map((f) => f.path).join(", ") || "(none)"}
 Reason: ${retrieval.reason}
 `;
-  return textContent(`${header}
+  const remembered = matchRememberedFacts(query, retrieval.files, await safeRecallAll(ctx), ctx);
+  return textContent(`${header}${remembered}
 ${packed.text}`);
 }
+function matchRememberedFacts(query, retrievedFiles, entries, ctx) {
+  if (entries.length === 0) return "";
+  const qTokens = new Set(tokenizeQuery(query));
+  const retrievedPaths = new Set(retrievedFiles.map((f) => f.path));
+  const scored = entries.map((e) => {
+    let score2 = 0;
+    for (const t of tokenizeQuery(`${e.content} ${e.tags.join(" ")}`)) {
+      if (qTokens.has(t)) score2 += 1;
+    }
+    if (e.files.some((f) => retrievedPaths.has(f)) || e.anchors?.some((a) => retrievedPaths.has(a.path))) {
+      score2 += 2;
+    }
+    return { e, score: score2 };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score).slice(0, PACK_FACTS_MAX);
+  if (scored.length === 0) return "";
+  return `${scored.map((x) => `Remembered: ${factLine(x.e, ctx.graph).slice(2)}`).join("\n")}
+`;
+}
 function resolveFileTarget(graph, filePath) {
   const files = graph.nodes.filter((n) => n.kind === "file");
   const exact = files.find((n) => n.path === filePath);
@@ -4821,6 +4841,43 @@ function buildTestsFooter(symbol, graph) {
   if (isLikelyEntry(symbol.file)) return "";
   return "Tests: none linked to this file.";
 }
+var FACTS_MAX = 3;
+var FACTS_CONTENT_MAX = 160;
+var PACK_FACTS_MAX = 2;
+function staleAnchorPaths(entry, graph) {
+  if (!entry.anchors || entry.anchors.length === 0) return [];
+  const hashByPath = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) if (n.kind === "file") hashByPath.set(n.path, n.file_hash);
+  return entry.anchors.filter((a) => hashByPath.get(a.path) !== a.hash).map((a) => a.path);
+}
+function factLine(entry, graph) {
+  const content = entry.content.length > FACTS_CONTENT_MAX ? `${entry.content.slice(0, FACTS_CONTENT_MAX - 1)}\u2026` : entry.content;
+  const date = entry.date ? ` (${entry.date.slice(0, 10)})` : "";
+  const stale = staleAnchorPaths(entry, graph);
+  const staleNote = stale.length ? `  \u26A0 possibly stale \u2014 ${stale[0]} changed since stored` : "";
+  return `- [${entry.type}] ${content}${date}${staleNote}`;
+}
+function entryLinksFile(entry, filePath) {
+  if (entry.anchors?.some((a) => a.path === filePath)) return true;
+  return entry.files.some((f) => f === filePath || filePath.endsWith(`/${f}`));
+}
+function buildFactsFooter(filePath, entries, graph) {
+  const linked = entries.filter((e) => entryLinksFile(e, filePath));
+  if (linked.length === 0) return "";
+  const newestFirst = linked.slice().reverse();
+  const shown = newestFirst.slice(0, FACTS_MAX);
+  const omitted = newestFirst.length - shown.length;
+  const lines = ["\u{1F4CC} Remembered for this file:", ...shown.map((e) => factLine(e, graph))];
+  if (omitted > 0) lines.push(`\u2026+${omitted} more \u2014 mcp__synthra__context_recall()`);
+  return lines.join("\n");
+}
+async function safeRecallAll(ctx) {
+  try {
+    return (await recallEntries(ctx.paths, {})).entries;
+  } catch {
+    return [];
+  }
+}
 async function graphRead(args, ctx) {
   const target = typeof args?.target === "string" ? args.target : "";
   if (!target) return errorContent("graph_read: 'target' (string) is required");
@@ -4839,10 +4896,15 @@ async function graphRead(args, ctx) {
   }
   const fileNode = resolved.node;
   await logAccess(ctx, { ts: nowIso(), path: fileNode.path, source: "read" });
+  const facts = buildFactsFooter(fileNode.path, await safeRecallAll(ctx), ctx.graph);
+  const factsBlock = facts ? `
+
+---
+${facts}` : "";
   if (!symbolName) {
     return textContent(`# ${fileNode.path}
 
-${fileNode.content}`);
+${fileNode.content}${factsBlock}`);
   }
   const cleanSym = symbolName.trim();
   const symbol = ctx.graph.nodes.find(
@@ -4872,7 +4934,7 @@ ${tests}` : "";
   return textContent(
     `# ${fileNode.path}::${symbol.name}  (L${symbol.start_line}-${symbol.end_line})
 
-${body}${depsBlock}${testsBlock}${editHint}`
+${body}${depsBlock}${testsBlock}${factsBlock}${editHint}`
   );
 }
 var editedFiles = /* @__PURE__ */ new Set();
@@ -4907,16 +4969,26 @@ async function contextRemember(args, ctx) {
   }
   const tags = Array.isArray(args?.tags) ? args.tags.filter((t) => typeof t === "string") : [];
   const files = Array.isArray(args?.files) ? args.files.filter((f) => typeof f === "string") : [];
+  const anchors = [];
+  for (const f of files) {
+    const resolved = resolveFileTarget(ctx.graph, f);
+    if ("node" in resolved) {
+      anchors.push({ path: resolved.node.path, hash: resolved.node.file_hash });
+    }
+  }
   const result = await rememberEntry(ctx.paths, {
     text,
     kind: kindRaw,
     tags,
-    files
+    files,
+    anchors
   });
+  const anchorNote = anchors.length ? `
+Anchored to ${anchors.length} file(s) \u2014 recall will flag this entry if they change.` : "";
   return textContent(
     `Remembered ${result.entry.type} on branch '${result.branch}'.
 Stored: ${result.storePath}
-CONTEXT.md refreshed: ${result.contextMdPath}`
+CONTEXT.md refreshed: ${result.contextMdPath}${anchorNote}`
   );
 }
 var DEFAULT_RECENT_WINDOW_MS = 60 * 60 * 1e3;
@@ -4951,7 +5023,9 @@ async function contextRecall(args, ctx) {
   const lines = [`# Context entries \u2014 branch: ${result.branch}`, ""];
   for (const e of result.entries) {
     const tags = e.tags.length ? ` [${e.tags.join(", ")}]` : "";
-    lines.push(`- **${e.type}**${tags} (${e.date}): ${e.content}`);
+    const stale = staleAnchorPaths(e, ctx.graph);
+    const staleNote = stale.length ? `  \u26A0 possibly stale \u2014 ${stale.join(", ")} changed since stored` : "";
+    lines.push(`- **${e.type}**${tags} (${e.date}): ${e.content}${staleNote}`);
     if (e.files.length) lines.push(`  files: ${e.files.join(", ")}`);
   }
   return textContent(lines.join("\n"));