neo4j-agent-memory 0.4.1 → 0.5.0

package/README.md

@@ -52,7 +52,13 @@ 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,
+  },
 });
 
 const feedback = await mem.feedback({
@@ -69,7 +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.
+- `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`
@@ -90,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:
@@ -143,6 +166,24 @@ 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,
 });
 ```
 
@@ -170,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/get_memory_graph.cypher

@@ -2,10 +2,12 @@
 // - $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($includeNodes, true) AS includeNodes,
+  coalesce($includeRelatedTo, false) AS includeRelatedTo
 
 CALL (ids, includeNodes) {
   WITH ids, includeNodes
@@ -82,4 +84,25 @@ CALL (ids) {
   }) AS coUsedEdges
 }
 
-RETURN nodes, recallEdges + coUsedEdges AS edges;
+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

@@ -23,4 +23,6 @@ export const 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;

package/dist/index.cjs

@@ -88,7 +88,9 @@ var 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")
+  getMemoryGraph: loadCypher("get_memory_graph.cypher"),
+  fallbackRetrieveMemories: loadCypher("fallback_retrieve_memories.cypher"),
+  listMemoryEdges: loadCypher("list_memory_edges.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -278,6 +280,8 @@ var MemoryService = class {
   cyAutoRelateByTags = cypher.autoRelateByTags;
   cyGetMemoriesById = cypher.getMemoriesById;
   cyGetMemoryGraph = cypher.getMemoryGraph;
+  cyFallbackRetrieve = cypher.fallbackRetrieveMemories;
+  cyListMemoryEdges = cypher.listMemoryEdges;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -365,7 +369,7 @@ var MemoryService = class {
         contentHash,
         tags,
         confidence: clamp01(l.confidence),
-        utility: 0.2,
+        utility: typeof l.utility === "number" ? clamp01(l.utility) : 0.2,
         // start modest; reinforce via feedback
         triage: l.triage ? JSON.stringify(l.triage) : null,
         antiPattern: l.antiPattern ? JSON.stringify(l.antiPattern) : null
@@ -442,6 +446,13 @@ var MemoryService = class {
       await session.close();
     }
   }
+  /**
+   * Create a new Case with an auto-generated id if none is provided.
+   */
+  async createCase(c) {
+    const id = c.id ?? newId("case");
+    return this.upsertCase({ ...c, id });
+  }
   /**
    * 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.
@@ -467,28 +478,49 @@ var MemoryService = class {
         halfLifeSeconds: this.halfLifeSeconds
       });
       const sections = r.records[0].get("sections");
-      const fixes = (sections.fixes ?? []).map((m) => ({
-        id: m.id,
-        kind: m.kind,
-        polarity: m.polarity ?? "positive",
-        title: m.title,
-        content: m.content,
-        tags: m.tags ?? [],
-        confidence: m.confidence ?? 0.7,
-        utility: m.utility ?? 0.2,
-        updatedAt: m.updatedAt?.toString?.() ?? null
-      }));
-      const doNot = (sections.doNot ?? []).map((m) => ({
+      const mapSummary = (m, fallbackPolarity) => ({
         id: m.id,
         kind: m.kind,
-        polarity: m.polarity ?? "negative",
+        polarity: m.polarity ?? fallbackPolarity,
         title: m.title,
         content: m.content,
         tags: m.tags ?? [],
         confidence: m.confidence ?? 0.7,
         utility: m.utility ?? 0.2,
         updatedAt: m.updatedAt?.toString?.() ?? null
-      }));
+      });
+      let fixes = (sections.fixes ?? []).map((m) => mapSummary(m, "positive"));
+      let doNot = (sections.doNot ?? []).map((m) => mapSummary(m, "negative"));
+      const fallback = args.fallback ?? {};
+      const shouldFallback = fallback.enabled === true && fixes.length === 0 && doNot.length === 0;
+      if (shouldFallback) {
+        const fallbackFixLimit = fallback.limit ?? fixLimit;
+        const fallbackDontLimit = fallback.limit ?? dontLimit;
+        try {
+          const fallbackRes = await session.run(this.cyFallbackRetrieve, {
+            prompt: args.prompt ?? "",
+            tags: args.tags ?? [],
+            kinds: args.kinds ?? [],
+            fulltextIndex: this.fulltextIndex,
+            vectorIndex: this.vectorIndex,
+            embedding: fallback.embedding ?? null,
+            useFulltext: fallback.useFulltext ?? true,
+            useVector: fallback.useVector ?? false,
+            useTags: fallback.useTags ?? true,
+            fixLimit: fallbackFixLimit,
+            dontLimit: fallbackDontLimit
+          });
+          const fbSections = fallbackRes.records[0]?.get("sections");
+          fixes = (fbSections?.fixes ?? []).map((m) => mapSummary(m, "positive"));
+          doNot = (fbSections?.doNot ?? []).map((m) => mapSummary(m, "negative"));
+        } catch (err) {
+          this.emit({
+            type: "read",
+            action: "retrieveContextBundle.fallbackError",
+            meta: { message: err instanceof Error ? err.message : String(err) }
+          });
+        }
+      }
       const allIds = [.../* @__PURE__ */ new Set([...fixes.map((x) => x.id), ...doNot.map((x) => x.id)])];
       const edgeAfter = /* @__PURE__ */ new Map();
       if (allIds.length > 0) {
@@ -583,7 +615,8 @@ ${m.content}`).join("");
       const res = await session.run(this.cyGetMemoryGraph, {
         agentId: args.agentId ?? null,
         memoryIds: ids,
-        includeNodes: args.includeNodes ?? true
+        includeNodes: args.includeNodes ?? true,
+        includeRelatedTo: args.includeRelatedTo ?? false
       });
       const record = res.records[0];
       const nodesRaw = record?.get("nodes") ?? [];
