neo4j-agent-memory 0.3.17 → 0.4.0

package/README.md

@@ -35,7 +35,16 @@ const mem = await createMemoryService({
   neo4j: { uri, username, password },
   vectorIndex: "memoryEmbedding",
   fulltextIndex: "memoryText",
-  halfLifeSeconds: 30 * 24 * 3600
+  halfLifeSeconds: 30 * 24 * 3600,
+  autoRelate: {
+    enabled: true,
+    minSharedTags: 2,
+    minWeight: 0.2,
+    maxCandidates: 12,
+    sameKind: true,
+    samePolarity: true,
+    allowedKinds: ["semantic", "procedural"]
+  }
 });
 
 const bundle = await mem.retrieveContextBundle({
@@ -61,6 +70,25 @@ Notes:
 - `createMemoryService` runs schema setup on init.
 - Cypher assets are bundled at `dist/cypher` in the published package.
 
+Auto-relate config (defaults):
+- `enabled: true`
+- `minSharedTags: 2`
+- `minWeight: 0.2`
+- `maxCandidates: 12`
+- `sameKind: true`
+- `samePolarity: true`
+- `allowedKinds: ["semantic", "procedural"]`
+
+Auto-relate behavior:
+- Uses tag overlap with Jaccard weight (`shared / (a + b - shared)`).
+- Runs only for newly inserted memories (skips deduped).
+- Applies filters for `sameKind`, `samePolarity`, and `allowedKinds`.
+- Requires `minSharedTags` and `minWeight` to pass before linking.
+- Limits to `maxCandidates` highest-weight neighbors.
+
+Performance note:
+- Auto-relate scans candidate memories with tag filtering; for large graphs, keep tags selective and consider tightening `maxCandidates` and `minSharedTags`.
+
 ## Tool adapter (createMemoryTools)
 
 Use the tool factory to preserve the existing tool surface used by the demo:

package/dist/cypher/auto_relate_memory_by_tags.cypher

@@ -0,0 +1,45 @@
+// Parameters:
+// - $id: Source memory id
+// - $nowIso: ISO timestamp
+// - $minSharedTags: Minimum overlapping tags
+// - $minWeight: Minimum Jaccard weight to relate
+// - $maxCandidates: Max related memories to link
+// - $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)
+WITH datetime($nowIso) AS now
+MATCH (src:Memory {id: $id})
+WITH src, now, coalesce(src.tags, []) AS srcTags
+MATCH (m:Memory)
+WHERE m.id <> src.id
+  AND (NOT $sameKind OR m.kind = src.kind)
+  AND (NOT $samePolarity OR m.polarity = src.polarity)
+  AND (size($allowedKinds) = 0 OR m.kind IN $allowedKinds)
+WITH
+  src,
+  now,
+  srcTags,
+  m,
+  size([t IN srcTags WHERE t IN coalesce(m.tags, [])]) AS shared,
+  size(srcTags) AS aSize,
+  size(coalesce(m.tags, [])) AS bSize
+WHERE shared >= $minSharedTags
+WITH
+  src,
+  now,
+  m,
+  shared,
+  CASE
+    WHEN (aSize + bSize - shared) = 0 THEN 0.0
+    ELSE toFloat(shared) / (aSize + bSize - shared)
+  END AS weight
+WHERE weight >= $minWeight
+ORDER BY weight DESC, shared DESC
+LIMIT $maxCandidates
+MERGE (src)-[r:RELATED_TO]->(m)
+ON CREATE SET r.weight = weight, r.createdAt = now, r.updatedAt = now
+ON MATCH SET r.weight = weight, r.updatedAt = now
+MERGE (m)-[r2:RELATED_TO]->(src)
+ON CREATE SET r2.weight = weight, r2.createdAt = now, r2.updatedAt = now
+ON MATCH SET r2.weight = weight, r2.updatedAt = now
+RETURN count(*) AS related;

package/dist/cypher/feedback_batch.cypher

@@ -1,7 +1,34 @@
+// :param {
+//   nowIso: "2026-01-04T22:07:53.086Z",
+//   agentId: "agent-123",
+//   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"
+//   ]
+// }
 WITH datetime($nowIso) AS now
-UNWIND $items AS item
+
+UNWIND $items AS memoryId
+WITH now, memoryId
+WHERE memoryId IS NOT NULL AND memoryId <> ""
+
 MATCH (a:Agent {id: $agentId})
-MATCH (m:Memory {id: item.memoryId})
+MATCH (m:Memory {id: memoryId})
+
 MERGE (a)-[r:RECALLS]->(m)
 ON CREATE SET
   r.a = 1.0,
@@ -11,32 +38,33 @@ ON CREATE SET
   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,
+     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,
+WITH now, r,
      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
+     coalesce(r.a, $aMin) AS aPrev,
+     coalesce(r.b, $bMin) AS bPrev
 
-WITH now, r, item, gamma,
+WITH now, r, 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
+WITH now, r,
+     (a0 + $w * $y) AS a1,
+     (b0 + $w * (1.0 - $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
+    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
 
 RETURN count(*) AS updated;

package/dist/cypher/index.ts

@@ -20,4 +20,5 @@ export const 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"),
 };

package/dist/cypher/list_memories.cypher

@@ -1,28 +1,36 @@
-// Parameters:
+// Parameters (Neo4j Browser :param)
+// :param { kind: null, limit: 50, agentId: "" }
+
 // - $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($kind, null) AS kind,
   coalesce($limit, 50) AS limit,
-  $agentId AS agentId
+  coalesce($agentId, "") AS agentId
 
-CALL {
-  WITH kind, agentId
+CALL (kind, agentId) {
+  // If agentId provided -> only recalled by that agent
   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
+
+  // If agentId absent -> all memories
   WITH kind, agentId
   WHERE agentId IS NULL OR agentId = ""
   MATCH (m:Memory)
   WHERE kind IS NULL OR m.kind = kind
   RETURN m
 }
-WITH m
+
+WITH m, limit
 ORDER BY m.updatedAt DESC
+
 WITH collect(
   m {
     .id,
@@ -36,4 +44,5 @@ WITH collect(
     .updatedAt
   }
 ) AS rows, limit
+
 RETURN rows[0..limit] AS memories;

package/dist/cypher/schema.cypher

@@ -16,5 +16,8 @@ FOR (m:Memory) ON (m.polarity);
 CREATE INDEX memory_kind IF NOT EXISTS
 FOR (m:Memory) ON (m.kind);
 
+CREATE INDEX memory_tags IF NOT EXISTS
+FOR (m:Memory) ON (m.tags);
+
 CREATE CONSTRAINT agent_id_unique IF NOT EXISTS
 FOR (a:Agent) REQUIRE a.id IS UNIQUE;

package/dist/index.cjs

@@ -85,7 +85,8 @@ var cypher = {
   feedbackBatch: loadCypher("feedback_batch.cypher"),
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
-  relateConcepts: loadCypher("relate_concepts.cypher")
+  relateConcepts: loadCypher("relate_concepts.cypher"),
+  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -145,6 +146,17 @@ function envHash(env) {
 function clamp01(x) {
   return Math.max(0, Math.min(1, x));
 }
+var DEFAULT_AUTO_RELATE = {
+  enabled: true,
+  minSharedTags: 2,
+  minWeight: 0.2,
+  maxCandidates: 12,
+  sameKind: true,
+  samePolarity: true,
+  allowedKinds: ["semantic", "procedural"]
+};
+var AUTO_RELATE_MIN_SHARED_TAGS = 1;
+var AUTO_RELATE_MIN_MAX_CANDIDATES = 1;
 function toBetaEdge(raw) {
   const aMin = 1e-3;
   const bMin = 1e-3;
@@ -222,6 +234,7 @@ var MemoryService = class {
   fulltextIndex;
   halfLifeSeconds;
   onMemoryEvent;
+  autoRelateConfig;
   cyUpsertMemory = cypher.upsertMemory;
   cyUpsertCase = cypher.upsertCase;
   cyRetrieveBundle = cypher.retrieveContextBundle;
@@ -229,6 +242,7 @@ var MemoryService = class {
   cyFeedbackCoUsed = cypher.feedbackCoUsed;
   cyListMemories = cypher.listMemories;
   cyRelateConcepts = cypher.relateConcepts;
+  cyAutoRelateByTags = cypher.autoRelateByTags;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -246,6 +260,22 @@ var MemoryService = class {
     this.fulltextIndex = cfg.fulltextIndex ?? "memoryText";
     this.halfLifeSeconds = cfg.halfLifeSeconds ?? 30 * 24 * 3600;
     this.onMemoryEvent = cfg.onMemoryEvent;
+    const autoRelate = cfg.autoRelate ?? {};
+    this.autoRelateConfig = {
+      enabled: autoRelate.enabled ?? DEFAULT_AUTO_RELATE.enabled,
+      minSharedTags: Math.max(
+        AUTO_RELATE_MIN_SHARED_TAGS,
+        Math.floor(autoRelate.minSharedTags ?? DEFAULT_AUTO_RELATE.minSharedTags)
+      ),
+      minWeight: clamp01(autoRelate.minWeight ?? DEFAULT_AUTO_RELATE.minWeight),
+      maxCandidates: Math.max(
+        AUTO_RELATE_MIN_MAX_CANDIDATES,
+        Math.floor(autoRelate.maxCandidates ?? DEFAULT_AUTO_RELATE.maxCandidates)
+      ),
+      sameKind: autoRelate.sameKind ?? DEFAULT_AUTO_RELATE.sameKind,
+      samePolarity: autoRelate.samePolarity ?? DEFAULT_AUTO_RELATE.samePolarity,
+      allowedKinds: autoRelate.allowedKinds ?? [...DEFAULT_AUTO_RELATE.allowedKinds]
+    };
   }
   async init() {
     await ensureSchema(this.client);
@@ -330,6 +360,21 @@ var MemoryService = class {
           }
         );
       }
+      const autoRelate = this.autoRelateConfig;
+      const allowedKinds = autoRelate.allowedKinds ?? [];
+      const canAutoRelate = autoRelate.enabled && tags.length >= autoRelate.minSharedTags && (allowedKinds.length === 0 || allowedKinds.includes(l.kind));
+      if (canAutoRelate) {
+        await write.run(this.cyAutoRelateByTags, {
+          id,
+          nowIso: (/* @__PURE__ */ new Date()).toISOString(),
+          minSharedTags: autoRelate.minSharedTags,
+          minWeight: autoRelate.minWeight,
+          maxCandidates: autoRelate.maxCandidates,
+          sameKind: autoRelate.sameKind,
+          samePolarity: autoRelate.samePolarity,
+          allowedKinds
+        });
+      }
       this.emit({ type: "write", action: "upsertMemory", meta: { id } });
       return { id, deduped: false };
     } finally {

package/dist/index.d.cts

@@ -0,0 +1,246 @@
+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 };

package/dist/index.d.ts

@@ -195,6 +195,15 @@ interface SaveLearningResult {
         reason: string;
     }>;
 }
+interface AutoRelateConfig {
+    enabled?: boolean;
+    minSharedTags?: number;
+    minWeight?: number;
+    maxCandidates?: number;
+    sameKind?: boolean;
+    samePolarity?: boolean;
+    allowedKinds?: MemoryKind[];
+}
 interface MemoryServiceConfig {
     neo4j: {
         uri: string;
@@ -205,6 +214,7 @@ interface MemoryServiceConfig {
     vectorIndex?: string;
     fulltextIndex?: string;
     halfLifeSeconds?: number;
+    autoRelate?: AutoRelateConfig;
     onMemoryEvent?: (event: MemoryEvent) => void;
 }
 type MemoryToolName = "store_skill" | "store_pattern" | "store_concept" | "relate_concepts" | "recall_skills" | "recall_concepts" | "recall_patterns";
@@ -222,6 +232,7 @@ declare class MemoryService {
     private fulltextIndex;
     private halfLifeSeconds;
     private onMemoryEvent?;
+    private autoRelateConfig;
     private cyUpsertMemory;
     private cyUpsertCase;
     private cyRetrieveBundle;
@@ -229,6 +240,7 @@ declare class MemoryService {
     private cyFeedbackCoUsed;
     private cyListMemories;
     private cyRelateConcepts;
+    private cyAutoRelateByTags;
     private cyGetRecallEdges;
     constructor(cfg: MemoryServiceConfig);
     init(): Promise<void>;
@@ -307,6 +319,7 @@ declare const cypher: {
     feedbackCoUsed: string;
     listMemories: string;
     relateConcepts: string;
+    autoRelateByTags: string;
 };
 
 declare function createMemoryTools(service: MemoryService): MemoryToolSet;
@@ -317,4 +330,4 @@ declare function newId(prefix: string): string;
 declare function normaliseSymptom(s: string): string;
 declare function envHash(env: EnvironmentFingerprint): string;
 
-export { 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 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 };

package/dist/index.js

@@ -35,7 +35,8 @@ var cypher = {
   feedbackBatch: loadCypher("feedback_batch.cypher"),
   feedbackCoUsed: loadCypher("feedback_co_used_with_batch.cypher"),
   listMemories: loadCypher("list_memories.cypher"),
-  relateConcepts: loadCypher("relate_concepts.cypher")
+  relateConcepts: loadCypher("relate_concepts.cypher"),
+  autoRelateByTags: loadCypher("auto_relate_memory_by_tags.cypher")
 };
 
 // src/neo4j/schema.ts
@@ -95,6 +96,17 @@ function envHash(env) {
 function clamp01(x) {
   return Math.max(0, Math.min(1, x));
 }
+var DEFAULT_AUTO_RELATE = {
+  enabled: true,
+  minSharedTags: 2,
+  minWeight: 0.2,
+  maxCandidates: 12,
+  sameKind: true,
+  samePolarity: true,
+  allowedKinds: ["semantic", "procedural"]
+};
+var AUTO_RELATE_MIN_SHARED_TAGS = 1;
+var AUTO_RELATE_MIN_MAX_CANDIDATES = 1;
 function toBetaEdge(raw) {
   const aMin = 1e-3;
   const bMin = 1e-3;
@@ -172,6 +184,7 @@ var MemoryService = class {
   fulltextIndex;
   halfLifeSeconds;
   onMemoryEvent;
+  autoRelateConfig;
   cyUpsertMemory = cypher.upsertMemory;
   cyUpsertCase = cypher.upsertCase;
   cyRetrieveBundle = cypher.retrieveContextBundle;
@@ -179,6 +192,7 @@ var MemoryService = class {
   cyFeedbackCoUsed = cypher.feedbackCoUsed;
   cyListMemories = cypher.listMemories;
   cyRelateConcepts = cypher.relateConcepts;
+  cyAutoRelateByTags = cypher.autoRelateByTags;
   cyGetRecallEdges = `
     UNWIND $ids AS id
     MATCH (m:Memory {id:id})
@@ -196,6 +210,22 @@ var MemoryService = class {
     this.fulltextIndex = cfg.fulltextIndex ?? "memoryText";
     this.halfLifeSeconds = cfg.halfLifeSeconds ?? 30 * 24 * 3600;
     this.onMemoryEvent = cfg.onMemoryEvent;
+    const autoRelate = cfg.autoRelate ?? {};
+    this.autoRelateConfig = {
+      enabled: autoRelate.enabled ?? DEFAULT_AUTO_RELATE.enabled,
+      minSharedTags: Math.max(
+        AUTO_RELATE_MIN_SHARED_TAGS,
+        Math.floor(autoRelate.minSharedTags ?? DEFAULT_AUTO_RELATE.minSharedTags)
+      ),
+      minWeight: clamp01(autoRelate.minWeight ?? DEFAULT_AUTO_RELATE.minWeight),
+      maxCandidates: Math.max(
+        AUTO_RELATE_MIN_MAX_CANDIDATES,
+        Math.floor(autoRelate.maxCandidates ?? DEFAULT_AUTO_RELATE.maxCandidates)
+      ),
+      sameKind: autoRelate.sameKind ?? DEFAULT_AUTO_RELATE.sameKind,
+      samePolarity: autoRelate.samePolarity ?? DEFAULT_AUTO_RELATE.samePolarity,
+      allowedKinds: autoRelate.allowedKinds ?? [...DEFAULT_AUTO_RELATE.allowedKinds]
+    };
   }
   async init() {
     await ensureSchema(this.client);
@@ -280,6 +310,21 @@ var MemoryService = class {
           }
         );
       }
+      const autoRelate = this.autoRelateConfig;
+      const allowedKinds = autoRelate.allowedKinds ?? [];
+      const canAutoRelate = autoRelate.enabled && tags.length >= autoRelate.minSharedTags && (allowedKinds.length === 0 || allowedKinds.includes(l.kind));
+      if (canAutoRelate) {
+        await write.run(this.cyAutoRelateByTags, {
+          id,
+          nowIso: (/* @__PURE__ */ new Date()).toISOString(),
+          minSharedTags: autoRelate.minSharedTags,
+          minWeight: autoRelate.minWeight,
+          maxCandidates: autoRelate.maxCandidates,
+          sameKind: autoRelate.sameKind,
+          samePolarity: autoRelate.samePolarity,
+          allowedKinds
+        });
+      }
       this.emit({ type: "write", action: "upsertMemory", meta: { id } });
       return { id, deduped: false };
     } finally {

package/package.json

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