neo4j-agent-memory 0.3.17

package/README.md

@@ -0,0 +1,161 @@
+# neo4j-agent-memory
+
+A Neo4j-backed memory system for AI agents:
+- semantic / procedural / episodic memories
+- case-based reasoning (symptoms -> similar cases -> fixes)
+- negative memories ("do not do")
+- environment fingerprints for precision
+- hybrid retrieval returning a ContextBundle with separate Fix / Do-not-do blocks
+- feedback API to reinforce / degrade association weights (agent affinity)
+
+## Install (npm)
+
+```bash
+npm install neo4j-agent-memory
+```
+
+## Requirements
+
+Hard requirements:
+- Node.js 18+
+- Neo4j 5+
+- Windows, macOS, or Linux
+
+Minimal requirements (tested):
+- Neo4j Desktop 2.1.1 (macOS) with a Neo4j 5.x database
+- Neo4j Browser + Bolt enabled
+- Download: https://neo4j.com/download-thanks-desktop/?edition=desktop&flavour=osx&release=2.1.1&offline=false
+
+## Core API
+
+```ts
+import { createMemoryService } from "neo4j-agent-memory";
+
+const mem = await createMemoryService({
+  neo4j: { uri, username, password },
+  vectorIndex: "memoryEmbedding",
+  fulltextIndex: "memoryText",
+  halfLifeSeconds: 30 * 24 * 3600
+});
+
+const bundle = await mem.retrieveContextBundle({
+  agentId: "auggie",
+  prompt: "EACCES cannot create node_modules",
+  symptoms: ["eacces", "permission denied", "node_modules"],
+  tags: ["npm", "node_modules"],
+  env: { os: "macos", packageManager: "npm", container: false }
+});
+
+await mem.feedback({
+  agentId: "auggie",
+  sessionId: bundle.sessionId,
+  usedIds: bundle.sections.fix.map((m) => m.id),
+  usefulIds: bundle.sections.fix.slice(0, 2).map((m) => m.id),
+  notUsefulIds: []
+});
+
+await mem.close();
+```
+
+Notes:
+- `createMemoryService` runs schema setup on init.
+- Cypher assets are bundled at `dist/cypher` in the published package.
+
+## Tool adapter (createMemoryTools)
+
+Use the tool factory to preserve the existing tool surface used by the demo:
+
+```ts
+import { createMemoryService, createMemoryTools } from "neo4j-agent-memory";
+
+const mem = await createMemoryService({ neo4j: { uri, username, password } });
+const tools = createMemoryTools(mem);
+
+await tools.store_skill.execute({
+  agentId: "auggie",
+  title: "Fix npm EACCES on macOS",
+  content: "If npm fails with EACCES, chown the cache directory and retry.",
+  tags: ["npm", "macos", "permissions"],
+});
+```
+
+Tool names:
+- `store_skill`
+- `store_pattern`
+- `store_concept`
+- `relate_concepts`
+- `recall_skills`
+- `recall_concepts`
+- `recall_patterns`
+
+## Stored UI APIs
+
+List summaries for the UI without legacy Cypher:
+
+```ts
+const all = await mem.listMemories({ limit: 50 });
+const episodes = await mem.listEpisodes({ agentId: "auggie" });
+const skills = await mem.listSkills({ agentId: "auggie" });
+const concepts = await mem.listConcepts({ agentId: "auggie" });
+```
+
+## Episodic capture helpers
+
+```ts
+await mem.captureEpisode({
+  agentId: "auggie",
+  runId: "run-123",
+  workflowName: "triage",
+  prompt: "Why is npm failing?",
+  response: "We found a permissions issue.",
+  outcome: "success",
+  tags: ["npm", "triage"],
+});
+
+await mem.captureStepEpisode({
+  agentId: "auggie",
+  runId: "run-123",
+  workflowName: "triage",
+  stepName: "fix",
+  prompt: "Apply the fix",
+  response: "Ran chown and reinstalled.",
+  outcome: "success",
+});
+```
+
+## Event hooks
+
+Provide an `onMemoryEvent` callback to observe reads/writes:
+
+```ts
+const mem = await createMemoryService({
+  neo4j: { uri, username, password },
+  onMemoryEvent: (event) => {
+    console.log(`[memory:${event.type}] ${event.action}`, event.meta);
+  },
+});
+```
+
+## Schema + cypher exports
+
+Schema helpers and cypher assets are exported for integrations:
+
+```ts
+import { ensureSchema, schemaVersion, migrate, cypher } from "neo4j-agent-memory";
+```
+
+## Intended usage (demo + API)
+
+This package is used by the demo API in this repository to:
+- retrieve a ContextBundle mid-run (`/memory/retrieve`)
+- send feedback (`/memory/feedback`)
+- save distilled learnings (`/memory/save`)
+
+See the repo for the demo API and UI:
+https://github.com/emmett08/neo4j-agent-memory-demo
+
+## Reinforcement model
+
+Edges `RECALLS` and `CO_USED_WITH` are updated using a decayed Beta posterior
+(a, b pseudo-counts with exponential forgetting). `strength` is cached as
+a/(a+b) and `evidence` as a+b.