@@ -596,6 +629,32 @@ ${m.content}`).join("");
       await session.close();
     }
   }
+  async listMemoryEdges(args = {}) {
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyListMemoryEdges, {
+        limit: args.limit ?? 200,
+        minStrength: args.minStrength ?? 0
+      });
+      return res.records[0]?.get("edges") ?? [];
+    } finally {
+      await session.close();
+    }
+  }
+  async retrieveContextBundleWithGraph(args) {
+    const bundle = await this.retrieveContextBundle(args);
+    const ids = [
+      ...bundle.sections.fix.map((m) => m.id),
+      ...bundle.sections.doNotDo.map((m) => m.id)
+    ];
+    const graph = await this.getMemoryGraph({
+      agentId: args.agentId,
+      memoryIds: ids,
+      includeNodes: args.includeNodes ?? false,
+      includeRelatedTo: args.includeRelatedTo ?? false
+    });
+    return { bundle, graph };
+  }
   async listEpisodes(args = {}) {
     return this.listMemories({ ...args, kind: "episodic" });
   }
@@ -626,6 +685,22 @@ ${m.content}`).join("");
     this.emit({ type: "write", action: "captureEpisode", meta: { runId: args.runId, title } });
     return result;
   }
+  async captureUsefulLearning(args) {
+    if (args.useful === false) {
+      return { saved: [], rejected: [{ title: args.learning.title, reason: "not marked useful" }] };
+    }
+    const result = await this.saveLearnings({
+      agentId: args.agentId,
+      sessionId: args.sessionId,
+      learnings: [args.learning]
+    });
+    this.emit({
+      type: "write",
+      action: "captureUsefulLearning",
+      meta: { title: args.learning.title, savedCount: result.saved.length }
+    });
+    return result;
+  }
   async captureStepEpisode(args) {
     const title = `Episode ${args.workflowName} - ${args.stepName}`;
     const base = {
@@ -655,18 +730,34 @@ ${m.content}`).join("");
     const used = new Set(fb.usedIds ?? []);
     const useful = new Set(fb.usefulIds ?? []);
     const notUseful = new Set(fb.notUsefulIds ?? []);
+    const neutral = new Set(fb.neutralIds ?? []);
     const prevented = new Set(fb.preventedErrorIds ?? []);
+    const updateUnratedUsed = fb.updateUnratedUsed ?? true;
     for (const id of prevented) useful.add(id);
     for (const id of useful) notUseful.delete(id);
+    for (const id of neutral) notUseful.delete(id);
     for (const id of useful) used.add(id);
     for (const id of notUseful) used.add(id);
+    for (const id of neutral) used.add(id);
     const quality = clamp01(fb.metrics?.quality ?? 0.7);
     const hallucRisk = clamp01(fb.metrics?.hallucinationRisk ?? 0.2);
     const baseY = clamp01(quality - 0.7 * hallucRisk);
     const w = 0.5 + 1.5 * quality;
     const yById = /* @__PURE__ */ new Map();
     for (const id of used) {
-      yById.set(id, useful.has(id) ? baseY : 0);
+      if (useful.has(id)) {
+        yById.set(id, baseY);
+        continue;
+      }
+      if (notUseful.has(id)) {
+        yById.set(id, 0);
+        continue;
+      }
+      if (neutral.has(id) || !updateUnratedUsed) {
+        yById.set(id, 0.5);
+        continue;
+      }
+      yById.set(id, 0);
     }
     const items = [...used].map((memoryId) => ({
       memoryId,

package/dist/index.d.ts

@@ -71,7 +71,7 @@ interface MemorySummary {
 interface MemoryGraphEdge {
     source: string;
     target: string;
-    kind: "recalls" | "co_used_with";
+    kind: "recalls" | "co_used_with" | "related_to";
     strength: number;
     evidence: number;
     updatedAt?: string | null;
@@ -106,6 +106,14 @@ interface RetrieveContextArgs {
     fixLimit?: number;
     dontLimit?: number;
     nowIso?: string;
+    fallback?: {
+        enabled?: boolean;
+        limit?: number;
+        useFulltext?: boolean;
+        useVector?: boolean;
+        useTags?: boolean;
+        embedding?: number[];
+    };
 }
 interface ListMemoriesArgs {
     kind?: MemoryKind;
@@ -119,6 +127,7 @@ interface GetMemoryGraphArgs {
     agentId?: string;
     memoryIds: string[];
     includeNodes?: boolean;
+    includeRelatedTo?: boolean;
 }
 interface BetaEdge {
     a: number;
@@ -160,6 +169,8 @@ interface MemoryFeedback {
     usedIds: string[];
     usefulIds: string[];
     notUsefulIds: string[];
+    neutralIds?: string[];
+    updateUnratedUsed?: boolean;
     preventedErrorIds?: string[];
     metrics?: FeedbackMetrics;
     notes?: string;
@@ -170,6 +181,34 @@ interface MemoryFeedbackResult {
         edge: BetaEdge;
     }>;
 }
+interface ListMemoryEdgesArgs {
+    limit?: number;
+    minStrength?: number;
+}
+interface MemoryEdgeExport {
+    source: string;
+    target: string;
+    kind: "co_used_with" | "related_to";
+    strength: number;
+    evidence: number;
+    updatedAt?: string | null;
+}
+interface RetrieveContextBundleWithGraphArgs extends RetrieveContextArgs {
+    includeNodes?: boolean;
+    includeRelatedTo?: boolean;
+}
+interface ContextBundleWithGraph {
+    bundle: ContextBundle;
+    graph: MemoryGraphResponse;
+}
+interface CaptureUsefulLearningArgs {
+    agentId: string;
+    sessionId?: string;
+    useful?: boolean;
+    learning: LearningCandidate & {
+        utility?: number;
+    };
+}
 interface CaptureEpisodeArgs {
     agentId: string;
     runId: string;
@@ -195,6 +234,7 @@ interface LearningCandidate {
     content: string;
     tags: string[];
     confidence: number;
+    utility?: number;
     signals?: MemoryRecord["signals"];
     env?: EnvironmentFingerprint;
     triage?: MemoryTriage;
@@ -271,6 +311,8 @@ declare class MemoryService {
     private cyAutoRelateByTags;
     private cyGetMemoriesById;
     private cyGetMemoryGraph;
+    private cyFallbackRetrieve;
+    private cyListMemoryEdges;
     private cyGetRecallEdges;
     constructor(cfg: MemoryServiceConfig);
     init(): Promise<void>;
@@ -291,6 +333,12 @@ declare class MemoryService {
      * Upsert an episodic Case (case-based reasoning) that links symptoms + env + resolved_by + negative memories.
      */
     upsertCase(c: CaseRecord): Promise<string>;
+    /**
+     * Create a new Case with an auto-generated id if none is provided.
+     */
+    createCase(c: Omit<CaseRecord, "id"> & {
+        id?: string;
+    }): 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.
@@ -299,6 +347,8 @@ declare class MemoryService {
     listMemories(args?: ListMemoriesArgs): Promise<MemorySummary[]>;
     getMemoriesById(args: GetMemoriesByIdArgs): Promise<MemoryRecord[]>;
     getMemoryGraph(args: GetMemoryGraphArgs): Promise<MemoryGraphResponse>;
+    listMemoryEdges(args?: ListMemoryEdgesArgs): Promise<MemoryEdgeExport[]>;
+    retrieveContextBundleWithGraph(args: RetrieveContextBundleWithGraphArgs): Promise<ContextBundleWithGraph>;
     listEpisodes(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
     listSkills(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
     listConcepts(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
@@ -308,6 +358,7 @@ declare class MemoryService {
         weight?: number;
     }): Promise<void>;
     captureEpisode(args: CaptureEpisodeArgs): Promise<SaveLearningResult>;
+    captureUsefulLearning(args: CaptureUsefulLearningArgs): Promise<SaveLearningResult>;
     captureStepEpisode(args: CaptureStepEpisodeArgs): Promise<SaveLearningResult>;
     /**
      * Reinforce/degrade agent->memory association weights using a single batched Cypher query.
@@ -354,6 +405,8 @@ declare const cypher: {
     autoRelateByTags: string;
     getMemoriesById: string;
     getMemoryGraph: string;
+    fallbackRetrieveMemories: string;
+    listMemoryEdges: string;
 };
 
 declare function createMemoryTools(service: MemoryService): MemoryToolSet;
@@ -364,4 +417,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 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 };
+export { type AutoRelateConfig, type BetaEdge, type CaptureEpisodeArgs, type CaptureStepEpisodeArgs, type CaptureUsefulLearningArgs, type CaseRecord, type ContextBundle, type ContextBundleWithGraph, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type GetMemoriesByIdArgs, type GetMemoryGraphArgs, type LearningCandidate, type ListMemoriesArgs, type ListMemoryEdgesArgs, type MemoryEdgeExport, 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 RetrieveContextBundleWithGraphArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, createMemoryTools, cypher, ensureSchema, envHash, loadCypher, migrate, newId, normaliseSymptom, schemaVersion, sha256Hex };

package/dist/index.js

@@ -38,7 +38,9 @@ var 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")
+  getMemoryGraph: loadCypher("get_memory_graph.cypher"),
+  fallbackRetrieveMemories: loadCypher("fallback_retrieve_memories.cypher"),
+  listMemoryEdges: loadCypher("list_memory_edges.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -228,6 +230,8 @@ var MemoryService = class {
   cyAutoRelateByTags = cypher.autoRelateByTags;
   cyGetMemoriesById = cypher.getMemoriesById;
   cyGetMemoryGraph = cypher.getMemoryGraph;
+  cyFallbackRetrieve = cypher.fallbackRetrieveMemories;
+  cyListMemoryEdges = cypher.listMemoryEdges;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -315,7 +319,7 @@ var MemoryService = class {
         contentHash,
         tags,
         confidence: clamp01(l.confidence),
-        utility: 0.2,
+        utility: typeof l.utility === "number" ? clamp01(l.utility) : 0.2,
         // start modest; reinforce via feedback
         triage: l.triage ? JSON.stringify(l.triage) : null,
         antiPattern: l.antiPattern ? JSON.stringify(l.antiPattern) : null
@@ -392,6 +396,13 @@ var MemoryService = class {
       await session.close();
     }
   }
+  /**
+   * Create a new Case with an auto-generated id if none is provided.
+   */
+  async createCase(c) {
+    const id = c.id ?? newId("case");
+    return this.upsertCase({ ...c, id });
+  }
   /**
    * 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.
@@ -417,28 +428,49 @@ var MemoryService = class {
         halfLifeSeconds: this.halfLifeSeconds
       });
       const sections = r.records[0].get("sections");
-      const fixes = (sections.fixes ?? []).map((m) => ({
-        id: m.id,
-        kind: m.kind,
-        polarity: m.polarity ?? "positive",
-        title: m.title,
-        content: m.content,
-        tags: m.tags ?? [],
-        confidence: m.confidence ?? 0.7,
-        utility: m.utility ?? 0.2,
-        updatedAt: m.updatedAt?.toString?.() ?? null
-      }));
-      const doNot = (sections.doNot ?? []).map((m) => ({
+      const mapSummary = (m, fallbackPolarity) => ({
         id: m.id,
         kind: m.kind,
-        polarity: m.polarity ?? "negative",
+        polarity: m.polarity ?? fallbackPolarity,
         title: m.title,
         content: m.content,
         tags: m.tags ?? [],
         confidence: m.confidence ?? 0.7,
         utility: m.utility ?? 0.2,
         updatedAt: m.updatedAt?.toString?.() ?? null
-      }));
+      });
+      let fixes = (sections.fixes ?? []).map((m) => mapSummary(m, "positive"));
+      let doNot = (sections.doNot ?? []).map((m) => mapSummary(m, "negative"));
+      const fallback = args.fallback ?? {};
+      const shouldFallback = fallback.enabled === true && fixes.length === 0 && doNot.length === 0;
+      if (shouldFallback) {
+        const fallbackFixLimit = fallback.limit ?? fixLimit;
+        const fallbackDontLimit = fallback.limit ?? dontLimit;
+        try {
+          const fallbackRes = await session.run(this.cyFallbackRetrieve, {
+            prompt: args.prompt ?? "",
+            tags: args.tags ?? [],
+            kinds: args.kinds ?? [],
+            fulltextIndex: this.fulltextIndex,
+            vectorIndex: this.vectorIndex,
+            embedding: fallback.embedding ?? null,
+            useFulltext: fallback.useFulltext ?? true,
+            useVector: fallback.useVector ?? false,
+            useTags: fallback.useTags ?? true,
+            fixLimit: fallbackFixLimit,
+            dontLimit: fallbackDontLimit
+          });
+          const fbSections = fallbackRes.records[0]?.get("sections");
+          fixes = (fbSections?.fixes ?? []).map((m) => mapSummary(m, "positive"));
+          doNot = (fbSections?.doNot ?? []).map((m) => mapSummary(m, "negative"));
+        } catch (err) {
+          this.emit({
+            type: "read",
+            action: "retrieveContextBundle.fallbackError",
+            meta: { message: err instanceof Error ? err.message : String(err) }
+          });
+        }
+      }
       const allIds = [.../* @__PURE__ */ new Set([...fixes.map((x) => x.id), ...doNot.map((x) => x.id)])];
       const edgeAfter = /* @__PURE__ */ new Map();
       if (allIds.length > 0) {
@@ -533,7 +565,8 @@ ${m.content}`).join("");
       const res = await session.run(this.cyGetMemoryGraph, {
         agentId: args.agentId ?? null,
         memoryIds: ids,
-        includeNodes: args.includeNodes ?? true
+        includeNodes: args.includeNodes ?? true,
+        includeRelatedTo: args.includeRelatedTo ?? false
       });
       const record = res.records[0];
       const nodesRaw = record?.get("nodes") ?? [];
@@ -546,6 +579,32 @@ ${m.content}`).join("");
       await session.close();
     }
   }
+  async listMemoryEdges(args = {}) {
+    const session = this.client.session("READ");
+    try {
+      const res = await session.run(this.cyListMemoryEdges, {
+        limit: args.limit ?? 200,
+        minStrength: args.minStrength ?? 0
+      });
+      return res.records[0]?.get("edges") ?? [];
+    } finally {
+      await session.close();
+    }
+  }
+  async retrieveContextBundleWithGraph(args) {
+    const bundle = await this.retrieveContextBundle(args);
+    const ids = [
+      ...bundle.sections.fix.map((m) => m.id),
+      ...bundle.sections.doNotDo.map((m) => m.id)
+    ];
+    const graph = await this.getMemoryGraph({
+      agentId: args.agentId,
+      memoryIds: ids,
+      includeNodes: args.includeNodes ?? false,
+      includeRelatedTo: args.includeRelatedTo ?? false
+    });
+    return { bundle, graph };
+  }
   async listEpisodes(args = {}) {
     return this.listMemories({ ...args, kind: "episodic" });
   }
@@ -576,6 +635,22 @@ ${m.content}`).join("");
     this.emit({ type: "write", action: "captureEpisode", meta: { runId: args.runId, title } });
     return result;
   }
