threadwell 0.0.0 → 0.0.2

package/dist/core/memory/memory-anchors.js

@@ -0,0 +1,35 @@
+export function createMemoryAnchor(kind, id, label, path) {
+    return { kind, id, label, path };
+}
+export function serializeMemoryAnchors(anchors) {
+    return JSON.stringify(anchors);
+}
+export function parseMemoryAnchors(value) {
+    if (!value)
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.flatMap((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return [];
+            const record = entry;
+            if (typeof record.kind !== "string" || typeof record.id !== "string" || typeof record.label !== "string") {
+                return [];
+            }
+            return [
+                {
+                    kind: record.kind,
+                    id: record.id,
+                    label: record.label,
+                    path: typeof record.path === "string" ? record.path : undefined,
+                },
+            ];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=memory-anchors.js.map

package/dist/core/memory/memory-anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-anchors.js","sourceRoot":"","sources":["../../../src/core/memory/memory-anchors.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,kBAAkB,CAAC,IAAsB,EAAE,EAAU,EAAE,KAAa,EAAE,IAAa,EAAgB;IAClH,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAAA,CACjC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAgC,EAAU;IAChF,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AAAA,CAC/B;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAyB,EAAkB;IAC7E,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAY,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,EAAE,CAAC;YAC3D,MAAM,MAAM,GAAG,KAAgC,CAAC;YAChD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC1G,OAAO,EAAE,CAAC;YACX,CAAC;YACD,OAAO;gBACN;oBACC,IAAI,EAAE,MAAM,CAAC,IAAwB;oBACrC,EAAE,EAAE,MAAM,CAAC,EAAE;oBACb,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;iBAC/D;aACD,CAAC;QAAA,CACF,CAAC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AAAA,CACD","sourcesContent":["export type MemoryAnchorKind = \"memory_event\" | \"context_term\" | \"adr\" | \"queue_item\" | \"file\" | \"validation\";\n\nexport interface MemoryAnchor {\n\tkind: MemoryAnchorKind;\n\tid: string;\n\tlabel: string;\n\tpath?: string;\n}\n\nexport function createMemoryAnchor(kind: MemoryAnchorKind, id: string, label: string, path?: string): MemoryAnchor {\n\treturn { kind, id, label, path };\n}\n\nexport function serializeMemoryAnchors(anchors: readonly MemoryAnchor[]): string {\n\treturn JSON.stringify(anchors);\n}\n\nexport function parseMemoryAnchors(value: string | undefined): MemoryAnchor[] {\n\tif (!value) return [];\n\ttry {\n\t\tconst parsed = JSON.parse(value) as unknown;\n\t\tif (!Array.isArray(parsed)) return [];\n\t\treturn parsed.flatMap((entry) => {\n\t\t\tif (typeof entry !== \"object\" || entry === null) return [];\n\t\t\tconst record = entry as Record<string, unknown>;\n\t\t\tif (typeof record.kind !== \"string\" || typeof record.id !== \"string\" || typeof record.label !== \"string\") {\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\treturn [\n\t\t\t\t{\n\t\t\t\t\tkind: record.kind as MemoryAnchorKind,\n\t\t\t\t\tid: record.id,\n\t\t\t\t\tlabel: record.label,\n\t\t\t\t\tpath: typeof record.path === \"string\" ? record.path : undefined,\n\t\t\t\t},\n\t\t\t];\n\t\t});\n\t} catch {\n\t\treturn [];\n\t}\n}\n"]}

package/dist/core/memory/memory-identity.d.ts

@@ -0,0 +1,11 @@
+import type { Model } from "@threadwell/ai";
+import type { MemorySessionIdentity } from "./memory-types.js";
+export declare function normalizeMemoryPath(path: string): string;
+export declare function createProjectId(cwd: string): string;
+export declare function createMemorySessionIdentity(options: {
+    cwd: string;
+    sessionId?: string;
+    continuitySessionId?: string;
+    model?: Model<any>;
+}): MemorySessionIdentity;
+//# sourceMappingURL=memory-identity.d.ts.map

package/dist/core/memory/memory-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-identity.d.ts","sourceRoot":"","sources":["../../../src/core/memory/memory-identity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;CACnB,GAAG,qBAAqB,CASxB","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { resolve } from \"node:path\";\nimport type { Model } from \"@threadwell/ai\";\nimport type { MemorySessionIdentity } from \"./memory-types.js\";\n\nexport function normalizeMemoryPath(path: string): string {\n\treturn resolve(path).replaceAll(\"\\\\\", \"/\").toLowerCase();\n}\n\nexport function createProjectId(cwd: string): string {\n\treturn createHash(\"sha256\").update(normalizeMemoryPath(cwd)).digest(\"hex\").slice(0, 16);\n}\n\nexport function createMemorySessionIdentity(options: {\n\tcwd: string;\n\tsessionId?: string;\n\tcontinuitySessionId?: string;\n\tmodel?: Model<any>;\n}): MemorySessionIdentity {\n\treturn {\n\t\tcwd: options.cwd,\n\t\tprojectId: createProjectId(options.cwd),\n\t\tsessionId: options.sessionId ?? randomUUID(),\n\t\tcontinuitySessionId: options.continuitySessionId,\n\t\tmodel: options.model?.id,\n\t\tprovider: options.model?.provider,\n\t};\n}\n"]}

package/dist/core/memory/memory-identity.js

@@ -0,0 +1,19 @@
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+export function normalizeMemoryPath(path) {
+    return resolve(path).replaceAll("\\", "/").toLowerCase();
+}
+export function createProjectId(cwd) {
+    return createHash("sha256").update(normalizeMemoryPath(cwd)).digest("hex").slice(0, 16);
+}
+export function createMemorySessionIdentity(options) {
+    return {
+        cwd: options.cwd,
+        projectId: createProjectId(options.cwd),
+        sessionId: options.sessionId ?? randomUUID(),
+        continuitySessionId: options.continuitySessionId,
+        model: options.model?.id,
+        provider: options.model?.provider,
+    };
+}
+//# sourceMappingURL=memory-identity.js.map

package/dist/core/memory/memory-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-identity.js","sourceRoot":"","sources":["../../../src/core/memory/memory-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAU;IACzD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;AAAA,CACzD;AAED,MAAM,UAAU,eAAe,CAAC,GAAW,EAAU;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAAA,CACxF;AAED,MAAM,UAAU,2BAA2B,CAAC,OAK3C,EAAyB;IACzB,OAAO;QACN,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC;QACvC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,UAAU,EAAE;QAC5C,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE;QACxB,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ;KACjC,CAAC;AAAA,CACF","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { resolve } from \"node:path\";\nimport type { Model } from \"@threadwell/ai\";\nimport type { MemorySessionIdentity } from \"./memory-types.js\";\n\nexport function normalizeMemoryPath(path: string): string {\n\treturn resolve(path).replaceAll(\"\\\\\", \"/\").toLowerCase();\n}\n\nexport function createProjectId(cwd: string): string {\n\treturn createHash(\"sha256\").update(normalizeMemoryPath(cwd)).digest(\"hex\").slice(0, 16);\n}\n\nexport function createMemorySessionIdentity(options: {\n\tcwd: string;\n\tsessionId?: string;\n\tcontinuitySessionId?: string;\n\tmodel?: Model<any>;\n}): MemorySessionIdentity {\n\treturn {\n\t\tcwd: options.cwd,\n\t\tprojectId: createProjectId(options.cwd),\n\t\tsessionId: options.sessionId ?? randomUUID(),\n\t\tcontinuitySessionId: options.continuitySessionId,\n\t\tmodel: options.model?.id,\n\t\tprovider: options.model?.provider,\n\t};\n}\n"]}

