neo4j-agent-memory 0.4.0 → 0.4.1

package/README.md

@@ -55,7 +55,7 @@ const bundle = await mem.retrieveContextBundle({
   env: { os: "macos", packageManager: "npm", container: false }
 });
 
-await mem.feedback({
+const feedback = await mem.feedback({
   agentId: "auggie",
   sessionId: bundle.sessionId,
   usedIds: bundle.sections.fix.map((m) => m.id),
@@ -69,6 +69,7 @@ await mem.close();
 Notes:
 - `createMemoryService` runs schema setup on init.
 - Cypher assets are bundled at `dist/cypher` in the published package.
+ - `feedback()` returns updated RECALLS edge posteriors for the provided memory ids.
 
 Auto-relate config (defaults):
 - `enabled: true`
@@ -127,6 +128,24 @@ const skills = await mem.listSkills({ agentId: "auggie" });
 const concepts = await mem.listConcepts({ agentId: "auggie" });
 ```
 
+## Graph APIs
+
+Fetch full memory records by id:
+
+```ts
+const records = await mem.getMemoriesById({ ids: ["mem-1", "mem-2"] });
+```
+
+Retrieve a weighted subgraph for UI maps:
+
+```ts
+const graph = await mem.getMemoryGraph({
+  agentId: "auggie",
+  memoryIds: ["mem-1", "mem-2"],
+  includeNodes: true,
+});
+```
+
 ## Episodic capture helpers
 
 ```ts

package/dist/cypher/feedback_batch.cypher

@@ -4,30 +4,19 @@
 //   halfLifeSeconds: 86400,
 //   aMin: 1.0,
 //   bMin: 1.0,
-//   w: 1.0,
-//   y: 1.0,
 //   items: [
-//     "mem_8cd773c2-208c-45ad-97ea-1b2337dca751",
-//     "mem_64fbcc73-0b5c-4041-8b6b-66514ffaf1d0",
-//     "mem_e55b80e2-6156-47bc-a964-9aef596f74a6",
-//     "mem_13189119-e3ad-4769-9f2b-2d3e3b8bc07f",
-//     "mem_137c3ff7-a81d-453d-8048-5c1b736db6ca",
-//     "mem_c0ea5643-3c61-4607-ba9f-67f4c2bb01ee",
-//     "mem_aa15e7b6-7f94-445a-9c52-3eb24a315215",
-//     "mem_e93e7bb8-b43c-44f5-a5d3-87545d67be59",
-//     "mem_b81e3709-35ae-4cab-931d-612dcc2cd43d",
-//     "mem_ce8a5b62-7ddb-4618-8a6c-93ed3b425f27",
-//     "mem_737df25b-7944-4dee-a7aa-86af93567663"
+//     { memoryId: "mem_8cd773c2-208c-45ad-97ea-1b2337dca751", w: 1.0, y: 1.0 },
+//     { memoryId: "mem_64fbcc73-0b5c-4041-8b6b-66514ffaf1d0", w: 1.0, y: 0.0 }
 //   ]
 // }
 WITH datetime($nowIso) AS now
 
-UNWIND $items AS memoryId
-WITH now, memoryId
-WHERE memoryId IS NOT NULL AND memoryId <> ""
+UNWIND $items AS item
+WITH now, item
+WHERE item.memoryId IS NOT NULL AND item.memoryId <> ""
 
 MATCH (a:Agent {id: $agentId})
-MATCH (m:Memory {id: memoryId})
+MATCH (m:Memory {id: item.memoryId})
 
 MERGE (a)-[r:RECALLS]->(m)
 ON CREATE SET
@@ -38,25 +27,25 @@ ON CREATE SET
   r.successes = 0,
   r.failures = 0
 
-WITH now, r,
+WITH now, r, item,
      CASE
        WHEN duration.inSeconds(coalesce(r.updatedAt, now), now).seconds > 0
        THEN duration.inSeconds(coalesce(r.updatedAt, now), now).seconds
        ELSE 0
      END AS dt
 
-WITH now, r,
+WITH now, r, item,
      0.5 ^ (dt / $halfLifeSeconds) AS gamma,
      coalesce(r.a, $aMin) AS aPrev,
      coalesce(r.b, $bMin) AS bPrev
 
-WITH now, r, gamma,
+WITH now, r, item, gamma,
      ($aMin + gamma * (aPrev - $aMin)) AS a0,
      ($bMin + gamma * (bPrev - $bMin)) AS b0
 
-WITH now, r,
-     (a0 + $w * $y) AS a1,
-     (b0 + $w * (1.0 - $y)) AS b1
+WITH now, r, item,
+     (a0 + item.w * item.y) AS a1,
+     (b0 + item.w * (1.0 - item.y)) AS b1
 
 SET r.a = a1,
     r.b = b1,
@@ -64,7 +53,12 @@ SET r.a = a1,
     r.evidence = a1 + b1,
     r.updatedAt = now,
     r.uses = coalesce(r.uses, 0) + 1,
-    r.successes = coalesce(r.successes, 0) + CASE WHEN $y >= 0.5 THEN 1 ELSE 0 END,
-    r.failures = coalesce(r.failures, 0) + CASE WHEN $y < 0.5 THEN 1 ELSE 0 END
+    r.successes = coalesce(r.successes, 0) + CASE WHEN item.y >= 0.5 THEN 1 ELSE 0 END,
+    r.failures = coalesce(r.failures, 0) + CASE WHEN item.y < 0.5 THEN 1 ELSE 0 END
 
-RETURN count(*) AS updated;
+RETURN item.memoryId AS id,
+       r.a AS a,
+       r.b AS b,
+       r.strength AS strength,
+       r.evidence AS evidence,
+       toString(r.updatedAt) AS updatedAt;

package/dist/cypher/get_memories_by_id.cypher

@@ -0,0 +1,41 @@
+// Parameters:
+// - $ids: Array of memory ids
+WITH [id IN coalesce($ids, []) WHERE id IS NOT NULL AND id <> ""] AS ids
+UNWIND range(0, size(ids) - 1) AS idx
+WITH idx, ids[idx] AS id
+MATCH (m:Memory {id: id})
+OPTIONAL MATCH (m)-[:APPLIES_IN]->(e:EnvironmentFingerprint)
+WITH idx, m, collect(e {
+  .hash,
+  .os,
+  .distro,
+  .ci,
+  .container,
+  .filesystem,
+  .workspaceMount,
+  .nodeVersion,
+  .packageManager,
+  .pmVersion
+}) AS envs
+WITH collect({
+  idx: idx,
+  memory: m {
+    .id,
+    .kind,
+    .polarity,
+    .title,
+    .content,
+    .tags,
+    .confidence,
+    .utility,
+    .triage,
+    .antiPattern,
+    .createdAt,
+    .updatedAt,
+    env: envs[0]
+  }
+}) AS rows
+UNWIND rows AS row
+WITH row
+ORDER BY row.idx
+RETURN collect(row.memory) AS memories;

package/dist/cypher/get_memory_graph.cypher

@@ -0,0 +1,85 @@
+// Parameters:
+// - $agentId: Agent id for RECALLS edges
+// - $memoryIds: Array of memory ids
+// - $includeNodes: Boolean to include node payloads
+WITH
+  coalesce($agentId, "") AS agentId,
+  [id IN coalesce($memoryIds, []) WHERE id IS NOT NULL AND id <> ""] AS ids,
+  coalesce($includeNodes, true) AS includeNodes
+
+CALL (ids, includeNodes) {
+  WITH ids, includeNodes
+  MATCH (m:Memory)
+  WHERE includeNodes = true AND m.id IN ids
+  OPTIONAL MATCH (m)-[:APPLIES_IN]->(e:EnvironmentFingerprint)
+  WITH m, collect(e {
+    .hash,
+    .os,
+    .distro,
+    .ci,
+    .container,
+    .filesystem,
+    .workspaceMount,
+    .nodeVersion,
+    .packageManager,
+    .pmVersion
+  }) AS envs
+  RETURN collect(m {
+    .id,
+    .kind,
+    .polarity,
+    .title,
+    .content,
+    .tags,
+    .confidence,
+    .utility,
+    .triage,
+    .antiPattern,
+    .createdAt,
+    .updatedAt,
+    env: envs[0]
+  }) AS nodes
+
+  UNION
+
+  WITH ids, includeNodes
+  WHERE includeNodes = false
+  RETURN [] AS nodes
+}
+
+CALL (ids, agentId) {
+  WITH ids, agentId
+  WHERE agentId IS NOT NULL AND agentId <> ""
+  MATCH (a:Agent {id: agentId})-[r:RECALLS]->(m:Memory)
+  WHERE m.id IN ids
+  RETURN collect({
+    source: a.id,
+    target: m.id,
+    kind: "recalls",
+    strength: r.strength,
+    evidence: r.evidence,
+    updatedAt: toString(r.updatedAt)
+  }) AS recallEdges
+
+  UNION
+
+  WITH ids, agentId
+  WHERE agentId IS NULL OR agentId = ""
+  RETURN [] AS recallEdges
+}
+
+CALL (ids) {
+  WITH ids
+  MATCH (m1:Memory)-[c:CO_USED_WITH]->(m2:Memory)
+  WHERE m1.id IN ids AND m2.id IN ids
+  RETURN collect({
+    source: m1.id,
+    target: m2.id,
+    kind: "co_used_with",
+    strength: c.strength,
+    evidence: c.evidence,
+    updatedAt: toString(c.updatedAt)
+  }) AS coUsedEdges
+}
+
+RETURN nodes, recallEdges + coUsedEdges AS edges;

package/dist/cypher/index.ts

@@ -21,4 +21,6 @@ export const cypher = {
   listMemories: loadCypher("list_memories.cypher"),
   relateConcepts: loadCypher("relate_concepts.cypher"),
   autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher"),
+  getMemoriesById: loadCypher("get_memories_by_id.cypher"),
+  getMemoryGraph: loadCypher("get_memory_graph.cypher"),
 };

package/dist/index.cjs

@@ -86,7 +86,9 @@ var cypher = {
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
   relateConcepts: loadCypher("relate_concepts.cypher"),
-  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher")
+  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher"),
+  getMemoriesById: loadCypher("get_memories_by_id.cypher"),
+  getMemoryGraph: loadCypher("get_memory_graph.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -146,6 +148,20 @@ function envHash(env) {
 function clamp01(x) {
   return Math.max(0, Math.min(1, x));
 }
+function parseJsonField(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function toDateString(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value?.toString === "function") return value.toString();
+  return String(value);
+}
 var DEFAULT_AUTO_RELATE = {
   enabled: true,
   minSharedTags: 2,
@@ -172,6 +188,23 @@ function toBetaEdge(raw) {
     updatedAt: raw?.updatedAt ?? null
   };
 }
+function toMemoryRecord(raw) {
+  return {
+    id: raw.id,
+    kind: raw.kind,
+    polarity: raw.polarity ?? "positive",
+    title: raw.title,
+    content: raw.content,
+    tags: raw.tags ?? [],
+    confidence: raw.confidence ?? 0.7,
+    utility: raw.utility ?? 0.2,
+    createdAt: toDateString(raw.createdAt),
+    updatedAt: toDateString(raw.updatedAt),
+    triage: parseJsonField(raw.triage),
+    antiPattern: parseJsonField(raw.antiPattern),
+    env: raw.env ?? void 0
+  };
+}
 function defaultPolicy(req) {
   return {
     minConfidence: req?.minConfidence ?? 0.65,
@@ -243,6 +276,8 @@ var MemoryService = class {
   cyListMemories = cypher.listMemories;
   cyRelateConcepts = cypher.relateConcepts;
   cyAutoRelateByTags = cypher.autoRelateByTags;
+  cyGetMemoriesById = cypher.getMemoriesById;
+  cyGetMemoryGraph = cypher.getMemoryGraph;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -528,6 +563,39 @@ ${m.content}`).join("");
       await session.close();
     }
   }
+  async getMemoriesById(args) {
+    const ids = [...new Set((args.ids ?? []).filter(Boolean))];
+    if (ids.length === 0) return [];
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyGetMemoriesById, { ids });
+      const memories = res.records[0]?.get("memories") ?? [];
+      return memories.map(toMemoryRecord);
+    } finally {
+      await session.close();
+    }
+  }
+  async getMemoryGraph(args) {
+    const ids = [...new Set((args.memoryIds ?? []).filter(Boolean))];
+    if (ids.length === 0) return { nodes: [], edges: [] };
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyGetMemoryGraph, {
+        agentId: args.agentId ?? null,
+        memoryIds: ids,
+        includeNodes: args.includeNodes ?? true
+      });
+      const record = res.records[0];
+      const nodesRaw = record?.get("nodes") ?? [];
+      const edges = record?.get("edges") ?? [];
+      return {
+        nodes: nodesRaw.map(toMemoryRecord),
+        edges
+      };
+    } finally {
+      await session.close();
+    }
+  }
   async listEpisodes(args = {}) {
     return this.listMemories({ ...args, kind: "episodic" });
   }
@@ -605,11 +673,11 @@ ${m.content}`).join("");
       y: yById.get(memoryId) ?? 0,
       w
     }));
-    if (items.length === 0) return;
+    if (items.length === 0) return { updated: [] };
     const session = this.client.session("WRITE");
     try {
       await session.run("MERGE (a:Agent {id:$id}) RETURN a", { id: fb.agentId });
-      await session.run(this.cyFeedbackBatch, {
+      const feedbackRes = await session.run(this.cyFeedbackBatch, {
         agentId: fb.agentId,
         nowIso,
         items,
@@ -617,6 +685,16 @@ ${m.content}`).join("");
         aMin: 1e-3,
         bMin: 1e-3
       });
+      const updated = feedbackRes.records.map((rec) => {
+        const raw = {
+          a: rec.get("a"),
+          b: rec.get("b"),
+          strength: rec.get("strength"),
+          evidence: rec.get("evidence"),
+          updatedAt: rec.get("updatedAt")
+        };
+        return { id: rec.get("id"), edge: toBetaEdge(raw) };
+      });
       const ids = [...used];
       const pairs = [];
       for (let i = 0; i < ids.length; i++) {
@@ -638,6 +716,7 @@ ${m.content}`).join("");
         });
       }
       this.emit({ type: "write", action: "feedback", meta: { agentId: fb.agentId, usedCount: used.size } });
+      return { updated };
     } finally {
       await session.close();
     }

package/dist/index.d.ts

@@ -21,6 +21,13 @@ interface DistilledInvariant {
     applicability?: string[];
     risks?: string[];
 }
+interface MemoryTriage {
+    symptoms: string[];
+    likelyCauses: string[];
+    verificationSteps?: string[];
+    fixSteps?: string[];
+    gotchas?: string[];
+}
 interface MemoryRecord {
     id: string;
     kind: MemoryKind;
@@ -32,6 +39,7 @@ interface MemoryRecord {
     utility: number;
     createdAt?: string;
     updatedAt?: string;
+    triage?: MemoryTriage;
     signals?: {
         symptoms?: string[];
         environment?: string[];
@@ -60,6 +68,18 @@ interface MemorySummary {
     createdAt?: string | null;
     updatedAt?: string | null;
 }
+interface MemoryGraphEdge {
+    source: string;
+    target: string;
+    kind: "recalls" | "co_used_with";
+    strength: number;
+    evidence: number;
+    updatedAt?: string | null;
+}
+interface MemoryGraphResponse {
+    nodes: MemoryRecord[];
+    edges: MemoryGraphEdge[];
+}
 interface CaseRecord {
     id: string;
     title: string;
@@ -92,6 +112,14 @@ interface ListMemoriesArgs {
     limit?: number;
     agentId?: string;
 }
+interface GetMemoriesByIdArgs {
+    ids: string[];
+}
+interface GetMemoryGraphArgs {
+    agentId?: string;
+    memoryIds: string[];
+    includeNodes?: boolean;
+}
 interface BetaEdge {
     a: number;
     b: number;
@@ -136,6 +164,12 @@ interface MemoryFeedback {
     metrics?: FeedbackMetrics;
     notes?: string;
 }
+interface MemoryFeedbackResult {
+    updated: Array<{
+        id: string;
+        edge: BetaEdge;
+    }>;
+}
 interface CaptureEpisodeArgs {
     agentId: string;
     runId: string;
@@ -163,13 +197,7 @@ interface LearningCandidate {
     confidence: number;
     signals?: MemoryRecord["signals"];
     env?: EnvironmentFingerprint;
-    triage?: {
-        symptoms: string[];
-        likelyCauses: string[];
-        verificationSteps?: string[];
-        fixSteps?: string[];
-        gotchas?: string[];
-    };
+    triage?: MemoryTriage;
     antiPattern?: MemoryRecord["antiPattern"];
 }
 interface SaveLearningRequest {
@@ -241,6 +269,8 @@ declare class MemoryService {
     private cyListMemories;
     private cyRelateConcepts;
     private cyAutoRelateByTags;
+    private cyGetMemoriesById;
+    private cyGetMemoryGraph;
     private cyGetRecallEdges;
     constructor(cfg: MemoryServiceConfig);
     init(): Promise<void>;
@@ -267,6 +297,8 @@ declare class MemoryService {
      */
     retrieveContextBundle(args: RetrieveContextArgs): Promise<ContextBundle>;
     listMemories(args?: ListMemoriesArgs): Promise<MemorySummary[]>;
+    getMemoriesById(args: GetMemoriesByIdArgs): Promise<MemoryRecord[]>;
+    getMemoryGraph(args: GetMemoryGraphArgs): Promise<MemoryGraphResponse>;
     listEpisodes(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
     listSkills(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
     listConcepts(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
@@ -281,7 +313,7 @@ declare class MemoryService {
      * Reinforce/degrade agent->memory association weights using a single batched Cypher query.
      * This supports mid-run retrieval by making feedback cheap and frequent.
      */
-    feedback(fb: MemoryFeedback): Promise<void>;
+    feedback(fb: MemoryFeedback): Promise<MemoryFeedbackResult>;
     /**
      * Save distilled learnings discovered during a task.
      * Enforces quality gates and stores negative memories explicitly.
@@ -320,6 +352,8 @@ declare const cypher: {
     listMemories: string;
     relateConcepts: string;
     autoRelateByTags: string;
+    getMemoriesById: string;
+    getMemoryGraph: string;
 };
 
 declare function createMemoryTools(service: MemoryService): MemoryToolSet;
@@ -330,4 +364,4 @@ declare function newId(prefix: string): string;
 declare function normaliseSymptom(s: string): string;
 declare function envHash(env: EnvironmentFingerprint): string;
 
-export { type AutoRelateConfig, type BetaEdge, type CaptureEpisodeArgs, type CaptureStepEpisodeArgs, type CaseRecord, type ContextBundle, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type LearningCandidate, type ListMemoriesArgs, type MemoryEvent, type MemoryFeedback, type MemoryKind, type MemoryPolarity, type MemoryRecord, MemoryService, type MemoryServiceConfig, type MemorySummary, type MemoryToolDefinition, type MemoryToolName, type MemoryToolSet, Neo4jClient, type Neo4jClientConfig, type RetrieveContextArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, createMemoryTools, cypher, ensureSchema, envHash, loadCypher, migrate, newId, normaliseSymptom, schemaVersion, sha256Hex };
+export { type AutoRelateConfig, type BetaEdge, type CaptureEpisodeArgs, type CaptureStepEpisodeArgs, type CaseRecord, type ContextBundle, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type GetMemoriesByIdArgs, type GetMemoryGraphArgs, type LearningCandidate, type ListMemoriesArgs, type MemoryEvent, type MemoryFeedback, type MemoryFeedbackResult, type MemoryGraphEdge, type MemoryGraphResponse, type MemoryKind, type MemoryPolarity, type MemoryRecord, MemoryService, type MemoryServiceConfig, type MemorySummary, type MemoryToolDefinition, type MemoryToolName, type MemoryToolSet, type MemoryTriage, Neo4jClient, type Neo4jClientConfig, type RetrieveContextArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, createMemoryTools, cypher, ensureSchema, envHash, loadCypher, migrate, newId, normaliseSymptom, schemaVersion, sha256Hex };

package/dist/index.js

@@ -36,7 +36,9 @@ var cypher = {
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
   relateConcepts: loadCypher("relate_concepts.cypher"),
-  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher")
+  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher"),
+  getMemoriesById: loadCypher("get_memories_by_id.cypher"),
+  getMemoryGraph: loadCypher("get_memory_graph.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -96,6 +98,20 @@ function envHash(env) {
 function clamp01(x) {
   return Math.max(0, Math.min(1, x));
 }
+function parseJsonField(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function toDateString(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value?.toString === "function") return value.toString();
+  return String(value);
+}
 var DEFAULT_AUTO_RELATE = {
   enabled: true,
   minSharedTags: 2,
@@ -122,6 +138,23 @@ function toBetaEdge(raw) {
     updatedAt: raw?.updatedAt ?? null
   };
 }
+function toMemoryRecord(raw) {
+  return {
+    id: raw.id,
+    kind: raw.kind,
+    polarity: raw.polarity ?? "positive",
+    title: raw.title,
+    content: raw.content,
+    tags: raw.tags ?? [],
+    confidence: raw.confidence ?? 0.7,
+    utility: raw.utility ?? 0.2,
+    createdAt: toDateString(raw.createdAt),
+    updatedAt: toDateString(raw.updatedAt),
+    triage: parseJsonField(raw.triage),
+    antiPattern: parseJsonField(raw.antiPattern),
+    env: raw.env ?? void 0
+  };
+}
 function defaultPolicy(req) {
   return {
     minConfidence: req?.minConfidence ?? 0.65,
@@ -193,6 +226,8 @@ var MemoryService = class {
   cyListMemories = cypher.listMemories;
   cyRelateConcepts = cypher.relateConcepts;
   cyAutoRelateByTags = cypher.autoRelateByTags;
+  cyGetMemoriesById = cypher.getMemoriesById;
+  cyGetMemoryGraph = cypher.getMemoryGraph;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -478,6 +513,39 @@ ${m.content}`).join("");
       await session.close();
     }
   }
+  async getMemoriesById(args) {
+    const ids = [...new Set((args.ids ?? []).filter(Boolean))];
+    if (ids.length === 0) return [];
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyGetMemoriesById, { ids });
+      const memories = res.records[0]?.get("memories") ?? [];
+      return memories.map(toMemoryRecord);
+    } finally {
+      await session.close();
+    }
+  }
+  async getMemoryGraph(args) {
+    const ids = [...new Set((args.memoryIds ?? []).filter(Boolean))];
+    if (ids.length === 0) return { nodes: [], edges: [] };
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyGetMemoryGraph, {
+        agentId: args.agentId ?? null,
+        memoryIds: ids,
+        includeNodes: args.includeNodes ?? true
+      });
+      const record = res.records[0];
+      const nodesRaw = record?.get("nodes") ?? [];
+      const edges = record?.get("edges") ?? [];
+      return {
+        nodes: nodesRaw.map(toMemoryRecord),
+        edges
+      };
+    } finally {
+      await session.close();
+    }
+  }
   async listEpisodes(args = {}) {
     return this.listMemories({ ...args, kind: "episodic" });
   }
@@ -555,11 +623,11 @@ ${m.content}`).join("");
       y: yById.get(memoryId) ?? 0,
       w
     }));
-    if (items.length === 0) return;
+    if (items.length === 0) return { updated: [] };
     const session = this.client.session("WRITE");
     try {
       await session.run("MERGE (a:Agent {id:$id}) RETURN a", { id: fb.agentId });
-      await session.run(this.cyFeedbackBatch, {
+      const feedbackRes = await session.run(this.cyFeedbackBatch, {
         agentId: fb.agentId,
         nowIso,
         items,
@@ -567,6 +635,16 @@ ${m.content}`).join("");
         aMin: 1e-3,
         bMin: 1e-3
       });
+      const updated = feedbackRes.records.map((rec) => {
+        const raw = {
+          a: rec.get("a"),
+          b: rec.get("b"),
+          strength: rec.get("strength"),
+          evidence: rec.get("evidence"),
+          updatedAt: rec.get("updatedAt")
+        };
+        return { id: rec.get("id"), edge: toBetaEdge(raw) };
+      });
       const ids = [...used];
       const pairs = [];
       for (let i = 0; i < ids.length; i++) {
@@ -588,6 +666,7 @@ ${m.content}`).join("");
         });
       }
       this.emit({ type: "write", action: "feedback", meta: { agentId: fb.agentId, usedCount: used.size } });
+      return { updated };
     } finally {
       await session.close();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo4j-agent-memory",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/dist/index.d.cts

@@ -1,246 +0,0 @@
-import { Session } from 'neo4j-driver';
-
-type MemoryKind = "semantic" | "procedural" | "episodic";
-type MemoryPolarity = "positive" | "negative";
-interface EnvironmentFingerprint {
-    hash?: string;
-    os?: "macos" | "linux" | "windows";
-    distro?: string;
-    ci?: string;
-    container?: boolean;
-    filesystem?: string;
-    workspaceMount?: "local" | "network" | "bind" | "readonly";
-    nodeVersion?: string;
-    packageManager?: "npm" | "pnpm" | "yarn";
-    pmVersion?: string;
-}
-interface DistilledInvariant {
-    invariant: string;
-    justification?: string;
-    verification?: string[];
-    applicability?: string[];
-    risks?: string[];
-}
-interface MemoryRecord {
-    id: string;
-    kind: MemoryKind;
-    polarity: MemoryPolarity;
-    title: string;
-    content: string;
-    tags: string[];
-    confidence: number;
-    utility: number;
-    createdAt?: string;
-    updatedAt?: string;
-    signals?: {
-        symptoms?: string[];
-        environment?: string[];
-    };
-    distilled?: {
-        invariants?: DistilledInvariant[];
-        steps?: string[];
-        verificationSteps?: string[];
-        gotchas?: string[];
-    };
-    antiPattern?: {
-        action: string;
-        whyBad: string;
-        saferAlternative?: string;
-    };
-    env?: EnvironmentFingerprint;
-}
-interface CaseRecord {
-    id: string;
-    title: string;
-    summary: string;
-    outcome: "resolved" | "unresolved" | "workaround";
-    symptoms: string[];
-    env: EnvironmentFingerprint;
-    resolvedByMemoryIds: string[];
-    negativeMemoryIds: string[];
-    resolvedAtIso?: string | null;
-}
-interface RetrieveContextArgs {
-    agentId: string;
-    prompt: string;
-    symptoms?: string[];
-    tags?: string[];
-    kinds?: MemoryKind[];
-    env?: EnvironmentFingerprint;
-    baseline?: Record<string, {
-        a: number;
-        b: number;
-    }>;
-    caseLimit?: number;
-    fixLimit?: number;
-    dontLimit?: number;
-    nowIso?: string;
-}
-interface BetaEdge {
-    a: number;
-    b: number;
-    /** Posterior mean a/(a+b), cached for query speed */
-    strength: number;
-    /** Evidence mass a+b, cached for query speed */
-    evidence: number;
-    updatedAt: string | null;
-}
-type ContextMemoryBase = Pick<MemoryRecord, "id" | "kind" | "polarity" | "title" | "content" | "tags" | "confidence" | "utility" | "updatedAt">;
-type ContextMemorySummary = ContextMemoryBase & {
-    /** Posterior snapshot before the current run (baseline) */
-    edgeBefore?: BetaEdge;
-    /** Posterior snapshot after the current run (undefined until feedback arrives) */
-    edgeAfter?: BetaEdge;
-};
-interface ContextBundle {
-    sessionId: string;
-    sections: {
-        fix: ContextMemorySummary[];
-        doNotDo: ContextMemorySummary[];
-    };
-    injection: {
-        fixBlock: string;
-        doNotDoBlock: string;
-    };
-}
-interface FeedbackMetrics {
-    durationMs?: number;
-    quality?: number;
-    hallucinationRisk?: number;
-    toolCalls?: number;
-    verificationPassed?: boolean;
-}
-interface MemoryFeedback {
-    agentId: string;
-    sessionId: string;
-    usedIds: string[];
-    usefulIds: string[];
-    notUsefulIds: string[];
-    preventedErrorIds?: string[];
-    metrics?: FeedbackMetrics;
-    notes?: string;
-}
-interface LearningCandidate {
-    kind: MemoryKind;
-    polarity?: MemoryPolarity;
-    title: string;
-    content: string;
-    tags: string[];
-    confidence: number;
-    signals?: MemoryRecord["signals"];
-    env?: EnvironmentFingerprint;
-    triage?: {
-        symptoms: string[];
-        likelyCauses: string[];
-        verificationSteps?: string[];
-        fixSteps?: string[];
-        gotchas?: string[];
-    };
-    antiPattern?: MemoryRecord["antiPattern"];
-}
-interface SaveLearningRequest {
-    agentId: string;
-    sessionId?: string;
-    taskId?: string;
-    learnings: LearningCandidate[];
-    policy?: {
-        minConfidence?: number;
-        requireVerificationSteps?: boolean;
-        maxItems?: number;
-    };
-}
-interface SaveLearningResult {
-    saved: Array<{
-        id: string;
-        kind: MemoryKind;
-        title: string;
-        deduped: boolean;
-    }>;
-    rejected: Array<{
-        title: string;
-        reason: string;
-    }>;
-}
-interface MemoryServiceConfig {
-    neo4j: {
-        uri: string;
-        username: string;
-        password: string;
-        database?: string;
-    };
-    vectorIndex?: string;
-    fulltextIndex?: string;
-    halfLifeSeconds?: number;
-}
-
-declare class MemoryService {
-    private client;
-    private vectorIndex;
-    private fulltextIndex;
-    private halfLifeSeconds;
-    private cyUpsertMemory;
-    private cyUpsertCase;
-    private cyRetrieveBundle;
-    private cyFeedbackBatch;
-    private cyFeedbackCoUsed;
-    private cyGetRecallEdges;
-    constructor(cfg: MemoryServiceConfig);
-    init(): Promise<void>;
-    close(): Promise<void>;
-    private ensureEnvHash;
-    /**
-     * Save a distilled memory (semantic/procedural/episodic) with exact dedupe by contentHash.
-     * NOTE: This package intentionally does not store "full answers" as semantic/procedural.
-     */
-    upsertMemory(l: LearningCandidate & {
-        id?: string;
-    }): Promise<{
-        id: string;
-        deduped: boolean;
-    }>;
-    /**
-     * Upsert an episodic Case (case-based reasoning) that links symptoms + env + resolved_by + negative memories.
-     */
-    upsertCase(c: CaseRecord): Promise<string>;
-    /**
-     * Retrieve a ContextBundle with separate Fix and Do-not-do sections, using case-based reasoning.
-     * The key idea: match cases by symptoms + env similarity, then pull linked memories.
-     */
-    retrieveContextBundle(args: RetrieveContextArgs): Promise<ContextBundle>;
-    /**
-     * Reinforce/degrade agent->memory association weights using a single batched Cypher query.
-     * This supports mid-run retrieval by making feedback cheap and frequent.
-     */
-    feedback(fb: MemoryFeedback): Promise<void>;
-    /**
-     * Save distilled learnings discovered during a task.
-     * Enforces quality gates and stores negative memories explicitly.
-     * Automatically creates a Case if learnings have triage.symptoms.
-     */
-    saveLearnings(req: SaveLearningRequest): Promise<SaveLearningResult>;
-}
-declare function createMemoryService(cfg: MemoryServiceConfig): Promise<MemoryService>;
-
-interface Neo4jClientConfig {
-    uri: string;
-    username: string;
-    password: string;
-    database?: string;
-}
-declare class Neo4jClient {
-    private driver;
-    private database?;
-    constructor(cfg: Neo4jClientConfig);
-    session(mode?: "READ" | "WRITE"): Session;
-    close(): Promise<void>;
-}
-
-declare function ensureSchema(client: Neo4jClient): Promise<void>;
-
-declare function sha256Hex(s: string): string;
-declare function canonicaliseForHash(title: string, content: string, tags: string[]): string;
-declare function newId(prefix: string): string;
-declare function normaliseSymptom(s: string): string;
-declare function envHash(env: EnvironmentFingerprint): string;
-
-export { type BetaEdge, type CaseRecord, type ContextBundle, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type LearningCandidate, type MemoryFeedback, type MemoryKind, type MemoryPolarity, type MemoryRecord, MemoryService, type MemoryServiceConfig, Neo4jClient, type Neo4jClientConfig, type RetrieveContextArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, ensureSchema, envHash, newId, normaliseSymptom, sha256Hex };