barry-cache 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # Barry Cache
 
 <p align="center">
-  <img src="https://unpkg.com/barry-cache@latest/assets/barry-cache.png" alt="Barry Cache" width="420">
+  <img src="https://raw.githubusercontent.com/AlexanderIstomin/barry-cache/main/assets/barry-cache.png" alt="Barry Cache" width="420">
 </p>
 
 Barry Cache remembers your repo.
@@ -12,7 +12,7 @@ It creates source-backed context files for coding agents, validates them, and gi
 
 Barry Cache exists because coding agents need durable project context that is shared, reviewable, and smaller than the whole repository. Private assistant memory, ad hoc chat history, and vendor-specific instruction files drift apart; Barry keeps the source of truth in the repo and lets every agent load the same facts.
 
-The structure is intentionally layered: canonical context lives in `docs/context/`, operational continuity lives in `.context-state/`, and generated retrieval data lives in `.context-cache/`. Canonical facts stay source-backed and validated, while `route`, `search`, `load`, and `resume` project only the relevant feature pack into an agent session.
+The structure is intentionally layered: canonical context lives in `docs/context/`, operational continuity lives in `.context-state/`, and generated retrieval data lives in `.context-cache/`. Canonical facts stay source-backed and validated, while `route`, `search`, `load`, and `resume` project only the relevant feature pack into an agent session. Repeated retrieval commands reuse `.context-cache/context-index.json` when the source context file manifest is unchanged.
 
 That gives Barry three core advantages: it is agent-agnostic, because adapters point to one canonical context; auditable, because facts carry stable IDs and source references; and context-efficient, because agents start from a small routed slice instead of rereading the whole codebase.
 
@@ -150,6 +150,8 @@ It appends a JSONL handoff record to `.context-state/handoffs/handoffs.jsonl`.
 
 Use this before ending a meaningful work session so the next agent can recover what happened.
 
+`finalize` writes operational memory only. It does not update canonical project context in `docs/context/`. If a task introduced durable implementation behavior, add or update source-backed facts in `docs/context/features/*/FACTS.jsonl` and run `barry-cache validate`.
+
 Statuses:
 - `success`: the task was completed.
 - `partial`: some useful progress was made.
@@ -295,6 +297,8 @@ bun run barry -- load --route editor-media-runtime
 
 This keeps the agent from reading every context file in the repo.
 
+Barry also keeps a disposable parsed context index in `.context-cache/context-index.json`. It is keyed by the source context files and directories, so repeated `resume`, `load`, `route`, `search`, and `review --json` commands reuse parsed context until a context source file changes.
+
 If an agent ignores the repo instructions, prompt it explicitly:
 
 ```text
@@ -345,6 +349,7 @@ Rules:
 3. Put uncertain notes, blockers, and next steps in operational memory, not canonical facts.
 4. Update IDMAP.md or KG.adj only when new source IDs or relationships are needed.
 5. Run barry-cache validate before finishing.
+6. Do not claim Barry canonical memory is updated unless docs/context/ changed.
 ```
 
 The minimum useful save is:

package/dist/cli.js

