@folterung/project-memory 0.1.21 → 0.1.22

package/packages/cli/src/scope/architecture-anchors.ts

@@ -0,0 +1,148 @@
+import fg from "fast-glob";
+import { join } from "node:path";
+import { statSync } from "node:fs";
+
+/**
+ * Architecture anchors: deterministic path rules for tagging entrypoints, routing,
+ * DI, bootstrap, and config so they can be retrieved for system-overview queries.
+ * Two tiers: hard anchors (explicit paths, always tag) and soft anchors (broader
+ * globs restricted to allowed roots and optional file size).
+ * Binaries (pdf, images, archives, fonts, etc.) are never considered anchors.
+ */
+
+export type ArchitectureAnchorKind = "entrypoint" | "routing" | "bootstrap" | "di" | "config";
+
+/** Extensions that are never considered architecture anchors (binaries / non-code). */
+export const BINARY_EXTENSIONS = new Set([
+  "pdf", "png", "jpg", "jpeg", "gif", "ico", "webp", "svg",
+  "woff", "woff2", "ttf", "eot", "otf",
+  "zip", "tar", "gz", "rar", "7z",
+  "exe", "dll", "so", "dylib", "bin",
+]);
+
+/** Default roots under which soft anchors are allowed (reduces false positives). */
+export const DEFAULT_SOFT_ANCHOR_ROOTS = ["app/", "src/", "public/", "server/", "api/"];
+
+/** Default max file size (bytes) for soft anchors; larger files are not tagged. */
+export const DEFAULT_MAX_SOFT_ANCHOR_FILE_BYTES = 200 * 1024;
+
+export interface GetArchitectureAnchorKindOptions {
+  fileSizeBytes?: number;
+  allowedRoots?: string[];
+  maxSoftAnchorFileBytes?: number;
+}
+
+/**
+ * Returns the architecture anchor kind for a relative path, or undefined if not an anchor.
+ * Hard anchors (explicit entrypoint/wiring paths) are always tagged when matched.
+ * Soft anchors (broader patterns) are only tagged when path is under allowedRoots
+ * and (when fileSizeBytes is provided) under maxSoftAnchorFileBytes.
+ * Paths with binary extensions are never anchors.
+ */
+export function getArchitectureAnchorKind(
+  relativePath: string,
+  options?: GetArchitectureAnchorKindOptions
+): ArchitectureAnchorKind | undefined {
+  const normalized = relativePath.replace(/\\/g, "/");
+  const ext = extFromPath(normalized);
+  if (ext && BINARY_EXTENSIONS.has(ext.toLowerCase())) {
+    return undefined;
+  }
+
+  const kind = matchHardAnchor(normalized) ?? matchSoftAnchor(normalized, options);
+  return kind;
+}
+
+function extFromPath(path: string): string {
+  const i = path.lastIndexOf(".");
+  if (i === -1) return "";
+  return path.slice(i + 1);
+}
+
+/** Hard anchors: explicit, narrow paths. No size/root constraints. */
+function matchHardAnchor(normalized: string): ArchitectureAnchorKind | undefined {
+  const entrypointExts = ["ts", "tsx", "js", "jsx", "html", "php"];
+  if (pathMatches(normalized, "public/index", entrypointExts)) return "entrypoint";
+  if (pathMatches(normalized, "src/index", ["ts", "tsx", "js", "jsx"])) return "entrypoint";
+  if (pathMatches(normalized, "server/index", ["ts", "js"])) return "entrypoint";
+  if (pathMatches(normalized, "api/index", ["ts", "js"])) return "entrypoint";
+  if (pathMatches(normalized, "app/index", ["ts", "tsx", "js", "jsx", "php"])) return "entrypoint";
+
+  if (pathMatches(normalized, "app/routes", ["ts", "js"])) return "routing";
+  if (pathMatches(normalized, "app/dependencies", ["ts", "js"])) return "di";
+  if (pathMatches(normalized, "app/settings", ["ts", "js"])) return "config";
+  return undefined;
+}
+
+function pathMatches(normalized: string, prefix: string, exts: string[]): boolean {
+  for (const ext of exts) {
+    if (normalized === `${prefix}.${ext}`) return true;
+  }
+  return false;
+}
+
+/** Soft anchors: broader patterns, only under allowed roots and optional size cap. */
+function matchSoftAnchor(
+  normalized: string,
+  options?: GetArchitectureAnchorKindOptions
+): ArchitectureAnchorKind | undefined {
+  const roots = options?.allowedRoots ?? DEFAULT_SOFT_ANCHOR_ROOTS;
+  const underRoot = roots.some((r) => normalized === r.slice(0, -1) || normalized.startsWith(r));
+  if (!underRoot) return undefined;
+
+  const maxBytes = options?.maxSoftAnchorFileBytes ?? DEFAULT_MAX_SOFT_ANCHOR_FILE_BYTES;
+  if (options?.fileSizeBytes != null && options.fileSizeBytes > maxBytes) {
+    return undefined;
+  }
+
+  if (normalized.includes("/routes/") || /\/routes\.(ts|js)$/.test(normalized)) return "routing";
+  if (/\/container[\w.-]*\.(ts|js)$/.test(normalized)) return "di";
+  if (/\/di[\w.-]*\.(ts|js)$/.test(normalized)) return "di";
+  if (/\/middleware[\w.-]*\.(ts|js)$/.test(normalized)) return "bootstrap";
+  if (/\/bootstrap[\w.-]*\.(ts|js)$/.test(normalized)) return "bootstrap";
+  if (/\/config[\w.-]*\.(ts|js|yml|yaml)$/.test(normalized)) return "config";
+  if (/\/settings[\w.-]*\.(ts|js)$/.test(normalized)) return "config";
+  return undefined;
+}
+
+export interface ListArchitectureAnchorPathsOptions {
+  allowedRoots?: string[];
+  maxSoftAnchorFileBytes?: number;
+}
+
+/**
+ * Returns absolute paths of files in the repo that match architecture anchor rules.
+ * Used when allowOutsideInclude is true to merge anchor paths into eligible paths.
+ * Binary extensions are excluded; soft anchors are restricted to allowedRoots and file size.
+ */
+export function listArchitectureAnchorPaths(
+  cwd: string,
+  options?: ListArchitectureAnchorPathsOptions
+): string[] {
+  const allowedRoots = options?.allowedRoots ?? DEFAULT_SOFT_ANCHOR_ROOTS;
+  const maxBytes = options?.maxSoftAnchorFileBytes ?? DEFAULT_MAX_SOFT_ANCHOR_FILE_BYTES;
+  const files = fg.sync("**/*", {
+    cwd,
+    dot: true,
+    onlyFiles: true,
+    absolute: true,
+    suppressErrors: true,
+  });
+  const result: string[] = [];
+  for (const abs of files) {
+    const rel = abs.slice(cwd.length).replace(/^[/\\]+/, "").replace(/\\/g, "/");
+    let fileSizeBytes: number | undefined;
+    try {
+      fileSizeBytes = statSync(abs).size;
+    } catch {
+      continue;
+    }
+    const kind = getArchitectureAnchorKind(rel, {
+      fileSizeBytes,
+      allowedRoots,
+      maxSoftAnchorFileBytes: maxBytes,
+    });
+    if (kind != null) result.push(abs);
+  }
+  return result;
+}