package/dist/core/memory/memory-retrieval.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryEvent, MemoryEventType, MemorySearchRequest, MemorySearchResult } from "./memory-types.js";
+export interface MemoryRetrievalRequest {
+    query: string;
+    projectId?: string;
+    sessionId?: string;
+    types?: MemoryEventType[];
+    filePaths?: string[];
+    tags?: string[];
+    limit: number;
+    maxCapsuleBytes: number;
+}
+export interface MemoryCapsule {
+    id: string;
+    type: MemoryEventType;
+    summary: string;
+    citation: string;
+    createdAt: string;
+    score: number;
+    reason: string;
+    filePaths?: string[];
+    tags?: string[];
+}
+export interface ParsedMemoryCitation {
+    id: string;
+    type?: MemoryEventType;
+    createdAt?: string;
+    filePaths: string[];
+}
+export interface MemoryWhyResult {
+    citation: string;
+    summary: string;
+    reason: string;
+    score: number;
+    filePaths: string[];
+    tags: string[];
+}
+export declare function createMemoryRetrievalRequest(options: {
+    query: string;
+    projectId?: string;
+    sessionId?: string;
+    types?: MemoryEventType[];
+    filePaths?: string[];
+    tags?: string[];
+    limit?: number;
+    maxCapsuleBytes?: number;
+}): MemoryRetrievalRequest;
+export declare function toMemorySearchRequest(request: MemoryRetrievalRequest): MemorySearchRequest;
+export declare function rankMemorySearchResults(results: readonly MemorySearchResult[], request: MemoryRetrievalRequest): MemorySearchResult[];
+export declare function createMemoryCitation(event: MemoryEvent): string;
+export declare function parseMemoryCitation(citation: string): ParsedMemoryCitation | undefined;
+export declare function createMemoryCapsules(results: MemorySearchResult[], request: MemoryRetrievalRequest): MemoryCapsule[];
+export declare function getMemoryWhy(capsules: readonly MemoryCapsule[], selector?: string): MemoryWhyResult[];
+export declare function renderMemoryWhy(results: readonly MemoryWhyResult[]): string;
+export declare function renderMemoryCapsules(capsules: readonly MemoryCapsule[]): string | undefined;
+//# sourceMappingURL=memory-retrieval.d.ts.map