package/dist/cypher/feedback_batch.cypher

@@ -0,0 +1,42 @@
+WITH datetime($nowIso) AS now
+UNWIND $items AS item
+MATCH (a:Agent {id: $agentId})
+MATCH (m:Memory {id: item.memoryId})
+MERGE (a)-[r:RECALLS]->(m)
+ON CREATE SET
+  r.a = 1.0,
+  r.b = 1.0,
+  r.updatedAt = now,
+  r.uses = 0,
+  r.successes = 0,
+  r.failures = 0
+
+WITH now, r, item,
+     // elapsed seconds, safe
+     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, item,
+     0.5 ^ (dt / $halfLifeSeconds) AS gamma,
+     coalesce(r.a, CASE WHEN $aMin > coalesce(r.strength, 0.5) * 2.0 THEN $aMin ELSE coalesce(r.strength, 0.5) * 2.0 END) AS aPrev,
+     coalesce(r.b, CASE WHEN $bMin > (1.0 - coalesce(r.strength, 0.5)) * 2.0 THEN $bMin ELSE (1.0 - coalesce(r.strength, 0.5)) * 2.0 END) AS bPrev
+
+WITH now, r, item, gamma,
+     ($aMin + gamma * (aPrev - $aMin)) AS a0,
+     ($bMin + gamma * (bPrev - $bMin)) AS b0
+
+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,
+    r.strength = a1 / (a1 + b1),
+    r.evidence = a1 + b1,
+    r.updatedAt = now,
+    r.uses = coalesce(r.uses,0) + 1,
+    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;

package/dist/cypher/feedback_co_used_with_batch.cypher

@@ -0,0 +1,34 @@
+WITH datetime($nowIso) AS now
+UNWIND $pairs AS pair
+MATCH (m1:Memory {id: pair.a})
+MATCH (m2:Memory {id: pair.b})
+MERGE (m1)-[c:CO_USED_WITH]->(m2)
+ON CREATE SET
+  c.a = 1.0,
+  c.b = 1.0,
+  c.updatedAt = now
+
+WITH now, c, pair,
+     CASE WHEN duration.inSeconds(coalesce(c.updatedAt, now), now).seconds > 0
+          THEN duration.inSeconds(coalesce(c.updatedAt, now), now).seconds
+          ELSE 0 END AS dt
+WITH now, c, pair,
+     0.5 ^ (dt / $halfLifeSeconds) AS gamma,
+     coalesce(c.a, CASE WHEN $aMin > coalesce(c.strength, 0.5) * 2.0 THEN $aMin ELSE coalesce(c.strength, 0.5) * 2.0 END) AS aPrev,
+     coalesce(c.b, CASE WHEN $bMin > (1.0 - coalesce(c.strength, 0.5)) * 2.0 THEN $bMin ELSE (1.0 - coalesce(c.strength, 0.5)) * 2.0 END) AS bPrev
+
+WITH now, c, pair, gamma,
+     ($aMin + gamma * (aPrev - $aMin)) AS a0,
+     ($bMin + gamma * (bPrev - $bMin)) AS b0
+
+WITH now, c, pair,
+     (a0 + pair.w * pair.y) AS a1,
+     (b0 + pair.w * (1.0 - pair.y)) AS b1
+
+SET c.a = a1,
+    c.b = b1,
+    c.strength = a1 / (a1 + b1),
+    c.evidence = a1 + b1,
+    c.updatedAt = now
+
+RETURN count(*) AS updated;