package/packages/mcp-server/dist/system-instructions.md

@@ -22,3 +22,10 @@ You are using Project Memory as a **verification and consistency layer** and a *
 - **Pre-store memory hygiene checklist** (for session summaries): Before storing, (a) search for existing summary in same scope/topic, (b) if found prefer superseding via `supersedesId`, (c) ensure template compliance, (d) include scope if applicable.
 - **Justifications:** Every stored or updated memory entry must include a **short justification** (why it improves future correctness). Justifications are trust signals for future agents.
 - **Temporal decay:** Older or low-confidence memory is more likely to require re-verification over time (e.g. after refactors, migrations, or architectural changes). Treat such entries as candidates for re-check against the repository, not as settled fact.
+
+## Architecture and system-overview queries
+
+When answering **application architecture**, **system overview**, or **how the app is wired**:
+
+- **Retrieval:** Use `search_project_memory` with `refsOnly: true` and `intent: "navigation"`. Prefer architecture anchor kinds when available (default includes entrypoint, routing, bootstrap, di, config). De-prioritize DTOs, models, PDFs/binaries, `.git`, `vendor`, and submodule metadata. Select 5–12 high-signal refs, then call `get_project_memory_items(ids)` to expand; do not answer from refs alone.
+- **Query wording:** Favor concrete wiring terms ("entry point", "routes", "dependencies", "container", "settings", "middleware", "bootstrap", "config") instead of generic "architecture" or "system overview" to reduce irrelevant chunks.