package/dist/core/memory/memory-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retrieval.d.ts","sourceRoot":"","sources":["../../../src/core/memory/memory-retrieval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE/G,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,sBAAsB,CAWzB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,mBAAmB,CAU1F;AAeD,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,OAAO,EAAE,sBAAsB,GAC7B,kBAAkB,EAAE,CAiBtB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAG/D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAUtF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,OAAO,EAAE,sBAAsB,GAAG,aAAa,EAAE,CAqBpH;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAarG;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAU3E;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,GAAG,SAAS,CAM3F","sourcesContent":["import { compactMemoryText } from \"./event-summary.js\";\nimport type { MemoryEvent, MemoryEventType, MemorySearchRequest, MemorySearchResult } from \"./memory-types.js\";\n\nexport interface MemoryRetrievalRequest {\n\tquery: string;\n\tprojectId?: string;\n\tsessionId?: string;\n\ttypes?: MemoryEventType[];\n\tfilePaths?: string[];\n\ttags?: string[];\n\tlimit: number;\n\tmaxCapsuleBytes: number;\n}\n\nexport interface MemoryCapsule {\n\tid: string;\n\ttype: MemoryEventType;\n\tsummary: string;\n\tcitation: string;\n\tcreatedAt: string;\n\tscore: number;\n\treason: string;\n\tfilePaths?: string[];\n\ttags?: string[];\n}\n\nexport interface ParsedMemoryCitation {\n\tid: string;\n\ttype?: MemoryEventType;\n\tcreatedAt?: string;\n\tfilePaths: string[];\n}\n\nexport interface MemoryWhyResult {\n\tcitation: string;\n\tsummary: string;\n\treason: string;\n\tscore: number;\n\tfilePaths: string[];\n\ttags: string[];\n}\n\nexport function createMemoryRetrievalRequest(options: {\n\tquery: string;\n\tprojectId?: string;\n\tsessionId?: string;\n\ttypes?: MemoryEventType[];\n\tfilePaths?: string[];\n\ttags?: string[];\n\tlimit?: number;\n\tmaxCapsuleBytes?: number;\n}): MemoryRetrievalRequest {\n\treturn {\n\t\tquery: options.query.trim(),\n\t\tprojectId: options.projectId,\n\t\tsessionId: options.sessionId,\n\t\ttypes: options.types,\n\t\tfilePaths: options.filePaths,\n\t\ttags: options.tags,\n\t\tlimit: options.limit ?? 8,\n\t\tmaxCapsuleBytes: options.maxCapsuleBytes ?? 4096,\n\t};\n}\n\nexport function toMemorySearchRequest(request: MemoryRetrievalRequest): MemorySearchRequest {\n\treturn {\n\t\tquery: request.query,\n\t\tprojectId: request.projectId,\n\t\tsessionId: request.sessionId,\n\t\ttypes: request.types,\n\t\tfilePaths: request.filePaths,\n\t\ttags: request.tags,\n\t\tlimit: request.limit,\n\t};\n}\n\nfunction recencyScore(createdAt: string): number {\n\tconst timestamp = Date.parse(createdAt);\n\tif (!Number.isFinite(timestamp)) return 0;\n\tconst ageDays = Math.max(0, (Date.now() - timestamp) / 86_400_000);\n\treturn Math.max(0, 1 - ageDays / 30);\n}\n\nfunction overlapScore(left: readonly string[] | undefined, right: readonly string[] | undefined): number {\n\tif (!left || !right || left.length === 0 || right.length === 0) return 0;\n\tconst rightSet = new Set(right);\n\treturn left.filter((value) => rightSet.has(value)).length;\n}\n\nexport function rankMemorySearchResults(\n\tresults: readonly MemorySearchResult[],\n\trequest: MemoryRetrievalRequest,\n): MemorySearchResult[] {\n\treturn results\n\t\t.map((result) => {\n\t\t\tconst priorityScore = result.event.priority * 2;\n\t\t\tconst fileScore = overlapScore(result.event.filePaths, request.filePaths) * 3;\n\t\t\tconst tagScore = overlapScore(result.event.tags, request.tags) * 2;\n\t\t\tconst typeScore = request.types?.includes(result.event.type) ? 2 : 0;\n\t\t\tconst score =\n\t\t\t\tresult.score + priorityScore + fileScore + tagScore + typeScore + recencyScore(result.event.createdAt);\n\t\t\treturn {\n\t\t\t\t...result,\n\t\t\t\tscore,\n\t\t\t\treason: `${result.reason}; hybrid priority/recency/path/tag ranking`,\n\t\t\t};\n\t\t})\n\t\t.sort((left, right) => right.score - left.score)\n\t\t.slice(0, request.limit);\n}\n\nexport function createMemoryCitation(event: MemoryEvent): string {\n\tconst files = event.filePaths && event.filePaths.length > 0 ? ` files:${event.filePaths.join(\",\")}` : \"\";\n\treturn `memory:${event.id} ${event.type} ${event.createdAt}${files}`;\n}\n\nexport function parseMemoryCitation(citation: string): ParsedMemoryCitation | undefined {\n\tconst match = citation.match(/^memory:([^\\s]+)(?:\\s+([^\\s]+))?(?:\\s+([^\\s]+))?(?:\\s+files:(.+))?$/);\n\tif (!match) return undefined;\n\tconst [, id, type, createdAt, files] = match;\n\treturn {\n\t\tid,\n\t\ttype: type as MemoryEventType | undefined,\n\t\tcreatedAt,\n\t\tfilePaths: files ? files.split(\",\").filter(Boolean) : [],\n\t};\n}\n\nexport function createMemoryCapsules(results: MemorySearchResult[], request: MemoryRetrievalRequest): MemoryCapsule[] {\n\tconst capsules: MemoryCapsule[] = [];\n\tlet bytes = 0;\n\tfor (const result of rankMemorySearchResults(results, request)) {\n\t\tconst capsule: MemoryCapsule = {\n\t\t\tid: result.event.id,\n\t\t\ttype: result.event.type,\n\t\t\tsummary: compactMemoryText(result.event.summary, 320),\n\t\t\tcitation: createMemoryCitation(result.event),\n\t\t\tcreatedAt: result.event.createdAt,\n\t\t\tscore: result.score,\n\t\t\treason: result.reason,\n\t\t\tfilePaths: result.event.filePaths,\n\t\t\ttags: result.event.tags,\n\t\t};\n\t\tconst nextBytes = Buffer.byteLength(JSON.stringify(capsule), \"utf-8\");\n\t\tif (bytes + nextBytes > request.maxCapsuleBytes && capsules.length > 0) break;\n\t\tbytes += nextBytes;\n\t\tcapsules.push(capsule);\n\t}\n\treturn capsules;\n}\n\nexport function getMemoryWhy(capsules: readonly MemoryCapsule[], selector?: string): MemoryWhyResult[] {\n\tconst normalizedSelector = selector?.trim();\n\tconst selected = normalizedSelector\n\t\t? capsules.filter((capsule) => capsule.id === normalizedSelector || capsule.citation === normalizedSelector)\n\t\t: capsules;\n\treturn selected.map((capsule) => ({\n\t\tcitation: capsule.citation,\n\t\tsummary: capsule.summary,\n\t\treason: capsule.reason,\n\t\tscore: capsule.score,\n\t\tfilePaths: capsule.filePaths ?? [],\n\t\ttags: capsule.tags ?? [],\n\t}));\n}\n\nexport function renderMemoryWhy(results: readonly MemoryWhyResult[]): string {\n\tif (results.length === 0) return \"No memory citations matched.\";\n\treturn [\n\t\t\"Threadwell memory why:\",\n\t\t...results.map((result) => {\n\t\t\tconst files = result.filePaths.length > 0 ? `\\n  files: ${result.filePaths.join(\", \")}` : \"\";\n\t\t\tconst tags = result.tags.length > 0 ? `\\n  tags: ${result.tags.join(\", \")}` : \"\";\n\t\t\treturn `- [${result.citation}] score=${result.score.toFixed(2)}\\n  reason: ${result.reason}\\n  summary: ${result.summary}${files}${tags}`;\n\t\t}),\n\t].join(\"\\n\");\n}\n\nexport function renderMemoryCapsules(capsules: readonly MemoryCapsule[]): string | undefined {\n\tif (capsules.length === 0) return undefined;\n\treturn [\n\t\t\"Relevant Threadwell memory:\",\n\t\t...capsules.map((capsule) => `- [${capsule.citation}] ${capsule.summary}`),\n\t].join(\"\\n\");\n}\n"]}

package/dist/core/memory/memory-retrieval.js