package/dist/cypher/index.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+declare const __dirname: string | undefined;
+
+const resolvedDir = typeof __dirname === "string" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+const baseDir = path.basename(resolvedDir) === "cypher" ? resolvedDir : path.resolve(resolvedDir, "cypher");
+
+export function loadCypher(rel: string): string {
+  return readFileSync(path.resolve(baseDir, rel), "utf8");
+}
+
+export const cypher = {
+  schema: loadCypher("schema.cypher"),
+  upsertMemory: loadCypher("upsert_memory.cypher"),
+  upsertCase: loadCypher("upsert_case.cypher"),
+  retrieveContextBundle: loadCypher("retrieve_context_bundle.cypher"),
+  feedbackBatch: loadCypher("feedback_batch.cypher"),
+  feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
+  listMemories: loadCypher("list_memories.cypher"),
+  relateConcepts: loadCypher("relate_concepts.cypher"),
+};

package/dist/cypher/list_memories.cypher

@@ -0,0 +1,39 @@
+// Parameters:
+// - $kind: Optional memory kind filter ("semantic" | "procedural" | "episodic")
+// - $limit: Max number of memories to return
+// - $agentId: Optional agent id to filter by RECALLS edges
+WITH
+  $kind AS kind,
+  coalesce($limit, 50) AS limit,
+  $agentId AS agentId
+
+CALL {
+  WITH kind, agentId
+  WITH kind, agentId
+  WHERE agentId IS NOT NULL AND agentId <> ""
+  MATCH (:Agent {id: agentId})-[:RECALLS]->(m:Memory)
+  WHERE kind IS NULL OR m.kind = kind
+  RETURN m
+  UNION
+  WITH kind, agentId
+  WHERE agentId IS NULL OR agentId = ""
+  MATCH (m:Memory)
+  WHERE kind IS NULL OR m.kind = kind
+  RETURN m
+}
+WITH m
+ORDER BY m.updatedAt DESC
+WITH collect(
+  m {
+    .id,
+    .kind,
+    .polarity,
+    .title,
+    .tags,
+    .confidence,
+    .utility,
+    .createdAt,
+    .updatedAt
+  }
+) AS rows, limit
+RETURN rows[0..limit] AS memories;

package/dist/cypher/relate_concepts.cypher

@@ -0,0 +1,13 @@
+// Parameters:
+// - $a: Memory id (concept A)
+// - $b: Memory id (concept B)
+// - $weight: Optional relationship weight
+MATCH (a:Memory {id: $a})
+MATCH (b:Memory {id: $b})
+MERGE (a)-[r:RELATED_TO]->(b)
+ON CREATE SET r.weight = $weight, r.createdAt = datetime(), r.updatedAt = datetime()
+ON MATCH SET r.weight = $weight, r.updatedAt = datetime()
+MERGE (b)-[r2:RELATED_TO]->(a)
+ON CREATE SET r2.weight = $weight, r2.createdAt = datetime(), r2.updatedAt = datetime()
+ON MATCH SET r2.weight = $weight, r2.updatedAt = datetime()
+RETURN a.id AS aId, b.id AS bId;