neo4j-agent-memory 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -86,7 +86,11 @@ 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"),
+  fallbackRetrieveMemories: loadCypher("fallback_retrieve_memories.cypher"),
+  listMemoryEdges: loadCypher("list_memory_edges.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -146,6 +150,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 +190,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 +278,10 @@ var MemoryService = class {
   cyListMemories = cypher.listMemories;
   cyRelateConcepts = cypher.relateConcepts;
   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})
@@ -330,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
@@ -407,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.
@@ -432,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) {
@@ -528,6 +595,66 @@ ${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,
+        includeRelatedTo: args.includeRelatedTo ?? false
+      });
+      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 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" });
   }
@@ -558,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 = {
@@ -587,29 +730,45 @@ ${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,
       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 +776,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 +807,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" | "related_to";
+    strength: number;
+    evidence: number;
+    updatedAt?: string | null;
+}
+interface MemoryGraphResponse {
+    nodes: MemoryRecord[];
+    edges: MemoryGraphEdge[];
+}
 interface CaseRecord {
     id: string;
     title: string;
@@ -86,12 +106,29 @@ 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;
     limit?: number;
     agentId?: string;
 }
+interface GetMemoriesByIdArgs {
+    ids: string[];
+}
+interface GetMemoryGraphArgs {
+    agentId?: string;
+    memoryIds: string[];
+    includeNodes?: boolean;
+    includeRelatedTo?: boolean;
+}
 interface BetaEdge {
     a: number;
     b: number;
@@ -132,10 +169,46 @@ interface MemoryFeedback {
     usedIds: string[];
     usefulIds: string[];
     notUsefulIds: string[];
+    neutralIds?: string[];
+    updateUnratedUsed?: boolean;
     preventedErrorIds?: string[];
     metrics?: FeedbackMetrics;
     notes?: string;
 }
+interface MemoryFeedbackResult {
+    updated: Array<{
+        id: string;
+        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;
@@ -161,15 +234,10 @@ interface LearningCandidate {
     content: string;
     tags: string[];
     confidence: number;
+    utility?: 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 +309,10 @@ declare class MemoryService {
     private cyListMemories;
     private cyRelateConcepts;
     private cyAutoRelateByTags;
+    private cyGetMemoriesById;
+    private cyGetMemoryGraph;
+    private cyFallbackRetrieve;
+    private cyListMemoryEdges;
     private cyGetRecallEdges;
     constructor(cfg: MemoryServiceConfig);
     init(): Promise<void>;
@@ -261,12 +333,22 @@ 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.
      */
     retrieveContextBundle(args: RetrieveContextArgs): Promise<ContextBundle>;
     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[]>;
@@ -276,12 +358,13 @@ 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.
      * 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 +403,10 @@ declare const cypher: {
     listMemories: string;
     relateConcepts: string;
     autoRelateByTags: string;
+    getMemoriesById: string;
+    getMemoryGraph: string;
+    fallbackRetrieveMemories: string;
+    listMemoryEdges: string;
 };
 
 declare function createMemoryTools(service: MemoryService): MemoryToolSet;
@@ -330,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 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 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 };