@@ -0,0 +1,128 @@
+import { compactMemoryText } from "./event-summary.js";
+export function createMemoryRetrievalRequest(options) {
+    return {
+        query: options.query.trim(),
+        projectId: options.projectId,
+        sessionId: options.sessionId,
+        types: options.types,
+        filePaths: options.filePaths,
+        tags: options.tags,
+        limit: options.limit ?? 8,
+        maxCapsuleBytes: options.maxCapsuleBytes ?? 4096,
+    };
+}
+export function toMemorySearchRequest(request) {
+    return {
+        query: request.query,
+        projectId: request.projectId,
+        sessionId: request.sessionId,
+        types: request.types,
+        filePaths: request.filePaths,
+        tags: request.tags,
+        limit: request.limit,
+    };
+}
+function recencyScore(createdAt) {
+    const timestamp = Date.parse(createdAt);
+    if (!Number.isFinite(timestamp))
+        return 0;
+    const ageDays = Math.max(0, (Date.now() - timestamp) / 86_400_000);
+    return Math.max(0, 1 - ageDays / 30);
+}
+function overlapScore(left, right) {
+    if (!left || !right || left.length === 0 || right.length === 0)
+        return 0;
+    const rightSet = new Set(right);
+    return left.filter((value) => rightSet.has(value)).length;
+}
+export function rankMemorySearchResults(results, request) {
+    return results
+        .map((result) => {
+        const priorityScore = result.event.priority * 2;
+        const fileScore = overlapScore(result.event.filePaths, request.filePaths) * 3;
+        const tagScore = overlapScore(result.event.tags, request.tags) * 2;
+        const typeScore = request.types?.includes(result.event.type) ? 2 : 0;
+        const score = result.score + priorityScore + fileScore + tagScore + typeScore + recencyScore(result.event.createdAt);
+        return {
+            ...result,
+            score,
+            reason: `${result.reason}; hybrid priority/recency/path/tag ranking`,
+        };
+    })
+        .sort((left, right) => right.score - left.score)
+        .slice(0, request.limit);
+}
+export function createMemoryCitation(event) {
+    const files = event.filePaths && event.filePaths.length > 0 ? ` files:${event.filePaths.join(",")}` : "";
+    return `memory:${event.id} ${event.type} ${event.createdAt}${files}`;
+}
+export function parseMemoryCitation(citation) {
+    const match = citation.match(/^memory:([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?(?:\s+files:(.+))?$/);
+    if (!match)
+        return undefined;
+    const [, id, type, createdAt, files] = match;
+    return {
+        id,
+        type: type,
+        createdAt,
+        filePaths: files ? files.split(",").filter(Boolean) : [],
+    };
+}
+export function createMemoryCapsules(results, request) {
+    const capsules = [];
+    let bytes = 0;
+    for (const result of rankMemorySearchResults(results, request)) {
+        const capsule = {
+            id: result.event.id,
+            type: result.event.type,
+            summary: compactMemoryText(result.event.summary, 320),
+            citation: createMemoryCitation(result.event),
+            createdAt: result.event.createdAt,
+            score: result.score,
+            reason: result.reason,
+            filePaths: result.event.filePaths,
+            tags: result.event.tags,
+        };
+        const nextBytes = Buffer.byteLength(JSON.stringify(capsule), "utf-8");
+        if (bytes + nextBytes > request.maxCapsuleBytes && capsules.length > 0)
+            break;
+        bytes += nextBytes;
+        capsules.push(capsule);
+    }
+    return capsules;
+}
+export function getMemoryWhy(capsules, selector) {
+    const normalizedSelector = selector?.trim();
+    const selected = normalizedSelector
+        ? capsules.filter((capsule) => capsule.id === normalizedSelector || capsule.citation === normalizedSelector)
+        : capsules;
+    return selected.map((capsule) => ({
+        citation: capsule.citation,
+        summary: capsule.summary,
+        reason: capsule.reason,
+        score: capsule.score,
+        filePaths: capsule.filePaths ?? [],
+        tags: capsule.tags ?? [],
+    }));
+}
+export function renderMemoryWhy(results) {
+    if (results.length === 0)
+        return "No memory citations matched.";
+    return [
+        "Threadwell memory why:",
+        ...results.map((result) => {
+            const files = result.filePaths.length > 0 ? `\n  files: ${result.filePaths.join(", ")}` : "";
+            const tags = result.tags.length > 0 ? `\n  tags: ${result.tags.join(", ")}` : "";
+            return `- [${result.citation}] score=${result.score.toFixed(2)}\n  reason: ${result.reason}\n  summary: ${result.summary}${files}${tags}`;
+        }),
+    ].join("\n");
+}
+export function renderMemoryCapsules(capsules) {
+    if (capsules.length === 0)
+        return undefined;
+    return [
+        "Relevant Threadwell memory:",
+        ...capsules.map((capsule) => `- [${capsule.citation}] ${capsule.summary}`),
+    ].join("\n");
+}
+//# sourceMappingURL=memory-retrieval.js.map

package/dist/core/memory/memory-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retrieval.js","sourceRoot":"","sources":["../../../src/core/memory/memory-retrieval.ts"],"names":[],"mappings":"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","sourcesContent":["import { compactMemoryText } from \"./event-summary.js\";\nimport type { MemoryEvent, MemoryEventType, MemorySearchRequest, MemorySearchResult } from \"./memory-types.js\";\n\nexport interface MemoryRetrievalRequest {\n\tquery: string;\n\tprojectId?: string;\n\tsessionId?: string;\n\ttypes?: MemoryEventType[];\n\tfilePaths?: string[];\n\ttags?: string[];\n\tlimit: number;\n\tmaxCapsuleBytes: number;\n}\n\nexport interface MemoryCapsule {\n\tid: string;\n\ttype: MemoryEventType;\n\tsummary: string;\n\tcitation: string;\n\tcreatedAt: string;\n\tscore: number;\n\treason: string;\n\tfilePaths?: string[];\n\ttags?: string[];\n}\n\nexport interface ParsedMemoryCitation {\n\tid: string;\n\ttype?: MemoryEventType;\n\tcreatedAt?: string;\n\tfilePaths: string[];\n}\n\nexport interface MemoryWhyResult {\n\tcitation: string;\n\tsummary: string;\n\treason: string;\n\tscore: number;\n\tfilePaths: string[];\n\ttags: string[];\n}\n\nexport function createMemoryRetrievalRequest(options: {\n\tquery: string;\n\tprojectId?: string;\n\tsessionId?: string;\n\ttypes?: MemoryEventType[];\n\tfilePaths?: string[];\n\ttags?: string[];\n\tlimit?: number;\n\tmaxCapsuleBytes?: number;\n}): MemoryRetrievalRequest {\n\treturn {\n\t\tquery: options.query.trim(),\n\t\tprojectId: options.projectId,\n\t\tsessionId: options.sessionId,\n\t\ttypes: options.types,\n\t\tfilePaths: options.filePaths,\n\t\ttags: options.tags,\n\t\tlimit: options.limit ?? 8,\n\t\tmaxCapsuleBytes: options.maxCapsuleBytes ?? 4096,\n\t};\n}\n\nexport function toMemorySearchRequest(request: MemoryRetrievalRequest): MemorySearchRequest {\n\treturn {\n\t\tquery: request.query,\n\t\tprojectId: request.projectId,\n\t\tsessionId: request.sessionId,\n\t\ttypes: request.types,\n\t\tfilePaths: request.filePaths,\n\t\ttags: request.tags,\n\t\tlimit: request.limit,\n\t};\n}\n\nfunction recencyScore(createdAt: string): number {\n\tconst timestamp = Date.parse(createdAt);\n\tif (!Number.isFinite(timestamp)) return 0;\n\tconst ageDays = Math.max(0, (Date.now() - timestamp) / 86_400_000);\n\treturn Math.max(0, 1 - ageDays / 30);\n}\n\nfunction overlapScore(left: readonly string[] | undefined, right: readonly string[] | undefined): number {\n\tif (!left || !right || left.length === 0 || right.length === 0) return 0;\n\tconst rightSet = new Set(right);\n\treturn left.filter((value) => rightSet.has(value)).length;\n}\n\nexport function rankMemorySearchResults(\n\tresults: readonly MemorySearchResult[],\n\trequest: MemoryRetrievalRequest,\n): MemorySearchResult[] {\n\treturn results\n\t\t.map((result) => {\n\t\t\tconst priorityScore = result.event.priority * 2;\n\t\t\tconst fileScore = overlapScore(result.event.filePaths, request.filePaths) * 3;\n\t\t\tconst tagScore = overlapScore(result.event.tags, request.tags) * 2;\n\t\t\tconst typeScore = request.types?.includes(result.event.type) ? 2 : 0;\n\t\t\tconst score =\n\t\t\t\tresult.score + priorityScore + fileScore + tagScore + typeScore + recencyScore(result.event.createdAt);\n\t\t\treturn {\n\t\t\t\t...result,\n\t\t\t\tscore,\n\t\t\t\treason: `${result.reason}; hybrid priority/recency/path/tag ranking`,\n\t\t\t};\n\t\t})\n\t\t.sort((left, right) => right.score - left.score)\n\t\t.slice(0, request.limit);\n}\n\nexport function createMemoryCitation(event: MemoryEvent): string {\n\tconst files = event.filePaths && event.filePaths.length > 0 ? ` files:${event.filePaths.join(\",\")}` : \"\";\n\treturn `memory:${event.id} ${event.type} ${event.createdAt}${files}`;\n}\n\nexport function parseMemoryCitation(citation: string): ParsedMemoryCitation | undefined {\n\tconst match = citation.match(/^memory:([^\\s]+)(?:\\s+([^\\s]+))?(?:\\s+([^\\s]+))?(?:\\s+files:(.+))?$/);\n\tif (!match) return undefined;\n\tconst [, id, type, createdAt, files] = match;\n\treturn {\n\t\tid,\n\t\ttype: type as MemoryEventType | undefined,\n\t\tcreatedAt,\n\t\tfilePaths: files ? files.split(\",\").filter(Boolean) : [],\n\t};\n}\n\nexport function createMemoryCapsules(results: MemorySearchResult[], request: MemoryRetrievalRequest): MemoryCapsule[] {\n\tconst capsules: MemoryCapsule[] = [];\n\tlet bytes = 0;\n\tfor (const result of rankMemorySearchResults(results, request)) {\n\t\tconst capsule: MemoryCapsule = {\n\t\t\tid: result.event.id,\n\t\t\ttype: result.event.type,\n\t\t\tsummary: compactMemoryText(result.event.summary, 320),\n\t\t\tcitation: createMemoryCitation(result.event),\n\t\t\tcreatedAt: result.event.createdAt,\n\t\t\tscore: result.score,\n\t\t\treason: result.reason,\n\t\t\tfilePaths: result.event.filePaths,\n\t\t\ttags: result.event.tags,\n\t\t};\n\t\tconst nextBytes = Buffer.byteLength(JSON.stringify(capsule), \"utf-8\");\n\t\tif (bytes + nextBytes > request.maxCapsuleBytes && capsules.length > 0) break;\n\t\tbytes += nextBytes;\n\t\tcapsules.push(capsule);\n\t}\n\treturn capsules;\n}\n\nexport function getMemoryWhy(capsules: readonly MemoryCapsule[], selector?: string): MemoryWhyResult[] {\n\tconst normalizedSelector = selector?.trim();\n\tconst selected = normalizedSelector\n\t\t? capsules.filter((capsule) => capsule.id === normalizedSelector || capsule.citation === normalizedSelector)\n\t\t: capsules;\n\treturn selected.map((capsule) => ({\n\t\tcitation: capsule.citation,\n\t\tsummary: capsule.summary,\n\t\treason: capsule.reason,\n\t\tscore: capsule.score,\n\t\tfilePaths: capsule.filePaths ?? [],\n\t\ttags: capsule.tags ?? [],\n\t}));\n}\n\nexport function renderMemoryWhy(results: readonly MemoryWhyResult[]): string {\n\tif (results.length === 0) return \"No memory citations matched.\";\n\treturn [\n\t\t\"Threadwell memory why:\",\n\t\t...results.map((result) => {\n\t\t\tconst files = result.filePaths.length > 0 ? `\\n  files: ${result.filePaths.join(\", \")}` : \"\";\n\t\t\tconst tags = result.tags.length > 0 ? `\\n  tags: ${result.tags.join(\", \")}` : \"\";\n\t\t\treturn `- [${result.citation}] score=${result.score.toFixed(2)}\\n  reason: ${result.reason}\\n  summary: ${result.summary}${files}${tags}`;\n\t\t}),\n\t].join(\"\\n\");\n}\n\nexport function renderMemoryCapsules(capsules: readonly MemoryCapsule[]): string | undefined {\n\tif (capsules.length === 0) return undefined;\n\treturn [\n\t\t\"Relevant Threadwell memory:\",\n\t\t...capsules.map((capsule) => `- [${capsule.citation}] ${capsule.summary}`),\n\t].join(\"\\n\");\n}\n"]}