package/packages/mcp-server/system-instructions.md

@@ -22,3 +22,10 @@ You are using Project Memory as a **verification and consistency layer** and a *
 - **Pre-store memory hygiene checklist** (for session summaries): Before storing, (a) search for existing summary in same scope/topic, (b) if found prefer superseding via `supersedesId`, (c) ensure template compliance, (d) include scope if applicable.
 - **Justifications:** Every stored or updated memory entry must include a **short justification** (why it improves future correctness). Justifications are trust signals for future agents.
 - **Temporal decay:** Older or low-confidence memory is more likely to require re-verification over time (e.g. after refactors, migrations, or architectural changes). Treat such entries as candidates for re-check against the repository, not as settled fact.
+
+## Architecture and system-overview queries
+
+When answering **application architecture**, **system overview**, or **how the app is wired**:
+
+- **Retrieval:** Use `search_project_memory` with `refsOnly: true` and `intent: "navigation"`. Prefer architecture anchor kinds when available (default includes entrypoint, routing, bootstrap, di, config). De-prioritize DTOs, models, PDFs/binaries, `.git`, `vendor`, and submodule metadata. Select 5–12 high-signal refs, then call `get_project_memory_items(ids)` to expand; do not answer from refs alone.
+- **Query wording:** Favor concrete wiring terms ("entry point", "routes", "dependencies", "container", "settings", "middleware", "bootstrap", "config") instead of generic "architecture" or "system overview" to reduce irrelevant chunks.

package/packages/server/coverage/lcov-report/api/index.html

@@ -25,7 +25,7 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>343/343</span>
+                <span class='fraction'>346/346</span>
             </div>
         
             
@@ -46,7 +46,7 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>343/343</span>
+                <span class='fraction'>346/346</span>
             </div>
         
             
@@ -99,13 +99,13 @@
 	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
 	</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="117" class="abs high">117/117</td>
+	<td data-value="120" class="abs high">120/120</td>
 	<td data-value="70.58" class="pct medium">70.58%</td>
 	<td data-value="17" class="abs medium">12/17</td>
 	<td data-value="100" class="pct high">100%</td>
 	<td data-value="2" class="abs high">2/2</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="117" class="abs high">117/117</td>
+	<td data-value="120" class="abs high">120/120</td>
 	</tr>
 
 <tr>
@@ -131,7 +131,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/api/points.ts.html

