neo4j-agent-memory 0.4.0 → 0.5.0

package/dist/index.js

@@ -36,7 +36,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
@@ -96,6 +100,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,
@@ -122,6 +140,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,
@@ -193,6 +228,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})
@@ -280,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
@@ -357,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.
@@ -382,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) {
@@ -478,6 +545,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" });
   }
@@ -508,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 = {
@@ -537,29 +680,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,
@@ -567,6 +726,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++) {
@@ -588,6 +757,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.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/dist/index.d.cts

@@ -1,246 +0,0 @@
-import { Session } from 'neo4j-driver';
-
-type MemoryKind = "semantic" | "procedural" | "episodic";
-type MemoryPolarity = "positive" | "negative";
-interface EnvironmentFingerprint {
-    hash?: string;
-    os?: "macos" | "linux" | "windows";
-    distro?: string;
-    ci?: string;
-    container?: boolean;
-    filesystem?: string;
-    workspaceMount?: "local" | "network" | "bind" | "readonly";
-    nodeVersion?: string;
-    packageManager?: "npm" | "pnpm" | "yarn";
-    pmVersion?: string;
-}
-interface DistilledInvariant {
-    invariant: string;
-    justification?: string;
-    verification?: string[];
-    applicability?: string[];
-    risks?: string[];
-}
-interface MemoryRecord {
-    id: string;
-    kind: MemoryKind;
-    polarity: MemoryPolarity;
-    title: string;
-    content: string;
-    tags: string[];
-    confidence: number;
-    utility: number;
-    createdAt?: string;
-    updatedAt?: string;
-    signals?: {
-        symptoms?: string[];
-        environment?: string[];
-    };
-    distilled?: {
-        invariants?: DistilledInvariant[];
-        steps?: string[];
-        verificationSteps?: string[];
-        gotchas?: string[];
-    };
-    antiPattern?: {
-        action: string;
-        whyBad: string;
-        saferAlternative?: string;
-    };
-    env?: EnvironmentFingerprint;
-}
-interface CaseRecord {
-    id: string;
-    title: string;
-    summary: string;
-    outcome: "resolved" | "unresolved" | "workaround";
-    symptoms: string[];
-    env: EnvironmentFingerprint;
-    resolvedByMemoryIds: string[];
-    negativeMemoryIds: string[];
-    resolvedAtIso?: string | null;
-}
-interface RetrieveContextArgs {
-    agentId: string;
-    prompt: string;
-    symptoms?: string[];
-    tags?: string[];
-    kinds?: MemoryKind[];
-    env?: EnvironmentFingerprint;
-    baseline?: Record<string, {
-        a: number;
-        b: number;
-    }>;
-    caseLimit?: number;
-    fixLimit?: number;
-    dontLimit?: number;
-    nowIso?: string;
-}
-interface BetaEdge {
-    a: number;
-    b: number;
-    /** Posterior mean a/(a+b), cached for query speed */
-    strength: number;
-    /** Evidence mass a+b, cached for query speed */
-    evidence: number;
-    updatedAt: string | null;
-}
-type ContextMemoryBase = Pick<MemoryRecord, "id" | "kind" | "polarity" | "title" | "content" | "tags" | "confidence" | "utility" | "updatedAt">;
-type ContextMemorySummary = ContextMemoryBase & {
-    /** Posterior snapshot before the current run (baseline) */
-    edgeBefore?: BetaEdge;
-    /** Posterior snapshot after the current run (undefined until feedback arrives) */
-    edgeAfter?: BetaEdge;
-};
-interface ContextBundle {
-    sessionId: string;
-    sections: {
-        fix: ContextMemorySummary[];
-        doNotDo: ContextMemorySummary[];
-    };
-    injection: {
-        fixBlock: string;
-        doNotDoBlock: string;
-    };
-}
-interface FeedbackMetrics {
-    durationMs?: number;
-    quality?: number;
-    hallucinationRisk?: number;
-    toolCalls?: number;
-    verificationPassed?: boolean;
-}
-interface MemoryFeedback {
-    agentId: string;
-    sessionId: string;
-    usedIds: string[];
-    usefulIds: string[];
-    notUsefulIds: string[];
-    preventedErrorIds?: string[];
-    metrics?: FeedbackMetrics;
-    notes?: string;
-}
-interface LearningCandidate {
-    kind: MemoryKind;
-    polarity?: MemoryPolarity;
-    title: string;
-    content: string;
-    tags: string[];
-    confidence: number;
-    signals?: MemoryRecord["signals"];
-    env?: EnvironmentFingerprint;
-    triage?: {
-        symptoms: string[];
-        likelyCauses: string[];
-        verificationSteps?: string[];
-        fixSteps?: string[];
-        gotchas?: string[];
-    };
-    antiPattern?: MemoryRecord["antiPattern"];
-}
-interface SaveLearningRequest {
-    agentId: string;
-    sessionId?: string;
-    taskId?: string;
-    learnings: LearningCandidate[];
-    policy?: {
-        minConfidence?: number;
-        requireVerificationSteps?: boolean;
-        maxItems?: number;
-    };
-}
-interface SaveLearningResult {
-    saved: Array<{
-        id: string;
-        kind: MemoryKind;
-        title: string;
-        deduped: boolean;
-    }>;
-    rejected: Array<{
-        title: string;
-        reason: string;
-    }>;
-}
-interface MemoryServiceConfig {
-    neo4j: {
-        uri: string;
-        username: string;
-        password: string;
-        database?: string;
-    };
-    vectorIndex?: string;
-    fulltextIndex?: string;
-    halfLifeSeconds?: number;
-}
-
-declare class MemoryService {
-    private client;
-    private vectorIndex;
-    private fulltextIndex;
-    private halfLifeSeconds;
-    private cyUpsertMemory;
-    private cyUpsertCase;
-    private cyRetrieveBundle;
-    private cyFeedbackBatch;
-    private cyFeedbackCoUsed;
-    private cyGetRecallEdges;
-    constructor(cfg: MemoryServiceConfig);
-    init(): Promise<void>;
-    close(): Promise<void>;
-    private ensureEnvHash;
-    /**
-     * Save a distilled memory (semantic/procedural/episodic) with exact dedupe by contentHash.
-     * NOTE: This package intentionally does not store "full answers" as semantic/procedural.
-     */
-    upsertMemory(l: LearningCandidate & {
-        id?: string;
-    }): Promise<{
-        id: string;
-        deduped: boolean;
-    }>;
-    /**
-     * Upsert an episodic Case (case-based reasoning) that links symptoms + env + resolved_by + negative memories.
-     */
-    upsertCase(c: CaseRecord): 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>;
-    /**
-     * 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>;
-    /**
-     * Save distilled learnings discovered during a task.
-     * Enforces quality gates and stores negative memories explicitly.
-     * Automatically creates a Case if learnings have triage.symptoms.
-     */
-    saveLearnings(req: SaveLearningRequest): Promise<SaveLearningResult>;
-}
-declare function createMemoryService(cfg: MemoryServiceConfig): Promise<MemoryService>;
-
-interface Neo4jClientConfig {
-    uri: string;
-    username: string;
-    password: string;
-    database?: string;
-}
-declare class Neo4jClient {
-    private driver;
-    private database?;
-    constructor(cfg: Neo4jClientConfig);
-    session(mode?: "READ" | "WRITE"): Session;
-    close(): Promise<void>;
-}
-
-declare function ensureSchema(client: Neo4jClient): Promise<void>;
-
-declare function sha256Hex(s: string): string;
-declare function canonicaliseForHash(title: string, content: string, tags: string[]): string;
-declare function newId(prefix: string): string;
-declare function normaliseSymptom(s: string): string;
-declare function envHash(env: EnvironmentFingerprint): string;
-
-export { type BetaEdge, type CaseRecord, type ContextBundle, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type LearningCandidate, type MemoryFeedback, type MemoryKind, type MemoryPolarity, type MemoryRecord, MemoryService, type MemoryServiceConfig, Neo4jClient, type Neo4jClientConfig, type RetrieveContextArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, ensureSchema, envHash, newId, normaliseSymptom, sha256Hex };