package/dist/core/memory/memory-schema.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryEventInput, MemoryEventType, MemoryPriority } from "./memory-types.js";
+export declare const MEMORY_EVENT_TYPES: readonly ["session_started", "session_ended", "user_message", "assistant_response", "assistant_summary", "compaction_snapshot", "tool_call", "tool_result", "file_modified", "validation_started", "validation_passed", "validation_failed", "decision", "decision_candidate", "blocker", "open_question", "handoff", "context_candidate", "adr_candidate", "task_started", "task_completed", "task_blocked"];
+export declare const MEMORY_PRIORITIES: readonly [0, 1, 2, 3, 4, 5];
+export declare const DEFAULT_MEMORY_PRIORITY_BY_TYPE: Readonly<Record<MemoryEventType, MemoryPriority>>;
+export declare const MEMORY_RETENTION_HINT_BY_TYPE: Readonly<Record<MemoryEventType, "ephemeral" | "normal" | "durable">>;
+export declare function isMemoryEventType(value: string): value is MemoryEventType;
+export declare function isMemoryPriority(value: number): value is MemoryPriority;
+export declare function getDefaultMemoryPriority(type: MemoryEventType): MemoryPriority;
+export declare function normalizeMemoryEventInput(input: MemoryEventInput): MemoryEventInput;
+export declare function validateMemoryEventInput(input: MemoryEventInput): string[];
+//# sourceMappingURL=memory-schema.d.ts.map