@@ -346,7 +346,7 @@ export function registerPointsRoutes(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/api/search.ts.html

@@ -25,7 +25,7 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>117/117</span>
+                <span class='fraction'>120/120</span>
             </div>
         
             
@@ -46,7 +46,7 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>117/117</span>
+                <span class='fraction'>120/120</span>
             </div>
         
             
@@ -180,7 +180,10 @@
 <a name='L115'></a><a href='#L115'>115</a>
 <a name='L116'></a><a href='#L116'>116</a>
 <a name='L117'></a><a href='#L117'>117</a>
-<a name='L118'></a><a href='#L118'>118</a></td><td class="line-coverage quiet"><span class="cline-any cline-yes">1x</span>
+<a name='L118'></a><a href='#L118'>118</a>
+<a name='L119'></a><a href='#L119'>119</a>
+<a name='L120'></a><a href='#L120'>120</a>
+<a name='L121'></a><a href='#L121'>121</a></td><td class="line-coverage quiet"><span class="cline-any cline-yes">1x</span>
 <span class="cline-any cline-yes">1x</span>
 <span class="cline-any cline-yes">1x</span>
 <span class="cline-any cline-yes">1x</span>
@@ -297,6 +300,9 @@
 <span class="cline-any cline-yes">4x</span>
 <span class="cline-any cline-yes">4x</span>
 <span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
 <span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import type { FastifyInstance } from "fastify";
 import type { QdrantClient } from "@qdrant/js-client-rest";
 import { createQdrantClient } from "../qdrant/client.js";
@@ -373,7 +379,10 @@ export function registerSearchRoutes(
         limitChunks,
       } = request.body;
       const vector = embedText(query<span class="branch-0 cbranch-no" title="branch not covered" > ?? "")</span>;
-      const chunkKinds = kinds &amp;&amp; kinds.length &gt; 0 ? kinds : ["chunk", "entrypoint", "agent_note"];
+      const chunkKinds =
+        kinds &amp;&amp; kinds.length &gt; 0
+          ? kinds
+          : ["chunk", "entrypoint", "routing", "bootstrap", "di", "config", "agent_note"];
       const chunkLimit = limitChunks ?? limit;
 &nbsp;
     const [systemMaps, moduleSummaries, chunks] = await Promise.all([
@@ -421,7 +430,7 @@ export function registerSearchRoutes(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/api/store.ts.html

@@ -472,7 +472,7 @@ export function registerStoreRoutes(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/embedding/index.html

@@ -101,7 +101,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/embedding/stub.ts.html

@@ -169,7 +169,7 @@ export function getVectorSize(): number {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/index.html

@@ -23,9 +23,9 @@
         <div class='clearfix'>
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">97.88% </span>
+                <span class="strong">97.89% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>509/520</span>
+                <span class='fraction'>512/523</span>
             </div>
         
             
@@ -44,9 +44,9 @@
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">97.88% </span>
+                <span class="strong">97.89% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>509/520</span>
+                <span class='fraction'>512/523</span>
             </div>
         
             
@@ -84,13 +84,13 @@
 	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
 	</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="343" class="abs high">343/343</td>
+	<td data-value="346" class="abs high">346/346</td>
 	<td data-value="83.87" class="pct high">83.87%</td>
 	<td data-value="62" class="abs high">52/62</td>
 	<td data-value="100" class="pct high">100%</td>
 	<td data-value="6" class="abs high">6/6</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="343" class="abs high">343/343</td>
+	<td data-value="346" class="abs high">346/346</td>
 	</tr>
 
 <tr>
@@ -131,7 +131,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/qdrant/client.ts.html

@@ -502,7 +502,7 @@ export async function retrievePointsById(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov-report/qdrant/index.html

@@ -101,7 +101,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-02-04T03:13:42.507Z
+                at 2026-02-04T03:51:00.028Z
             </div>
         <script src="../prettify.js"></script>
         <script>

package/packages/server/coverage/lcov.info

@@ -117,7 +117,7 @@ end_of_record
 TN:
 SF:src/api/search.ts
 FN:37,registerSearchRoutes
-FN:86,textForChunk
+FN:89,textForChunk
 FNF:2
 FNH:2
 FNDA:4,registerSearchRoutes
@@ -239,25 +239,28 @@ DA:114,4
 DA:115,4
 DA:116,4
 DA:117,4
-LF:117
-LH:117
+DA:118,4
+DA:119,4
+DA:120,4
+LF:120
+LH:120
 BRDA:37,0,0,4
 BRDA:42,1,0,0
 BRDA:66,2,0,4
 BRDA:76,3,0,0
-BRDA:77,4,0,1
-BRDA:77,5,0,1
-BRDA:77,6,0,3
-BRDA:86,7,0,12
-BRDA:87,8,0,3
-BRDA:87,9,0,3
-BRDA:87,10,0,9
-BRDA:90,11,0,4
-BRDA:92,12,0,0
-BRDA:95,13,0,4
-BRDA:97,14,0,0
-BRDA:100,15,0,4
-BRDA:102,16,0,0
+BRDA:78,4,0,1
+BRDA:79,5,0,1
+BRDA:80,6,0,3
+BRDA:89,7,0,12
+BRDA:90,8,0,3
+BRDA:90,9,0,3
+BRDA:90,10,0,9
+BRDA:93,11,0,4
+BRDA:95,12,0,0
+BRDA:98,13,0,4
+BRDA:100,14,0,0
+BRDA:103,15,0,4
+BRDA:105,16,0,0
 BRF:17
 BRH:12
 end_of_record
@@ -676,7 +679,7 @@ BRDA:50,5,0,8
 BRDA:59,6,0,0
 BRDA:63,7,0,4
 BRDA:73,8,0,0
-BRDA:72,9,0,10
+BRDA:72,9,0,22
 BRDA:77,10,0,3
 BRDA:78,11,0,0
 BRDA:85,12,0,0