neo4j-agent-memory 0.3.19 → 0.4.1

package/README.md

@@ -35,7 +35,16 @@ const mem = await createMemoryService({
   neo4j: { uri, username, password },
   vectorIndex: "memoryEmbedding",
   fulltextIndex: "memoryText",
-  halfLifeSeconds: 30 * 24 * 3600
+  halfLifeSeconds: 30 * 24 * 3600,
+  autoRelate: {
+    enabled: true,
+    minSharedTags: 2,
+    minWeight: 0.2,
+    maxCandidates: 12,
+    sameKind: true,
+    samePolarity: true,
+    allowedKinds: ["semantic", "procedural"]
+  }
 });
 
 const bundle = await mem.retrieveContextBundle({
@@ -46,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),
@@ -60,6 +69,26 @@ 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`
+- `minSharedTags: 2`
+- `minWeight: 0.2`
+- `maxCandidates: 12`
+- `sameKind: true`
+- `samePolarity: true`
+- `allowedKinds: ["semantic", "procedural"]`
+
+Auto-relate behavior:
+- Uses tag overlap with Jaccard weight (`shared / (a + b - shared)`).
+- Runs only for newly inserted memories (skips deduped).
+- Applies filters for `sameKind`, `samePolarity`, and `allowedKinds`.
+- Requires `minSharedTags` and `minWeight` to pass before linking.
+- Limits to `maxCandidates` highest-weight neighbors.
+
+Performance note:
+- Auto-relate scans candidate memories with tag filtering; for large graphs, keep tags selective and consider tightening `maxCandidates` and `minSharedTags`.
 
 ## Tool adapter (createMemoryTools)
 
@@ -99,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/auto_relate_memory_by_tags.cypher

@@ -0,0 +1,45 @@
+// Parameters:
+// - $id: Source memory id
+// - $nowIso: ISO timestamp
+// - $minSharedTags: Minimum overlapping tags
+// - $minWeight: Minimum Jaccard weight to relate
+// - $maxCandidates: Max related memories to link
+// - $sameKind: Only relate to same kind if true
+// - $samePolarity: Only relate to same polarity if true
+// - $allowedKinds: Optional list of kinds to consider (empty = all)
+WITH datetime($nowIso) AS now
+MATCH (src:Memory {id: $id})
+WITH src, now, coalesce(src.tags, []) AS srcTags
+MATCH (m:Memory)
+WHERE m.id <> src.id
+  AND (NOT $sameKind OR m.kind = src.kind)
+  AND (NOT $samePolarity OR m.polarity = src.polarity)
+  AND (size($allowedKinds) = 0 OR m.kind IN $allowedKinds)
+WITH
+  src,
+  now,
+  srcTags,
+  m,
+  size([t IN srcTags WHERE t IN coalesce(m.tags, [])]) AS shared,
+  size(srcTags) AS aSize,
+  size(coalesce(m.tags, [])) AS bSize
+WHERE shared >= $minSharedTags
+WITH
+  src,
+  now,
+  m,
+  shared,
+  CASE
+    WHEN (aSize + bSize - shared) = 0 THEN 0.0
+    ELSE toFloat(shared) / (aSize + bSize - shared)
+  END AS weight
+WHERE weight >= $minWeight
+ORDER BY weight DESC, shared DESC
+LIMIT $maxCandidates
+MERGE (src)-[r:RELATED_TO]->(m)
+ON CREATE SET r.weight = weight, r.createdAt = now, r.updatedAt = now
+ON MATCH SET r.weight = weight, r.updatedAt = now
+MERGE (m)-[r2:RELATED_TO]->(src)
+ON CREATE SET r2.weight = weight, r2.createdAt = now, r2.updatedAt = now
+ON MATCH SET r2.weight = weight, r2.updatedAt = now
+RETURN count(*) AS related;

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

@@ -20,4 +20,7 @@ export const 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"),
+  getMemoriesById: loadCypher("get_memories_by_id.cypher"),
+  getMemoryGraph: loadCypher("get_memory_graph.cypher"),
 };

package/dist/cypher/schema.cypher

@@ -16,5 +16,8 @@ FOR (m:Memory) ON (m.polarity);
 CREATE INDEX memory_kind IF NOT EXISTS
 FOR (m:Memory) ON (m.kind);
 
+CREATE INDEX memory_tags IF NOT EXISTS
+FOR (m:Memory) ON (m.tags);
+
 CREATE CONSTRAINT agent_id_unique IF NOT EXISTS
 FOR (a:Agent) REQUIRE a.id IS UNIQUE;

package/dist/index.cjs

@@ -85,7 +85,10 @@ var cypher = {
   feedbackBatch: loadCypher("feedback_batch.cypher"),
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
-  relateConcepts: loadCypher("relate_concepts.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")
 };
 
 // src/neo4j/schema.ts
@@ -145,6 +148,31 @@ 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,
+  minWeight: 0.2,
+  maxCandidates: 12,
+  sameKind: true,
+  samePolarity: true,
+  allowedKinds: ["semantic", "procedural"]
+};
+var AUTO_RELATE_MIN_SHARED_TAGS = 1;
+var AUTO_RELATE_MIN_MAX_CANDIDATES = 1;
 function toBetaEdge(raw) {
   const aMin = 1e-3;
   const bMin = 1e-3;
@@ -160,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,
@@ -222,6 +267,7 @@ var MemoryService = class {
   fulltextIndex;
   halfLifeSeconds;
   onMemoryEvent;
+  autoRelateConfig;
   cyUpsertMemory = cypher.upsertMemory;
   cyUpsertCase = cypher.upsertCase;
   cyRetrieveBundle = cypher.retrieveContextBundle;
@@ -229,6 +275,9 @@ var MemoryService = class {
   cyFeedbackCoUsed = cypher.feedbackCoUsed;
   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})
@@ -246,6 +295,22 @@ var MemoryService = class {
     this.fulltextIndex = cfg.fulltextIndex ?? "memoryText";
     this.halfLifeSeconds = cfg.halfLifeSeconds ?? 30 * 24 * 3600;
     this.onMemoryEvent = cfg.onMemoryEvent;
+    const autoRelate = cfg.autoRelate ?? {};
+    this.autoRelateConfig = {
+      enabled: autoRelate.enabled ?? DEFAULT_AUTO_RELATE.enabled,
+      minSharedTags: Math.max(
+        AUTO_RELATE_MIN_SHARED_TAGS,
+        Math.floor(autoRelate.minSharedTags ?? DEFAULT_AUTO_RELATE.minSharedTags)
+      ),
+      minWeight: clamp01(autoRelate.minWeight ?? DEFAULT_AUTO_RELATE.minWeight),
+      maxCandidates: Math.max(
+        AUTO_RELATE_MIN_MAX_CANDIDATES,
+        Math.floor(autoRelate.maxCandidates ?? DEFAULT_AUTO_RELATE.maxCandidates)
+      ),
+      sameKind: autoRelate.sameKind ?? DEFAULT_AUTO_RELATE.sameKind,
+      samePolarity: autoRelate.samePolarity ?? DEFAULT_AUTO_RELATE.samePolarity,
+      allowedKinds: autoRelate.allowedKinds ?? [...DEFAULT_AUTO_RELATE.allowedKinds]
+    };
   }
   async init() {
     await ensureSchema(this.client);
@@ -330,6 +395,21 @@ var MemoryService = class {
           }
         );
       }
+      const autoRelate = this.autoRelateConfig;
+      const allowedKinds = autoRelate.allowedKinds ?? [];
+      const canAutoRelate = autoRelate.enabled && tags.length >= autoRelate.minSharedTags && (allowedKinds.length === 0 || allowedKinds.includes(l.kind));
+      if (canAutoRelate) {
+        await write.run(this.cyAutoRelateByTags, {
+          id,
+          nowIso: (/* @__PURE__ */ new Date()).toISOString(),
+          minSharedTags: autoRelate.minSharedTags,
+          minWeight: autoRelate.minWeight,
+          maxCandidates: autoRelate.maxCandidates,
+          sameKind: autoRelate.sameKind,
+          samePolarity: autoRelate.samePolarity,
+          allowedKinds
+        });
+      }
       this.emit({ type: "write", action: "upsertMemory", meta: { id } });
       return { id, deduped: false };
     } finally {
@@ -483,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" });
   }
@@ -560,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,
@@ -572,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++) {
@@ -593,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 {
@@ -195,6 +223,15 @@ interface SaveLearningResult {
         reason: string;
     }>;
 }
+interface AutoRelateConfig {
+    enabled?: boolean;
+    minSharedTags?: number;
+    minWeight?: number;
+    maxCandidates?: number;
+    sameKind?: boolean;
+    samePolarity?: boolean;
+    allowedKinds?: MemoryKind[];
+}
 interface MemoryServiceConfig {
     neo4j: {
         uri: string;
@@ -205,6 +242,7 @@ interface MemoryServiceConfig {
     vectorIndex?: string;
     fulltextIndex?: string;
     halfLifeSeconds?: number;
+    autoRelate?: AutoRelateConfig;
     onMemoryEvent?: (event: MemoryEvent) => void;
 }
 type MemoryToolName = "store_skill" | "store_pattern" | "store_concept" | "relate_concepts" | "recall_skills" | "recall_concepts" | "recall_patterns";
@@ -222,6 +260,7 @@ declare class MemoryService {
     private fulltextIndex;
     private halfLifeSeconds;
     private onMemoryEvent?;
+    private autoRelateConfig;
     private cyUpsertMemory;
     private cyUpsertCase;
     private cyRetrieveBundle;
@@ -229,6 +268,9 @@ declare class MemoryService {
     private cyFeedbackCoUsed;
     private cyListMemories;
     private cyRelateConcepts;
+    private cyAutoRelateByTags;
+    private cyGetMemoriesById;
+    private cyGetMemoryGraph;
     private cyGetRecallEdges;
     constructor(cfg: MemoryServiceConfig);
     init(): Promise<void>;
@@ -255,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[]>;
@@ -269,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.
@@ -307,6 +351,9 @@ declare const cypher: {
     feedbackCoUsed: string;
     listMemories: string;
     relateConcepts: string;
+    autoRelateByTags: string;
+    getMemoriesById: string;
+    getMemoryGraph: string;
 };
 
 declare function createMemoryTools(service: MemoryService): MemoryToolSet;
@@ -317,4 +364,4 @@ declare function newId(prefix: string): string;
 declare function normaliseSymptom(s: string): string;
 declare function envHash(env: EnvironmentFingerprint): string;
 
-export { 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

@@ -35,7 +35,10 @@ var cypher = {
   feedbackBatch: loadCypher("feedback_batch.cypher"),
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
-  relateConcepts: loadCypher("relate_concepts.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")
 };
 
 // src/neo4j/schema.ts
@@ -95,6 +98,31 @@ 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,
+  minWeight: 0.2,
+  maxCandidates: 12,
+  sameKind: true,
+  samePolarity: true,
+  allowedKinds: ["semantic", "procedural"]
+};
+var AUTO_RELATE_MIN_SHARED_TAGS = 1;
+var AUTO_RELATE_MIN_MAX_CANDIDATES = 1;
 function toBetaEdge(raw) {
   const aMin = 1e-3;
   const bMin = 1e-3;
@@ -110,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,
@@ -172,6 +217,7 @@ var MemoryService = class {
   fulltextIndex;
   halfLifeSeconds;
   onMemoryEvent;
+  autoRelateConfig;
   cyUpsertMemory = cypher.upsertMemory;
   cyUpsertCase = cypher.upsertCase;
   cyRetrieveBundle = cypher.retrieveContextBundle;
@@ -179,6 +225,9 @@ var MemoryService = class {
   cyFeedbackCoUsed = cypher.feedbackCoUsed;
   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})
@@ -196,6 +245,22 @@ var MemoryService = class {
     this.fulltextIndex = cfg.fulltextIndex ?? "memoryText";
     this.halfLifeSeconds = cfg.halfLifeSeconds ?? 30 * 24 * 3600;
     this.onMemoryEvent = cfg.onMemoryEvent;
+    const autoRelate = cfg.autoRelate ?? {};
+    this.autoRelateConfig = {
+      enabled: autoRelate.enabled ?? DEFAULT_AUTO_RELATE.enabled,
+      minSharedTags: Math.max(
+        AUTO_RELATE_MIN_SHARED_TAGS,
+        Math.floor(autoRelate.minSharedTags ?? DEFAULT_AUTO_RELATE.minSharedTags)
+      ),
+      minWeight: clamp01(autoRelate.minWeight ?? DEFAULT_AUTO_RELATE.minWeight),
+      maxCandidates: Math.max(
+        AUTO_RELATE_MIN_MAX_CANDIDATES,
+        Math.floor(autoRelate.maxCandidates ?? DEFAULT_AUTO_RELATE.maxCandidates)
+      ),
+      sameKind: autoRelate.sameKind ?? DEFAULT_AUTO_RELATE.sameKind,
+      samePolarity: autoRelate.samePolarity ?? DEFAULT_AUTO_RELATE.samePolarity,
+      allowedKinds: autoRelate.allowedKinds ?? [...DEFAULT_AUTO_RELATE.allowedKinds]
+    };
   }
   async init() {
     await ensureSchema(this.client);
@@ -280,6 +345,21 @@ var MemoryService = class {
           }
         );
       }
+      const autoRelate = this.autoRelateConfig;
+      const allowedKinds = autoRelate.allowedKinds ?? [];
+      const canAutoRelate = autoRelate.enabled && tags.length >= autoRelate.minSharedTags && (allowedKinds.length === 0 || allowedKinds.includes(l.kind));
+      if (canAutoRelate) {
+        await write.run(this.cyAutoRelateByTags, {
+          id,
+          nowIso: (/* @__PURE__ */ new Date()).toISOString(),
+          minSharedTags: autoRelate.minSharedTags,
+          minWeight: autoRelate.minWeight,
+          maxCandidates: autoRelate.maxCandidates,
+          sameKind: autoRelate.sameKind,
+          samePolarity: autoRelate.samePolarity,
+          allowedKinds
+        });
+      }
       this.emit({ type: "write", action: "upsertMemory", meta: { id } });
       return { id, deduped: false };
     } finally {
@@ -433,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" });
   }
@@ -510,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,
@@ -522,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++) {
@@ -543,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.3.19",
+  "version": "0.4.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",