package/dist/core/memory/memory-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-schema.d.ts","sourceRoot":"","sources":["../../../src/core/memory/memory-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE3F,eAAO,MAAM,kBAAkB,+YAuBgB,CAAC;AAEhD,eAAO,MAAM,iBAAiB,6BAAkE,CAAC;AAEjG,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAuB7F,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC,CAuB/G,CAAC;AAKF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEvE;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAE9E;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAanF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAY1E","sourcesContent":["import type { MemoryEventInput, MemoryEventType, MemoryPriority } from \"./memory-types.js\";\n\nexport const MEMORY_EVENT_TYPES = [\n\t\"session_started\",\n\t\"session_ended\",\n\t\"user_message\",\n\t\"assistant_response\",\n\t\"assistant_summary\",\n\t\"compaction_snapshot\",\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"file_modified\",\n\t\"validation_started\",\n\t\"validation_passed\",\n\t\"validation_failed\",\n\t\"decision\",\n\t\"decision_candidate\",\n\t\"blocker\",\n\t\"open_question\",\n\t\"handoff\",\n\t\"context_candidate\",\n\t\"adr_candidate\",\n\t\"task_started\",\n\t\"task_completed\",\n\t\"task_blocked\",\n] as const satisfies readonly MemoryEventType[];\n\nexport const MEMORY_PRIORITIES = [0, 1, 2, 3, 4, 5] as const satisfies readonly MemoryPriority[];\n\nexport const DEFAULT_MEMORY_PRIORITY_BY_TYPE: Readonly<Record<MemoryEventType, MemoryPriority>> = {\n\tsession_started: 2,\n\tsession_ended: 2,\n\tuser_message: 3,\n\tassistant_response: 2,\n\tassistant_summary: 2,\n\tcompaction_snapshot: 4,\n\ttool_call: 1,\n\ttool_result: 1,\n\tfile_modified: 4,\n\tvalidation_started: 2,\n\tvalidation_passed: 4,\n\tvalidation_failed: 4,\n\tdecision: 5,\n\tdecision_candidate: 3,\n\tblocker: 5,\n\topen_question: 4,\n\thandoff: 5,\n\tcontext_candidate: 3,\n\tadr_candidate: 4,\n\ttask_started: 3,\n\ttask_completed: 4,\n\ttask_blocked: 5,\n};\n\nexport const MEMORY_RETENTION_HINT_BY_TYPE: Readonly<Record<MemoryEventType, \"ephemeral\" | \"normal\" | \"durable\">> = {\n\tsession_started: \"normal\",\n\tsession_ended: \"normal\",\n\tuser_message: \"normal\",\n\tassistant_response: \"normal\",\n\tassistant_summary: \"normal\",\n\tcompaction_snapshot: \"normal\",\n\ttool_call: \"ephemeral\",\n\ttool_result: \"ephemeral\",\n\tfile_modified: \"normal\",\n\tvalidation_started: \"ephemeral\",\n\tvalidation_passed: \"normal\",\n\tvalidation_failed: \"normal\",\n\tdecision: \"durable\",\n\tdecision_candidate: \"normal\",\n\tblocker: \"durable\",\n\topen_question: \"durable\",\n\thandoff: \"durable\",\n\tcontext_candidate: \"normal\",\n\tadr_candidate: \"normal\",\n\ttask_started: \"normal\",\n\ttask_completed: \"normal\",\n\ttask_blocked: \"durable\",\n};\n\nconst MEMORY_EVENT_TYPE_SET = new Set<string>(MEMORY_EVENT_TYPES);\nconst MEMORY_PRIORITY_SET = new Set<number>(MEMORY_PRIORITIES);\n\nexport function isMemoryEventType(value: string): value is MemoryEventType {\n\treturn MEMORY_EVENT_TYPE_SET.has(value);\n}\n\nexport function isMemoryPriority(value: number): value is MemoryPriority {\n\treturn MEMORY_PRIORITY_SET.has(value);\n}\n\nexport function getDefaultMemoryPriority(type: MemoryEventType): MemoryPriority {\n\treturn DEFAULT_MEMORY_PRIORITY_BY_TYPE[type];\n}\n\nexport function normalizeMemoryEventInput(input: MemoryEventInput): MemoryEventInput {\n\tconst summary = input.summary.trim();\n\tconst priority = input.priority ?? getDefaultMemoryPriority(input.type);\n\tconst filePaths = input.filePaths?.map((filePath) => filePath.trim()).filter(Boolean);\n\tconst tags = input.tags?.map((tag) => tag.trim()).filter(Boolean);\n\n\treturn {\n\t\t...input,\n\t\tsummary,\n\t\tpriority,\n\t\tfilePaths: filePaths && filePaths.length > 0 ? [...new Set(filePaths)] : undefined,\n\t\ttags: tags && tags.length > 0 ? [...new Set(tags)] : undefined,\n\t};\n}\n\nexport function validateMemoryEventInput(input: MemoryEventInput): string[] {\n\tconst errors: string[] = [];\n\tif (!isMemoryEventType(input.type)) {\n\t\terrors.push(`Unknown memory event type: ${input.type}`);\n\t}\n\tif (!input.summary.trim()) {\n\t\terrors.push(\"Memory event summary is required\");\n\t}\n\tif (input.priority !== undefined && !isMemoryPriority(input.priority)) {\n\t\terrors.push(`Invalid memory priority: ${input.priority}`);\n\t}\n\treturn errors;\n}\n"]}

package/dist/core/memory/memory-schema.js

@@ -0,0 +1,111 @@
+export const MEMORY_EVENT_TYPES = [
+    "session_started",
+    "session_ended",
+    "user_message",
+    "assistant_response",
+    "assistant_summary",
+    "compaction_snapshot",
+    "tool_call",
+    "tool_result",
+    "file_modified",
+    "validation_started",
+    "validation_passed",
+    "validation_failed",
+    "decision",
+    "decision_candidate",
+    "blocker",
+    "open_question",
+    "handoff",
+    "context_candidate",
+    "adr_candidate",
+    "task_started",
+    "task_completed",
+    "task_blocked",
+];
+export const MEMORY_PRIORITIES = [0, 1, 2, 3, 4, 5];
+export const DEFAULT_MEMORY_PRIORITY_BY_TYPE = {
+    session_started: 2,
+    session_ended: 2,
+    user_message: 3,
+    assistant_response: 2,
+    assistant_summary: 2,
+    compaction_snapshot: 4,
+    tool_call: 1,
+    tool_result: 1,
+    file_modified: 4,
+    validation_started: 2,
+    validation_passed: 4,
+    validation_failed: 4,
+    decision: 5,
+    decision_candidate: 3,
+    blocker: 5,
+    open_question: 4,
+    handoff: 5,
+    context_candidate: 3,
+    adr_candidate: 4,
+    task_started: 3,
+    task_completed: 4,
+    task_blocked: 5,
+};
+export const MEMORY_RETENTION_HINT_BY_TYPE = {
+    session_started: "normal",
+    session_ended: "normal",
+    user_message: "normal",
+    assistant_response: "normal",
+    assistant_summary: "normal",
+    compaction_snapshot: "normal",
+    tool_call: "ephemeral",
+    tool_result: "ephemeral",
+    file_modified: "normal",
+    validation_started: "ephemeral",
+    validation_passed: "normal",
+    validation_failed: "normal",
+    decision: "durable",
+    decision_candidate: "normal",
+    blocker: "durable",
+    open_question: "durable",
+    handoff: "durable",
+    context_candidate: "normal",
+    adr_candidate: "normal",
+    task_started: "normal",
+    task_completed: "normal",
+    task_blocked: "durable",
+};
+const MEMORY_EVENT_TYPE_SET = new Set(MEMORY_EVENT_TYPES);
+const MEMORY_PRIORITY_SET = new Set(MEMORY_PRIORITIES);
+export function isMemoryEventType(value) {
+    return MEMORY_EVENT_TYPE_SET.has(value);
+}
+export function isMemoryPriority(value) {
+    return MEMORY_PRIORITY_SET.has(value);
+}
+export function getDefaultMemoryPriority(type) {
+    return DEFAULT_MEMORY_PRIORITY_BY_TYPE[type];
+}
+export function normalizeMemoryEventInput(input) {
+    const summary = input.summary.trim();
+    const priority = input.priority ?? getDefaultMemoryPriority(input.type);
+    const filePaths = input.filePaths?.map((filePath) => filePath.trim()).filter(Boolean);
+    const tags = input.tags?.map((tag) => tag.trim()).filter(Boolean);
+    return {
+        ...input,
+        summary,
+        priority,
+        filePaths: filePaths && filePaths.length > 0 ? [...new Set(filePaths)] : undefined,
+        tags: tags && tags.length > 0 ? [...new Set(tags)] : undefined,
+    };
+}
+export function validateMemoryEventInput(input) {
+    const errors = [];
+    if (!isMemoryEventType(input.type)) {
+        errors.push(`Unknown memory event type: ${input.type}`);
+    }
+    if (!input.summary.trim()) {
+        errors.push("Memory event summary is required");
+    }
+    if (input.priority !== undefined && !isMemoryPriority(input.priority)) {
+        errors.push(`Invalid memory priority: ${input.priority}`);
+    }
+    return errors;
+}
+//# sourceMappingURL=memory-schema.js.map