@@ -263,7 +263,11 @@ function unquote(input) {
 
 // src/core/context.ts
 import { appendFile, mkdir as mkdir2 } from "node:fs/promises";
-import { basename as basename2, join as join4 } from "node:path";
+import { basename as basename2, join as join5 } from "node:path";
+
+// src/core/context-cache.ts
+import { stat as stat2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 
 // src/core/validate.ts
 import { join as join3 } from "node:path";
@@ -338,17 +342,155 @@ function validateFact(value) {
   return null;
 }
 
+// src/core/context-cache.ts
+var cacheVersion = 1;
+var contextCachePath = ".context-cache/context-index.json";
+async function readContextSnapshot(repo) {
+  const cached = await readFreshContextCache(repo);
+  if (cached)
+    return hydrateSnapshot(repo, cached);
+  const snapshot = await readContextSnapshotFromDisk(repo);
+  await writeContextCache(repo, snapshot);
+  return snapshot;
+}
+async function readFreshContextCache(repo) {
+  try {
+    const parsed = JSON.parse(await readTextIfExists(repoPath(repo, contextCachePath)));
+    if (!isContextCacheFile(parsed))
+      return null;
+    return await manifestIsFresh(repo, parsed.manifest) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function writeContextCache(repo, snapshot) {
+  const cache = {
+    version: cacheVersion,
+    generated_at: new Date().toISOString(),
+    manifest: await buildManifest(repo, snapshot),
+    features: snapshot.features.map((feature) => ({
+      ...feature,
+      dir: rel(repo, feature.dir)
+    })),
+    adrs: snapshot.adrs
+  };
+  try {
+    await writeText(repoPath(repo, contextCachePath), `${JSON.stringify(cache, null, 2)}
+`);
+  } catch {}
+}
+async function readContextSnapshotFromDisk(repo) {
+  return {
+    features: await readFeaturePacksFromDisk(repo),
+    adrs: (await readAdrCatalog(repo)).adrs
+  };
+}
+async function readFeaturePacksFromDisk(repo) {
+  const root = repoPath(repo, "docs/context/features");
+  const slugs = await listDirs(root);
+  const features = [];
+  for (const slug2 of slugs) {
+    const dir = join4(root, slug2);
+    features.push({
+      slug: slug2,
+      dir,
+      readme: await readTextIfExists(join4(dir, "README.md")),
+      idmap: await readTextIfExists(join4(dir, "IDMAP.md")),
+      graph: await readTextIfExists(join4(dir, "KG.adj")),
+      facts: await readFacts(join4(dir, "FACTS.jsonl"))
+    });
+  }
+  return features;
+}
+async function readFacts(path) {
+  const rows = (await readTextIfExists(path)).split(/\r?\n/);
+  const facts = [];
+  for (const row of rows) {
+    if (row.trim().length === 0)
+      continue;
+    const parsed = JSON.parse(row);
+    if (validateFact(parsed) === null)
+      facts.push(parsed);
+  }
+  return facts;
+}
+async function buildManifest(repo, snapshot) {
+  const paths = new Map;
+  paths.set("docs/context/features", "dir");
+  paths.set("docs/context/adrs", "dir");
+  for (const feature of snapshot.features) {
+    const dir = rel(repo, feature.dir);
+    paths.set(dir, "dir");
+    paths.set(`${dir}/README.md`, "file");
+    paths.set(`${dir}/IDMAP.md`, "file");
+    paths.set(`${dir}/KG.adj`, "file");
+    paths.set(`${dir}/FACTS.jsonl`, "file");
+  }
+  for (const adr of snapshot.adrs) {
+    paths.set(adr.path, "file");
+  }
+  const entries = [...paths.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  return await Promise.all(entries.map(([path, kind]) => statManifestEntry(repo, path, kind)));
+}
+async function manifestIsFresh(repo, manifest) {
+  for (const entry of manifest) {
+    const current = await statManifestEntry(repo, entry.path, entry.kind);
+    if (!sameManifestEntry(entry, current))
+      return false;
+  }
+  return true;
+}
+async function statManifestEntry(repo, path, kind) {
+  try {
+    const value = await stat2(repoPath(repo, path));
+    const matchesKind = kind === "dir" ? value.isDirectory() : value.isFile();
+    if (!matchesKind)
+      return { path, kind, exists: false };
+    return {
+      path,
+      kind,
+      exists: true,
+      mtimeMs: value.mtimeMs,
+      size: value.size
+    };
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { path, kind, exists: false };
+    throw error;
+  }
+}
+function sameManifestEntry(left, right) {
+  if (left.path !== right.path || left.kind !== right.kind || left.exists !== right.exists)
+    return false;
+  if (!left.exists || !right.exists)
+    return true;
+  return left.mtimeMs === right.mtimeMs && left.size === right.size;
+}
+function hydrateSnapshot(repo, cache) {
+  return {
+    features: cache.features.map((feature) => ({
+      ...feature,
+      dir: repoPath(repo, feature.dir)
+    })),
+    adrs: cache.adrs
+  };
+}
+function isContextCacheFile(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const candidate = value;
+  return candidate.version === cacheVersion && Array.isArray(candidate.manifest) && Array.isArray(candidate.features) && Array.isArray(candidate.adrs);
+}
+
 // src/core/context.ts
 async function routeTask({ repo, task }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const taskTokens = tokens(task);
   const routes = features.map((feature) => scoreFeature(feature, taskTokens, adrs)).filter((route) => route.score > 0).sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
   return { task, routes };
 }
 async function searchContext({ repo, query }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const queryTokens = tokens(query);
   const results = [];
   for (const feature of features) {
@@ -374,7 +516,7 @@ async function searchContext({ repo, query }) {
           route: feature.slug,
           score,
           text: factText,
-          source: `${rel(repo, join4(feature.dir, "FACTS.jsonl"))}#${fact.id}`
+          source: `${rel(repo, join5(feature.dir, "FACTS.jsonl"))}#${fact.id}`
         });
       }
     }
@@ -396,8 +538,7 @@ async function searchContext({ repo, query }) {
   return { query, results };
 }
 async function loadContext({ repo, route }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const feature = features.find((item) => item.slug === route) ?? null;
   if (!feature)
     return { feature: null, facts: [], sources: [], adrs: [] };
@@ -405,10 +546,10 @@ async function loadContext({ repo, route }) {
     feature,
     facts: feature.facts,
     sources: [
-      rel(repo, join4(feature.dir, "README.md")),
-      rel(repo, join4(feature.dir, "IDMAP.md")),
-      rel(repo, join4(feature.dir, "KG.adj")),
-      rel(repo, join4(feature.dir, "FACTS.jsonl"))
+      rel(repo, join5(feature.dir, "README.md")),
+      rel(repo, join5(feature.dir, "IDMAP.md")),
+      rel(repo, join5(feature.dir, "KG.adj")),
+      rel(repo, join5(feature.dir, "FACTS.jsonl"))
     ],
     adrs: linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs)
   };
@@ -432,7 +573,7 @@ async function resumeProject({ repo, task }) {
 async function finalizeProject(options) {
   const dir = repoPath(options.repo, ".context-state/handoffs");
   await mkdir2(dir, { recursive: true });
-  const path = join4(dir, "handoffs.jsonl");
+  const path = join5(dir, "handoffs.jsonl");
   const record = {
     id: `handoff-${new Date().toISOString()}`,
     updated_at: new Date().toISOString(),
@@ -445,35 +586,6 @@ async function finalizeProject(options) {
 `);
   return { saved: true, path: rel(options.repo, path), summary: options.summary };
 }
-async function readFeaturePacks(repo) {
-  const root = repoPath(repo, "docs/context/features");
-  const slugs = await listDirs(root);
-  const features = [];
-  for (const slug2 of slugs) {
-    const dir = join4(root, slug2);
-    features.push({
-      slug: slug2,
-      dir,
-      readme: await readTextIfExists(join4(dir, "README.md")),
-      idmap: await readTextIfExists(join4(dir, "IDMAP.md")),
-      graph: await readTextIfExists(join4(dir, "KG.adj")),
-      facts: await readFacts(join4(dir, "FACTS.jsonl"))
-    });
-  }
-  return features;
-}
-async function readFacts(path) {
-  const rows = (await readTextIfExists(path)).split(/\r?\n/);
-  const facts = [];
-  for (const row of rows) {
-    if (row.trim().length === 0)
-      continue;
-    const parsed = JSON.parse(row);
-    if (validateFact(parsed) === null)
-      facts.push(parsed);
-  }
-  return facts;
-}
 function scoreFeature(feature, taskTokens, adrs) {
   const linkedAdrs = linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs);
   const text = [
@@ -516,7 +628,7 @@ function firstLine(value) {
 }
 
 // src/core/import-pulpcut.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 async function importPulpcutKb(options) {
   const dryRun = options.dryRun ?? false;
   const result = {
@@ -531,19 +643,19 @@ async function importPulpcutKb(options) {
     warnings: []
   };
   const sourceDocs = repoPath(options.from, "docs");
-  const kbIndex = await readTextIfExists(join5(sourceDocs, "KB_INDEX.md"));
+  const kbIndex = await readTextIfExists(join6(sourceDocs, "KB_INDEX.md"));
   if (kbIndex.trim().length === 0) {
-    throw new Error(`PulpCut KB index not found at ${join5(sourceDocs, "KB_INDEX.md")}`);
+    throw new Error(`PulpCut KB index not found at ${join6(sourceDocs, "KB_INDEX.md")}`);
   }
   const routes = parseKbIndex(kbIndex);
   const slugs = await listDirs(sourceDocs);
   for (const slug2 of slugs) {
-    const sourceDir = join5(sourceDocs, slug2);
-    const rawFacts = await readTextIfExists(join5(sourceDir, "FACTS.jsonl"));
+    const sourceDir = join6(sourceDocs, slug2);
+    const rawFacts = await readTextIfExists(join6(sourceDir, "FACTS.jsonl"));
     if (rawFacts.trim().length === 0)
       continue;
-    const idmap = await readTextIfExists(join5(sourceDir, "IDMAP.md"));
-    const graph = await readTextIfExists(join5(sourceDir, "KG.adj"));
+    const idmap = await readTextIfExists(join6(sourceDir, "IDMAP.md"));
+    const graph = await readTextIfExists(join6(sourceDir, "KG.adj"));
     if (idmap.trim().length === 0)
       result.warnings.push(`${slug2}: missing IDMAP.md`);
     if (graph.trim().length === 0)
@@ -728,7 +840,7 @@ function stringOrStringArray(value) {
 
 // src/core/init.ts
 import { mkdir as mkdir3 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/core/templates.ts
 var managedStart = "<!-- barry-cache:start -->";
@@ -761,6 +873,8 @@ Barry Cache remembers this repo through source-backed context files.
 
 ${commandNote}
 
+Repeated retrieval commands use the disposable parsed index in \`.context-cache/context-index.json\` when source context files have not changed.
+
 Start task context with:
 
 \`\`\`bash
@@ -786,6 +900,12 @@ Before handing off substantial work, record factual evidence:
 \`\`\`bash
 ${commandPrefix} finalize --status success --summary "<summary>"
 \`\`\`
+
+Memory policy:
+
+- Finalize writes operational memory only.
+- Do not claim Barry canonical memory is updated unless \`docs/context/\` changed.
+- If a task adds durable implementation behavior, add or update source-backed facts in \`docs/context/features/*/FACTS.jsonl\` and run \`${commandPrefix} validate\`.
 `;
 }
 var indexMd = `# Context Index
@@ -849,7 +969,7 @@ Barry Cache keeps repo context source-backed, validated, and easy for agents to
 
 This directory is the canonical project memory for Barry Cache. It keeps durable implementation context in Git so humans and agents can review the same source-backed facts instead of relying on private assistant memory or stale chat history.
 
-Barry separates three concerns: \`docs/context/\` is reviewed truth, \`.context-state/\` is operational session continuity, and \`.context-cache/\` is disposable retrieval data. Use this structure to explain existing behavior, route tasks, validate facts, and resume agent work without loading the whole repo.
+Barry separates three concerns: \`docs/context/\` is reviewed truth, \`.context-state/\` is operational session continuity, and \`.context-cache/\` is disposable retrieval data. Barry stores a parsed context index in \`.context-cache/context-index.json\` and reuses it while the source context manifest is unchanged. Use this structure to explain existing behavior, route tasks, validate facts, and resume agent work without loading the whole repo.
 `;
 var adrReadmeMd = `# Architecture Decision Records
 
@@ -870,7 +990,7 @@ Barry Cache separates canonical context, operational state, and generated caches
 
 - Canonical context lives in \`docs/context/\`.
 - Operational continuity lives in \`.context-state/\`.
-- Generated retrieval data lives in \`.context-cache/\`.
+- Generated retrieval data lives in \`.context-cache/\`, including the disposable parsed context index.
 `;
 var factSchema = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -969,11 +1089,11 @@ async function initProject(options) {
   await patchAgentInstructions(repo, dryRun, result, options.agents, commandPrefix, packageManager);
   await patchGitignore(repo, dryRun, result);
   if (!dryRun) {
-    await mkdir3(join6(repo, ".context-state/work/threads"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/handoffs"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/failures"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/strategies"), { recursive: true });
-    await mkdir3(join6(repo, ".context-cache"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/work/threads"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/handoffs"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/failures"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/strategies"), { recursive: true });
+    await mkdir3(join7(repo, ".context-cache"), { recursive: true });
   }
   result.changed = result.written.length > 0 || result.updated.length > 0;
   return result;
@@ -1070,6 +1190,18 @@ Validate context changes with:
 \`\`\`bash
 ${commandPrefix} validate
 \`\`\`
+
+Before handing off substantial work, record factual evidence:
+
+\`\`\`bash
+${commandPrefix} finalize --status success --summary "<summary>"
+\`\`\`
+
+Memory policy:
+
+- Finalize writes operational memory only.
+- Do not claim Barry canonical memory is updated unless \`docs/context/\` changed.
+- If a task adds durable implementation behavior, add or update source-backed facts in \`docs/context/features/*/FACTS.jsonl\` and run \`${commandPrefix} validate\`.
 `;
 }
 function llmsTxt() {
@@ -1084,7 +1216,7 @@ function llmsTxt() {
 }
 
 // src/core/review-model.ts
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 
 // src/core/review-tree.ts
 function buildReviewTree(facts) {
@@ -1236,8 +1368,7 @@ async function buildReviewModel({ repo }) {
   const warnings = [];
   const facts = [];
   const timeline = [];
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   for (const adr of adrs)
     addAdr(graph, adr);
   for (const feature of features) {
@@ -1247,7 +1378,7 @@ async function buildReviewModel({ repo }) {
     for (const fact of feature.facts) {
       facts.push({
         route: feature.slug,
-        source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+        source: `${rel(repo, join8(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
         fact
       });
       addFact(graph, repo, feature, fact, sourceMap, adrs);
@@ -1329,7 +1460,7 @@ function addFact(graph, repo, feature, fact, sourceMap, adrs) {
     kind: "fact",
     label: fact.id,
     subtitle: `${fact.subject} ${fact.predicate} ${fact.object}`,
-    source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+    source: `${rel(repo, join8(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
     meta: {
       route: feature.slug,
       status: fact.status,
@@ -3915,7 +4046,8 @@ async function main(argv = process.argv.slice(2)) {
       case "finalize": {
         const status = optionalChoice(parsed, "status", finalizeStatuses, "success", commandUsage("finalize"));
         const summary = requiredString(parsed, "summary", commandUsage("finalize"), { status: [...finalizeStatuses] });
-        print(await finalizeProject({ repo, status, summary }), json);
+        const result = await finalizeProject({ repo, status, summary });
+        print(result, json, formatFinalizeMessage(result));
         break;
       }
       case "adr": {
@@ -4124,6 +4256,14 @@ function formatAdrList(adrs) {
   return adrs.map((adr) => `${adr.id}  ${adr.status}  ${adr.title} (${adr.path})`).join(`
 `);
 }
+function formatFinalizeMessage(result) {
+  return [
+    `Saved operational handoff to ${result.path}.`,
+    "Finalize writes operational memory only; it does not update canonical context in docs/context/.",
+    "If this task introduced durable implementation behavior, add or update docs/context/features/*/FACTS.jsonl and run barry-cache validate."
+  ].join(`
+`);
+}
 function formatInitMessage(result) {
   if (!result.dryRun) {
     const lines2 = [`Barry Cache init ${result.changed ? "changed files" : "already up to date"}.`];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barry-cache",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Barry Cache remembers your repo.",
   "type": "module",
   "bin": {
@@ -15,7 +15,6 @@
   },
   "files": [
     "dist",
-    "assets/barry-cache.png",
     "README.md"
   ],
   "engines": {
@@ -26,4 +25,4 @@
     "@types/node": "^25.8.0",
     "typescript": "^6.0.3"
   }
-}
+}