neo4j-agent-memory 0.4.0 → 0.5.0

package/README.md

@@ -52,10 +52,16 @@ const bundle = await mem.retrieveContextBundle({
   prompt: "EACCES cannot create node_modules",
   symptoms: ["eacces", "permission denied", "node_modules"],
   tags: ["npm", "node_modules"],
-  env: { os: "macos", packageManager: "npm", container: false }
+  env: { os: "macos", packageManager: "npm", container: false },
+  fallback: {
+    enabled: true,
+    useFulltext: true,
+    useTags: true,
+    useVector: false,
+  },
 });
 
-await mem.feedback({
+const feedback = await mem.feedback({
   agentId: "auggie",
   sessionId: bundle.sessionId,
   usedIds: bundle.sections.fix.map((m) => m.id),
@@ -69,6 +75,9 @@ 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.
+- Neutral usage: pass `neutralIds` or `updateUnratedUsed: false` to avoid penalizing retrieved-but-unrated memories.
+- Fallback retrieval uses fulltext/tag (and optional vector) search; provide `fallback.embedding` when using vector indexes.
 
 Auto-relate config (defaults):
 - `enabled: true`
@@ -89,6 +98,21 @@ Auto-relate behavior:
 Performance note:
 - Auto-relate scans candidate memories with tag filtering; for large graphs, keep tags selective and consider tightening `maxCandidates` and `minSharedTags`.
 
+Neo4j Browser params (auto-relate by tags):
+
+```cypher
+:param nowIso => "2026-01-04T22:07:53.086Z";
+:param id => "mem_8cd773c2-208c-45ad-97ea-1b2337dca751";
+:param minSharedTags => 2;
+:param minWeight => 0.3;
+:param maxCandidates => 10;
+:param sameKind => false;
+:param samePolarity => false;
+:param allowedKinds => [];
+```
+
+Note: `:param` lines are only supported in Neo4j Browser; other runners should pass parameters via the driver.
+
 ## Tool adapter (createMemoryTools)
 
 Use the tool factory to preserve the existing tool surface used by the demo:
@@ -127,6 +151,42 @@ 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,
+  includeRelatedTo: true,
+});
+```
+
+List edges for analytics/audit:
+
+```ts
+const edges = await mem.listMemoryEdges({ limit: 500, minStrength: 0.2 });
+```
+
+Retrieve a bundle with graph edges in one call:
+
+```ts
+const bundleWithGraph = await mem.retrieveContextBundleWithGraph({
+  agentId: "auggie",
+  prompt: "EACCES cannot create node_modules",
+  tags: ["npm", "node_modules"],
+  includeRelatedTo: true,
+});
+```
+
 ## Episodic capture helpers
 
 ```ts
@@ -151,6 +211,38 @@ await mem.captureStepEpisode({
 });
 ```
 
+## Useful learning capture
+
+```ts
+await mem.captureUsefulLearning({
+  agentId: "auggie",
+  sessionId: "run-123",
+  useful: true,
+  learning: {
+    kind: "semantic",
+    title: "Avoid chmod 777 on node_modules",
+    content: "Use npm cache ownership fixes instead of chmod 777.",
+    tags: ["npm", "permissions"],
+    confidence: 0.8,
+    utility: 0.3,
+  },
+});
+```
+
+## Case helpers
+
+```ts
+await mem.createCase({
+  title: "npm EACCES",
+  summary: "Permission denied on cache directory.",
+  outcome: "resolved",
+  symptoms: ["eacces", "permission denied"],
+  env: { os: "macos", packageManager: "npm" },
+  resolvedByMemoryIds: ["mem-1"],
+  negativeMemoryIds: [],
+});
+```
+
 ## Event hooks
 
 Provide an `onMemoryEvent` callback to observe reads/writes:

package/dist/cypher/auto_relate_memory_by_tags.cypher

@@ -7,6 +7,15 @@
 // - $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)
+// Neo4j Browser params (example only):
+// :param nowIso => "2026-01-04T22:07:53.086Z";
+// :param id => "mem_8cd773c2-208c-45ad-97ea-1b2337dca751";
+// :param minSharedTags => 2;
+// :param minWeight => 0.3;
+// :param maxCandidates => 10;
+// :param sameKind => false;
+// :param samePolarity => false;
+// :param allowedKinds => [];
 WITH datetime($nowIso) AS now
 MATCH (src:Memory {id: $id})
 WITH src, now, coalesce(src.tags, []) AS srcTags

package/dist/cypher/fallback_retrieve_memories.cypher

@@ -0,0 +1,68 @@
+// Parameters:
+// - $prompt: Query text
+// - $tags: Array of tags
+// - $kinds: Optional kinds filter
+// - $fulltextIndex: Fulltext index name
+// - $vectorIndex: Vector index name
+// - $embedding: Optional embedding vector
+// - $useFulltext: boolean
+// - $useVector: boolean
+// - $useTags: boolean
+// - $fixLimit: number
+// - $dontLimit: number
+WITH
+  coalesce($prompt, "") AS prompt,
+  coalesce($tags, []) AS tags,
+  coalesce($kinds, []) AS kinds,
+  coalesce($fulltextIndex, "") AS fulltextIndex,
+  coalesce($vectorIndex, "") AS vectorIndex,
+  $embedding AS embedding,
+  coalesce($useFulltext, true) AS useFulltext,
+  coalesce($useVector, false) AS useVector,
+  coalesce($useTags, true) AS useTags,
+  coalesce($fixLimit, 8) AS fixLimit,
+  coalesce($dontLimit, 6) AS dontLimit
+
+CALL {
+  WITH useFulltext, fulltextIndex, prompt
+  WHERE useFulltext = true AND fulltextIndex <> "" AND prompt <> ""
+  CALL db.index.fulltext.queryNodes(fulltextIndex, prompt) YIELD node, score
+  RETURN node AS m, score AS score
+
+  UNION
+
+  WITH useTags, tags
+  WHERE useTags = true AND size(tags) > 0
+  MATCH (m:Memory)
+  WHERE any(t IN tags WHERE t IN coalesce(m.tags, []))
+  RETURN m, 0.1 AS score
+
+  UNION
+
+  WITH useVector, vectorIndex, embedding
+  WHERE useVector = true AND vectorIndex <> "" AND embedding IS NOT NULL
+  CALL db.index.vector.queryNodes(vectorIndex, embedding, 20) YIELD node, score
+  RETURN node AS m, score AS score
+}
+WITH m, max(score) AS score, kinds, fixLimit, dontLimit
+WHERE m IS NOT NULL AND (size(kinds) = 0 OR m.kind IN kinds)
+WITH m, score, fixLimit, dontLimit
+ORDER BY score DESC, m.updatedAt DESC
+
+WITH collect(m {
+  .id,
+  .kind,
+  .polarity,
+  .title,
+  .content,
+  .tags,
+  .confidence,
+  .utility,
+  .updatedAt
+}) AS rows, fixLimit, dontLimit
+
+WITH
+  [m IN rows WHERE m.polarity <> "negative"][0..fixLimit] AS fixes,
+  [m IN rows WHERE m.polarity = "negative"][0..dontLimit] AS doNot
+
+RETURN { fixes: fixes, doNot: doNot } AS sections;

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,108 @@
+// Parameters:
+// - $agentId: Agent id for RECALLS edges
+// - $memoryIds: Array of memory ids
+// - $includeNodes: Boolean to include node payloads
+// - $includeRelatedTo: Boolean to include RELATED_TO edges
+WITH
+  coalesce($agentId, "") AS agentId,
+  [id IN coalesce($memoryIds, []) WHERE id IS NOT NULL AND id <> ""] AS ids,
+  coalesce($includeNodes, true) AS includeNodes,
+  coalesce($includeRelatedTo, false) AS includeRelatedTo
+
+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
+}
+
+CALL (ids, includeRelatedTo) {
+  WITH ids, includeRelatedTo
+  WHERE includeRelatedTo = true
+  MATCH (m1:Memory)-[r:RELATED_TO]->(m2:Memory)
+  WHERE m1.id IN ids AND m2.id IN ids
+  RETURN collect({
+    source: m1.id,
+    target: m2.id,
+    kind: "related_to",
+    strength: r.weight,
+    evidence: 0.0,
+    updatedAt: toString(r.updatedAt)
+  }) AS relatedEdges
+
+  UNION
+
+  WITH ids, includeRelatedTo
+  WHERE includeRelatedTo = false
+  RETURN [] AS relatedEdges
+}
+
+RETURN nodes, recallEdges + coUsedEdges + relatedEdges AS edges;

package/dist/cypher/index.ts

@@ -21,4 +21,8 @@ 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"),
+  fallbackRetrieveMemories: loadCypher("fallback_retrieve_memories.cypher"),
+  listMemoryEdges: loadCypher("list_memory_edges.cypher"),
 };

package/dist/cypher/list_memory_edges.cypher

@@ -0,0 +1,37 @@
+// Parameters:
+// - $limit: Max edges to return
+// - $minStrength: Minimum strength threshold
+WITH
+  coalesce($limit, 200) AS limit,
+  coalesce($minStrength, 0.0) AS minStrength
+
+CALL {
+  WITH minStrength
+  MATCH (m1:Memory)-[c:CO_USED_WITH]->(m2:Memory)
+  WHERE coalesce(c.strength, 0.0) >= minStrength
+  RETURN {
+    source: m1.id,
+    target: m2.id,
+    kind: "co_used_with",
+    strength: c.strength,
+    evidence: c.evidence,
+    updatedAt: toString(c.updatedAt)
+  } AS edge
+
+  UNION
+
+  WITH minStrength
+  MATCH (m1:Memory)-[r:RELATED_TO]->(m2:Memory)
+  WHERE coalesce(r.weight, 0.0) >= minStrength
+  RETURN {
+    source: m1.id,
+    target: m2.id,
+    kind: "related_to",
+    strength: r.weight,
+    evidence: 0.0,
+    updatedAt: toString(r.updatedAt)
+  } AS edge
+}
+WITH edge, limit
+ORDER BY edge.strength DESC
+RETURN collect(edge)[0..limit] AS edges;