package/dist/core/memory/memory-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-schema.js","sourceRoot":"","sources":["../../../src/core/memory/memory-schema.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MemoryEventInput, MemoryEventType, MemoryPriority } from \"./memory-types.js\";\n\nexport const MEMORY_EVENT_TYPES = [\n\t\"session_started\",\n\t\"session_ended\",\n\t\"user_message\",\n\t\"assistant_response\",\n\t\"assistant_summary\",\n\t\"compaction_snapshot\",\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"file_modified\",\n\t\"validation_started\",\n\t\"validation_passed\",\n\t\"validation_failed\",\n\t\"decision\",\n\t\"decision_candidate\",\n\t\"blocker\",\n\t\"open_question\",\n\t\"handoff\",\n\t\"context_candidate\",\n\t\"adr_candidate\",\n\t\"task_started\",\n\t\"task_completed\",\n\t\"task_blocked\",\n] as const satisfies readonly MemoryEventType[];\n\nexport const MEMORY_PRIORITIES = [0, 1, 2, 3, 4, 5] as const satisfies readonly MemoryPriority[];\n\nexport const DEFAULT_MEMORY_PRIORITY_BY_TYPE: Readonly<Record<MemoryEventType, MemoryPriority>> = {\n\tsession_started: 2,\n\tsession_ended: 2,\n\tuser_message: 3,\n\tassistant_response: 2,\n\tassistant_summary: 2,\n\tcompaction_snapshot: 4,\n\ttool_call: 1,\n\ttool_result: 1,\n\tfile_modified: 4,\n\tvalidation_started: 2,\n\tvalidation_passed: 4,\n\tvalidation_failed: 4,\n\tdecision: 5,\n\tdecision_candidate: 3,\n\tblocker: 5,\n\topen_question: 4,\n\thandoff: 5,\n\tcontext_candidate: 3,\n\tadr_candidate: 4,\n\ttask_started: 3,\n\ttask_completed: 4,\n\ttask_blocked: 5,\n};\n\nexport const MEMORY_RETENTION_HINT_BY_TYPE: Readonly<Record<MemoryEventType, \"ephemeral\" | \"normal\" | \"durable\">> = {\n\tsession_started: \"normal\",\n\tsession_ended: \"normal\",\n\tuser_message: \"normal\",\n\tassistant_response: \"normal\",\n\tassistant_summary: \"normal\",\n\tcompaction_snapshot: \"normal\",\n\ttool_call: \"ephemeral\",\n\ttool_result: \"ephemeral\",\n\tfile_modified: \"normal\",\n\tvalidation_started: \"ephemeral\",\n\tvalidation_passed: \"normal\",\n\tvalidation_failed: \"normal\",\n\tdecision: \"durable\",\n\tdecision_candidate: \"normal\",\n\tblocker: \"durable\",\n\topen_question: \"durable\",\n\thandoff: \"durable\",\n\tcontext_candidate: \"normal\",\n\tadr_candidate: \"normal\",\n\ttask_started: \"normal\",\n\ttask_completed: \"normal\",\n\ttask_blocked: \"durable\",\n};\n\nconst MEMORY_EVENT_TYPE_SET = new Set<string>(MEMORY_EVENT_TYPES);\nconst MEMORY_PRIORITY_SET = new Set<number>(MEMORY_PRIORITIES);\n\nexport function isMemoryEventType(value: string): value is MemoryEventType {\n\treturn MEMORY_EVENT_TYPE_SET.has(value);\n}\n\nexport function isMemoryPriority(value: number): value is MemoryPriority {\n\treturn MEMORY_PRIORITY_SET.has(value);\n}\n\nexport function getDefaultMemoryPriority(type: MemoryEventType): MemoryPriority {\n\treturn DEFAULT_MEMORY_PRIORITY_BY_TYPE[type];\n}\n\nexport function normalizeMemoryEventInput(input: MemoryEventInput): MemoryEventInput {\n\tconst summary = input.summary.trim();\n\tconst priority = input.priority ?? getDefaultMemoryPriority(input.type);\n\tconst filePaths = input.filePaths?.map((filePath) => filePath.trim()).filter(Boolean);\n\tconst tags = input.tags?.map((tag) => tag.trim()).filter(Boolean);\n\n\treturn {\n\t\t...input,\n\t\tsummary,\n\t\tpriority,\n\t\tfilePaths: filePaths && filePaths.length > 0 ? [...new Set(filePaths)] : undefined,\n\t\ttags: tags && tags.length > 0 ? [...new Set(tags)] : undefined,\n\t};\n}\n\nexport function validateMemoryEventInput(input: MemoryEventInput): string[] {\n\tconst errors: string[] = [];\n\tif (!isMemoryEventType(input.type)) {\n\t\terrors.push(`Unknown memory event type: ${input.type}`);\n\t}\n\tif (!input.summary.trim()) {\n\t\terrors.push(\"Memory event summary is required\");\n\t}\n\tif (input.priority !== undefined && !isMemoryPriority(input.priority)) {\n\t\terrors.push(`Invalid memory priority: ${input.priority}`);\n\t}\n\treturn errors;\n}\n"]}

package/dist/core/memory/memory-service.d.ts