+  async captureUsefulLearning(args) {
+    if (args.useful === false) {
+      return { saved: [], rejected: [{ title: args.learning.title, reason: "not marked useful" }] };
+    }
+    const result = await this.saveLearnings({
+      agentId: args.agentId,
+      sessionId: args.sessionId,
+      learnings: [args.learning]
+    });
+    this.emit({
+      type: "write",
+      action: "captureUsefulLearning",
+      meta: { title: args.learning.title, savedCount: result.saved.length }
+    });
+    return result;
+  }
   async captureStepEpisode(args) {
     const title = `Episode ${args.workflowName} - ${args.stepName}`;
     const base = {
@@ -605,18 +680,34 @@ ${m.content}`).join("");
     const used = new Set(fb.usedIds ?? []);
     const useful = new Set(fb.usefulIds ?? []);
     const notUseful = new Set(fb.notUsefulIds ?? []);
+    const neutral = new Set(fb.neutralIds ?? []);
     const prevented = new Set(fb.preventedErrorIds ?? []);
+    const updateUnratedUsed = fb.updateUnratedUsed ?? true;
     for (const id of prevented) useful.add(id);
     for (const id of useful) notUseful.delete(id);
+    for (const id of neutral) notUseful.delete(id);
     for (const id of useful) used.add(id);
     for (const id of notUseful) used.add(id);
+    for (const id of neutral) used.add(id);
     const quality = clamp01(fb.metrics?.quality ?? 0.7);
     const hallucRisk = clamp01(fb.metrics?.hallucinationRisk ?? 0.2);
     const baseY = clamp01(quality - 0.7 * hallucRisk);
     const w = 0.5 + 1.5 * quality;
     const yById = /* @__PURE__ */ new Map();
     for (const id of used) {
-      yById.set(id, useful.has(id) ? baseY : 0);
+      if (useful.has(id)) {
+        yById.set(id, baseY);
+        continue;
+      }
+      if (notUseful.has(id)) {
+        yById.set(id, 0);
+        continue;
+      }
+      if (neutral.has(id) || !updateUnratedUsed) {
+        yById.set(id, 0.5);
+        continue;
+      }
+      yById.set(id, 0);
     }
     const items = [...used].map((memoryId) => ({
       memoryId,

package/package.json

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