@@ -0,0 +1,35 @@
+import { type MemoryStore } from "./memory-store.js";
+import type { MemoryEvent, MemoryEventInput, MemorySearchRequest, MemorySearchResult, MemorySessionIdentity, MemoryStatus } from "./memory-types.js";
+export interface MemoryRetentionPolicy {
+    retentionDays?: number;
+    maxEvents?: number;
+}
+export interface MemoryServiceOptions {
+    session: MemorySessionIdentity;
+    store?: MemoryStore;
+    enabled?: boolean;
+    retention?: MemoryRetentionPolicy;
+}
+export declare class MemoryService {
+    private readonly session;
+    private readonly store;
+    private readonly enabled;
+    private readonly retention;
+    private readonly dedupe;
+    private initialized;
+    constructor(options: MemoryServiceOptions);
+    initialize(): Promise<void>;
+    recordEvent(event: MemoryEventInput): Promise<MemoryEvent | undefined>;
+    search(request: MemorySearchRequest): Promise<MemorySearchResult[]>;
+    getRecent(limit?: number): Promise<MemoryEvent[]>;
+    exportProject(): Promise<{
+        path: string;
+        eventCount: number;
+    }>;
+    forgetEvent(eventId: string): Promise<boolean>;
+    purgeProject(): Promise<number>;
+    applyRetentionPolicy(): Promise<number>;
+    getStatus(): Promise<MemoryStatus>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=memory-service.d.ts.map

package/dist/core/memory/memory-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-service.d.ts","sourceRoot":"","sources":["../../../src/core/memory/memory-service.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EACX,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,qBAAqB;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,WAAW,CAAS;IAE5B,YAAY,OAAO,EAAE,oBAAoB,EAQxC;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAKhC;IAEK,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAa3E;IAEK,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAIxE;IAEK,SAAS,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAIlD;IAEK,aAAa,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAUnE;IAEK,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAInD;IAEK,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAIpC;IAEK,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAkB5C;IAEK,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC,CAavC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;CACD","sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { THREADWELL_CONFIG_DIR_NAME } from \"../../config.js\";\nimport { MemoryDedupeWindow } from \"./dedupe.js\";\nimport { summarizeMemoryEvent } from \"./event-summary.js\";\nimport { normalizeMemoryEventInput, validateMemoryEventInput } from \"./memory-schema.js\";\nimport { type MemoryStore, NoopMemoryStore } from \"./memory-store.js\";\nimport type {\n\tMemoryEvent,\n\tMemoryEventInput,\n\tMemorySearchRequest,\n\tMemorySearchResult,\n\tMemorySessionIdentity,\n\tMemoryStatus,\n} from \"./memory-types.js\";\nimport { redactMemoryEventInput } from \"./redaction.js\";\n\nexport interface MemoryRetentionPolicy {\n\tretentionDays?: number;\n\tmaxEvents?: number;\n}\n\nexport interface MemoryServiceOptions {\n\tsession: MemorySessionIdentity;\n\tstore?: MemoryStore;\n\tenabled?: boolean;\n\tretention?: MemoryRetentionPolicy;\n}\n\nexport class MemoryService {\n\tprivate readonly session: MemorySessionIdentity;\n\tprivate readonly store: MemoryStore;\n\tprivate readonly enabled: boolean;\n\tprivate readonly retention: Required<MemoryRetentionPolicy>;\n\tprivate readonly dedupe = new MemoryDedupeWindow();\n\tprivate initialized = false;\n\n\tconstructor(options: MemoryServiceOptions) {\n\t\tthis.session = options.session;\n\t\tthis.enabled = options.enabled ?? true;\n\t\tthis.retention = {\n\t\t\tretentionDays: options.retention?.retentionDays ?? 90,\n\t\t\tmaxEvents: options.retention?.maxEvents ?? 10000,\n\t\t};\n\t\tthis.store = options.store ?? new NoopMemoryStore();\n\t}\n\n\tasync initialize(): Promise<void> {\n\t\tif (this.initialized) return;\n\t\tthis.initialized = true;\n\t\tif (!this.enabled) return;\n\t\tawait this.store.initialize(this.session);\n\t}\n\n\tasync recordEvent(event: MemoryEventInput): Promise<MemoryEvent | undefined> {\n\t\tif (!this.enabled) return undefined;\n\t\tconst eventWithSummary = { ...event, summary: event.summary.trim() || summarizeMemoryEvent(event) };\n\t\tconst normalizedEvent = normalizeMemoryEventInput(redactMemoryEventInput(eventWithSummary));\n\t\tif (!this.dedupe.shouldRecord(normalizedEvent)) return undefined;\n\t\tconst errors = validateMemoryEventInput(normalizedEvent);\n\t\tif (errors.length > 0) {\n\t\t\tthrow new Error(`Invalid memory event: ${errors.join(\"; \")}`);\n\t\t}\n\t\tawait this.initialize();\n\t\tconst recorded = await this.store.recordEvent(this.session, normalizedEvent);\n\t\tawait this.applyRetentionPolicy();\n\t\treturn recorded;\n\t}\n\n\tasync search(request: MemorySearchRequest): Promise<MemorySearchResult[]> {\n\t\tif (!this.enabled) return [];\n\t\tawait this.initialize();\n\t\treturn this.store.search({ projectId: this.session.projectId, ...request });\n\t}\n\n\tasync getRecent(limit = 10): Promise<MemoryEvent[]> {\n\t\tif (!this.enabled) return [];\n\t\tawait this.initialize();\n\t\treturn this.store.getRecent(this.session.projectId, limit);\n\t}\n\n\tasync exportProject(): Promise<{ path: string; eventCount: number }> {\n\t\tif (!this.enabled) return { path: \"\", eventCount: 0 };\n\t\tawait this.initialize();\n\t\tconst status = await this.store.getStatus();\n\t\tconst events = await this.store.getRecent(this.session.projectId, Math.max(status.eventCount, 1));\n\t\tconst exportDir = join(this.session.cwd, THREADWELL_CONFIG_DIR_NAME, \"exports\");\n\t\tawait mkdir(exportDir, { recursive: true });\n\t\tconst path = join(exportDir, `memory-${new Date().toISOString().replace(/[:.]/g, \"-\")}.jsonl`);\n\t\tawait writeFile(path, `${events.map((event) => JSON.stringify(event)).join(\"\\n\")}\\n`, \"utf-8\");\n\t\treturn { path, eventCount: events.length };\n\t}\n\n\tasync forgetEvent(eventId: string): Promise<boolean> {\n\t\tif (!this.enabled) return false;\n\t\tawait this.initialize();\n\t\treturn this.store.deleteEvent(this.session.projectId, eventId);\n\t}\n\n\tasync purgeProject(): Promise<number> {\n\t\tif (!this.enabled) return 0;\n\t\tawait this.initialize();\n\t\treturn this.store.purgeProject(this.session.projectId);\n\t}\n\n\tasync applyRetentionPolicy(): Promise<number> {\n\t\tif (!this.enabled) return 0;\n\t\tawait this.initialize();\n\t\tconst status = await this.store.getStatus();\n\t\tconst events = await this.store.getRecent(this.session.projectId, Math.max(status.eventCount, 1));\n\t\tconst cutoff = Date.now() - this.retention.retentionDays * 24 * 60 * 60 * 1000;\n\t\tconst idsToDelete = new Set<string>();\n\t\tfor (const event of events) {\n\t\t\tif (Date.parse(event.createdAt) < cutoff) idsToDelete.add(event.id);\n\t\t}\n\t\tfor (const event of events.slice(this.retention.maxEvents)) {\n\t\t\tidsToDelete.add(event.id);\n\t\t}\n\t\tlet deleted = 0;\n\t\tfor (const id of idsToDelete) {\n\t\t\tif (await this.store.deleteEvent(this.session.projectId, id)) deleted++;\n\t\t}\n\t\treturn deleted;\n\t}\n\n\tasync getStatus(): Promise<MemoryStatus> {\n\t\tif (!this.enabled) {\n\t\t\treturn {\n\t\t\t\tenabled: false,\n\t\t\t\tprojectId: this.session.projectId,\n\t\t\t\tsessionId: this.session.sessionId,\n\t\t\t\teventCount: 0,\n\t\t\t\tstore: this.store.kind,\n\t\t\t};\n\t\t}\n\t\tawait this.initialize();\n\t\tconst status = await this.store.getStatus();\n\t\treturn { ...status, enabled: true, projectId: this.session.projectId, sessionId: this.session.sessionId };\n\t}\n\n\tasync close(): Promise<void> {\n\t\tawait this.store.close();\n\t}\n}\n"]}