@tangle-network/agent-knowledge 1.6.0 → 1.7.0

package/README.md

@@ -11,6 +11,7 @@ This package turns raw sources and generated markdown knowledge into a versionab
 - [CLI](#cli) — `init` → `source-add` → `index` → `search` → `lint`
 - [Design](#design) — the invariants (immutable sources, cited claims, deterministic graph)
 - [Agent-Eval integration](#agent-eval-integration) — readiness bundles + release reports
+- [Memory adapters](#memory-adapters) — generic memory contract + Neo4j Agent Memory bridge
 - [Research loop](#research-loop) — `runKnowledgeResearchLoop` + control-loop adapter
 - [Researcher profile](#researcher-profile) — sandbox `AgentProfile` for `runLoop`
 - [Pluggable knowledge sources](#pluggable-knowledge-sources) — live authorities → eval re-runs
@@ -106,6 +107,10 @@ from `@tangle-network/agent-knowledge`.
 
 The `/viz` subpath exports graph insight helpers without UI dependencies.
 
+The `/memory` subpath exports an optional memory adapter contract. Use it to
+bridge episodic or graph-native memory systems into the same source-grounded
+readiness/eval machinery without making `agent-knowledge` own the database.
+
 ## Agent-Eval Integration
 
 To answer whether a candidate knowledge base actually improves agent task success, run an `@tangle-network/agent-eval` improvement loop (`runImprovementLoop`) over your KB variants on a real task corpus; each run is scored into a `RunRecord`.
@@ -143,6 +148,38 @@ Pass `readiness.report` to `blockingKnowledgeEval()` from
 `@tangle-network/agent-eval`; use `readiness.questions` and
 `readiness.acquisitionPlans` to drive UI or connector workflows.
 
+## Memory Adapters
+
+`agent-knowledge` does not store operational memory itself. It defines the
+contract that lets a runtime read/write memory through any backend, then turn
+memory hits into `SourceRecord` evidence for readiness, linting, and eval gates.
+
+```ts
+import {
+  createNeo4jAgentMemoryAdapter,
+  memoryHitToSourceRecord,
+} from '@tangle-network/agent-knowledge/memory'
+
+const memory = createNeo4jAgentMemoryAdapter({ client: neo4jMemoryClient })
+
+const context = await memory.getContext('What does this user prefer?', {
+  scope: { userId: 'user-123', sessionId: 'session-456' },
+  limit: 5,
+})
+
+const sourceRecords = context.hits.map((hit) =>
+  memoryHitToSourceRecord(hit, { scope: { userId: 'user-123' } }),
+)
+```
+
+The Neo4j adapter is runtime dependency-free: pass the real
+`@neo4j-labs/agent-memory` client in products, or a fake client in tests. CI
+typechecks against `@neo4j-labs/agent-memory@0.4.0` and covers the published
+TypeScript SDK surface: `shortTerm.addMessage/searchMessages/getContext`,
+`longTerm.addEntity/addPreference/addFact/searchEntities/searchPreferences`,
+and `reasoning.getSimilarTraces`. Generic `search` / `getContext` and
+snake_case bridge-style methods remain supported for non-hosted clients.
+
 ## Research Loop
 
 Use `runKnowledgeResearchLoop()` when an agent is acting as a researcher or

package/dist/chunk-U6KQ4FS3.js

@@ -0,0 +1,585 @@
+import {
+  sha256,
+  stableId
+} from "./chunk-YMKHCTS2.js";
+
+// src/memory/source-record.ts
+function memoryHitToSourceRecord(hit, options = {}) {
+  const contentHash = sha256(`${hit.uri}
+${hit.text}`);
+  return {
+    id: stableId("src", `${hit.uri}:${contentHash}`),
+    uri: hit.uri,
+    title: hit.title ?? `${hit.kind}:${hit.id}`,
+    mediaType: "text/plain",
+    contentHash,
+    text: hit.text,
+    validUntil: hit.validUntil,
+    lastVerifiedAt: hit.lastVerifiedAt,
+    createdAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    metadata: {
+      ...hit.metadata ?? {},
+      source: "agent-memory",
+      memoryId: hit.id,
+      memoryKind: hit.kind,
+      score: hit.score,
+      normalizedScore: hit.normalizedScore,
+      confidence: hit.confidence,
+      scope: options.scope
+    }
+  };
+}
+function memoryWriteResultToSourceRecord(result, text, options = {}) {
+  return memoryHitToSourceRecord(
+    {
+      id: result.id,
+      uri: result.uri,
+      kind: result.kind,
+      text,
+      metadata: result.metadata
+    },
+    options
+  );
+}
+
+// src/memory/adapter.ts
+async function defaultGetMemoryContext(adapter, query, options = {}) {
+  const hits = await adapter.search(query, options);
+  return {
+    query,
+    hits,
+    sourceRecords: hits.map((hit) => memoryHitToSourceRecord(hit, { scope: options.scope })),
+    text: renderMemoryContext(hits)
+  };
+}
+function renderMemoryContext(hits) {
+  return hits.map((hit, index) => {
+    const label = hit.title ?? `${hit.kind}:${hit.id}`;
+    const score = typeof hit.normalizedScore === "number" ? ` score=${hit.normalizedScore.toFixed(3)}` : "";
+    return [`[${index + 1}] ${label}${score}`, hit.text].join("\n");
+  }).join("\n\n");
+}
+
+// src/memory/neo4j.ts
+function createNeo4jAgentMemoryAdapter(options) {
+  const client = options.client;
+  const id = options.id ?? "neo4j-agent-memory";
+  return {
+    id,
+    async search(query, searchOptions = {}) {
+      const sdkHits = await searchNeo4jMemory(client, query, searchOptions, id);
+      if (sdkHits.length > 0) return sdkHits;
+      const result = await callOptional(
+        client,
+        ["search", "memory_search"],
+        [query, neo4jOptions(searchOptions)]
+      );
+      if (result !== void 0) return normalizeHits(result, searchOptions, id);
+      const context = await callOptional(
+        client,
+        ["getContext", "get_context"],
+        [query, neo4jOptions(searchOptions)]
+      );
+      if (context !== void 0) return normalizeHits(context, searchOptions, id);
+      return [];
+    },
+    async getContext(query, searchOptions = {}) {
+      const shortTerm = nested(client, ["shortTerm", "short_term"], {});
+      const sessionId = searchOptions.scope?.sessionId;
+      if (sessionId) {
+        const conversationContext = await callOptional(
+          shortTerm,
+          ["getContext", "get_context"],
+          [sessionId]
+        );
+        if (conversationContext !== void 0) {
+          const hits2 = normalizeConversationContextHits(conversationContext, searchOptions, id);
+          const text = textFromConversationContext(conversationContext) ?? (typeof conversationContext === "string" ? conversationContext : hits2.length > 0 ? renderHits(hits2) : "");
+          return {
+            query,
+            text,
+            hits: hits2,
+            sourceRecords: hits2.map(
+              (hit) => memoryHitToSourceRecord(hit, { scope: searchOptions.scope })
+            ),
+            metadata: { adapter: id, rawContext: conversationContext }
+          };
+        }
+      }
+      const result = await callOptional(
+        client,
+        ["getContext", "get_context"],
+        [query, neo4jOptions(searchOptions)]
+      );
+      if (result === void 0) {
+        return defaultGetMemoryContext(
+          {
+            search: async () => {
+              const sdkHits = await searchNeo4jMemory(client, query, searchOptions, id);
+              if (sdkHits.length > 0) return sdkHits;
+              const searchResult = await callOptional(
+                client,
+                ["search", "memory_search"],
+                [query, neo4jOptions(searchOptions)]
+              );
+              return normalizeHits(searchResult, searchOptions, id);
+            }
+          },
+          query,
+          searchOptions
+        );
+      }
+      if (typeof result === "string") {
+        const hit = {
+          id: stableId("mem", `${id}:${query}:${result}`),
+          uri: `memory://${id}/context/${stableId("ctx", query)}`,
+          kind: "fact",
+          text: result,
+          title: "Memory context",
+          normalizedScore: 1
+        };
+        return {
+          query,
+          text: result,
+          hits: [hit],
+          sourceRecords: [memoryHitToSourceRecord(hit, { scope: searchOptions.scope })],
+          metadata: { adapter: id }
+        };
+      }
+      const hits = normalizeHits(result, searchOptions, id);
+      if (hits.length > 0)
+        return defaultGetMemoryContext({ search: async () => hits }, query, searchOptions);
+      return defaultGetMemoryContext({ search: async () => [] }, query, searchOptions);
+    },
+    async write(input) {
+      const result = await writeNeo4jMemory(client, input, id);
+      return {
+        ...result,
+        sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope: input.scope })
+      };
+    }
+  };
+}
+async function writeNeo4jMemory(client, input, adapterId) {
+  const scope = input.scope ?? {};
+  const sessionId = scope.sessionId ?? input.metadata?.sessionId;
+  let result;
+  if (input.kind === "message") {
+    const shortTerm = nested(client, ["shortTerm", "short_term"], client);
+    result = await callOptional(
+      shortTerm,
+      ["addMessage"],
+      [
+        sessionId,
+        input.role ?? "user",
+        input.text,
+        {
+          metadata: input.metadata,
+          conversationId: sessionId,
+          userId: scope.userId
+        }
+      ]
+    );
+    if (result === void 0) {
+      result = await callRequired(
+        shortTerm,
+        ["add_message"],
+        [
+          {
+            session_id: sessionId,
+            sessionId,
+            role: input.role ?? "user",
+            content: input.text,
+            user_identifier: scope.userId,
+            userIdentifier: scope.userId,
+            metadata: input.metadata
+          }
+        ]
+      );
+    }
+  } else if (input.kind === "entity") {
+    const longTerm = nested(client, ["longTerm", "long_term"], client);
+    result = await callOptional(
+      longTerm,
+      ["addEntity"],
+      [
+        input.entityName ?? input.title ?? input.text,
+        input.entityType ?? "ENTITY",
+        neo4jEntityOptions(input)
+      ]
+    );
+    if (result === void 0) {
+      result = await callRequired(
+        longTerm,
+        ["add_entity"],
+        [
+          input.entityName ?? input.title ?? input.text,
+          input.entityType ?? "ENTITY",
+          neo4jWriteOptions(input)
+        ]
+      );
+    }
+  } else if (input.kind === "preference") {
+    const longTerm = nested(client, ["longTerm", "long_term"], client);
+    result = await callOptional(
+      longTerm,
+      ["addPreference"],
+      [input.category ?? "general", input.text, neo4jPreferenceOptions(input)]
+    );
+    if (result === void 0) {
+      result = await callRequired(
+        longTerm,
+        ["add_preference"],
+        [input.category ?? "general", input.text, neo4jWriteOptions(input)]
+      );
+    }
+  } else {
+    result = await callRequired(
+      nested(client, ["longTerm", "long_term"], client),
+      ["addFact", "add_fact"],
+      [
+        input.subject ?? input.title ?? input.kind,
+        input.predicate ?? "states",
+        input.object ?? input.text
+      ]
+    );
+  }
+  const id = idFromResult(result) ?? input.id ?? stableId("mem", `${input.kind}:${input.text}`);
+  return {
+    accepted: true,
+    id,
+    uri: `memory://${adapterId}/${encodeURIComponent(id)}`,
+    kind: input.kind,
+    metadata: { rawResult: result }
+  };
+}
+async function searchNeo4jMemory(client, query, options, adapterId) {
+  const searches = [];
+  const kinds = options.kinds;
+  const includeKind = (kind) => !kinds?.length || kinds.includes(kind);
+  const shortTerm = nested(client, ["shortTerm", "short_term"], {});
+  const longTerm = nested(client, ["longTerm", "long_term"], {});
+  const reasoning = nested(client, ["reasoning"], {});
+  if (includeKind("message")) {
+    searches.push(
+      callOptional(
+        shortTerm,
+        ["searchMessages", "search_messages"],
+        [query, searchMessagesOptions(options)]
+      ).then((result) => normalizeHits(result, { ...options, kinds: ["message"] }, adapterId))
+    );
+  }
+  if (includeKind("entity")) {
+    searches.push(
+      callOptional(
+        longTerm,
+        ["searchEntities", "search_entities"],
+        [query, searchEntitiesOptions(options)]
+      ).then((result) => normalizeHits(result, { ...options, kinds: ["entity"] }, adapterId))
+    );
+  }
+  if (includeKind("preference")) {
+    searches.push(
+      callOptional(
+        longTerm,
+        ["searchPreferences", "search_preferences"],
+        [query, searchPreferencesOptions(options)]
+      ).then((result) => normalizeHits(result, { ...options, kinds: ["preference"] }, adapterId))
+    );
+  }
+  if (includeKind("reasoning-trace")) {
+    searches.push(
+      callOptional(
+        reasoning,
+        ["getSimilarTraces", "get_similar_traces"],
+        [query, similarTracesOptions(options)]
+      ).then(
+        (result) => normalizeHits(result, { ...options, kinds: ["reasoning-trace"] }, adapterId)
+      )
+    );
+  }
+  const hits = (await Promise.all(searches)).flat();
+  return hits.sort((a, b) => (b.normalizedScore ?? b.score ?? 0) - (a.normalizedScore ?? a.score ?? 0)).slice(0, options.limit);
+}
+function neo4jOptions(options) {
+  return {
+    limit: options.limit,
+    k: options.limit,
+    min_score: options.minScore,
+    minScore: options.minScore,
+    user_identifier: options.scope?.userId,
+    userIdentifier: options.scope?.userId,
+    session_id: options.scope?.sessionId,
+    sessionId: options.scope?.sessionId,
+    namespace: options.scope?.namespace,
+    tenant_id: options.scope?.tenantId,
+    tenantId: options.scope?.tenantId,
+    kinds: options.kinds,
+    metadata: options.metadata
+  };
+}
+function searchMessagesOptions(options) {
+  return {
+    limit: options.limit,
+    sessionId: options.scope?.sessionId,
+    conversationId: options.scope?.sessionId,
+    threshold: options.minScore,
+    metadata: options.metadata
+  };
+}
+function searchEntitiesOptions(options) {
+  return {
+    limit: options.limit,
+    type: options.metadata?.type
+  };
+}
+function searchPreferencesOptions(options) {
+  return {
+    limit: options.limit,
+    category: options.metadata?.category
+  };
+}
+function similarTracesOptions(options) {
+  return {
+    limit: options.limit,
+    sessionId: options.scope?.sessionId,
+    successOnly: options.metadata?.successOnly
+  };
+}
+function neo4jWriteOptions(input) {
+  return {
+    user_identifier: input.scope?.userId,
+    userIdentifier: input.scope?.userId,
+    session_id: input.scope?.sessionId,
+    sessionId: input.scope?.sessionId,
+    namespace: input.scope?.namespace,
+    confidence: input.confidence,
+    metadata: input.metadata
+  };
+}
+function neo4jEntityOptions(input) {
+  return {
+    description: input.metadata?.description ?? input.title
+  };
+}
+function neo4jPreferenceOptions(input) {
+  return {
+    context: input.metadata?.context ?? input.title
+  };
+}
+async function callOptional(target, names, args) {
+  for (const name of names) {
+    const fn = target[name];
+    if (typeof fn === "function") return await fn.apply(target, args);
+  }
+  return void 0;
+}
+async function callRequired(target, names, args) {
+  const result = await callOptional(target, names, args);
+  if (result !== void 0) return result;
+  throw new Error(`Neo4j agent-memory client is missing method ${names.join(" or ")}`);
+}
+function nested(target, names, fallback) {
+  for (const name of names) {
+    const value = target[name];
+    if (value && typeof value === "object") return value;
+  }
+  return fallback;
+}
+function normalizeHits(value, options, adapterId) {
+  const rawHits = rawHitsFrom(value);
+  return rawHits.map((hit, index) => normalizeHit(hit, index, adapterId)).filter((hit) => hit !== null).filter(
+    (hit) => options.minScore === void 0 ? true : (hit.normalizedScore ?? hit.score ?? 0) >= options.minScore
+  ).filter((hit) => options.kinds?.length ? options.kinds.includes(hit.kind) : true).slice(0, options.limit);
+}
+function normalizeHit(value, index, adapterId) {
+  if (typeof value === "string") {
+    return {
+      id: stableId("mem", value),
+      uri: `memory://${adapterId}/${stableId("mem", value)}`,
+      kind: "fact",
+      text: value,
+      normalizedScore: index === 0 ? 1 : void 0
+    };
+  }
+  const obj = record(value);
+  if (!obj) return null;
+  const kind = memoryKind(stringField(obj, ["kind", "type", "label"]), obj);
+  const text = textFromHitObject(obj, kind);
+  if (!text) return null;
+  const id = stringField(obj, ["id", "memoryId", "uuid"]) ?? stableId("mem", text);
+  return {
+    id,
+    uri: stringField(obj, ["uri"]) ?? `memory://${adapterId}/${encodeURIComponent(id)}`,
+    kind,
+    text,
+    title: stringField(obj, ["title", "name", "task", "subject"]),
+    score: numberField(obj, ["score"]),
+    normalizedScore: numberField(obj, ["normalizedScore", "normalized_score"]),
+    confidence: numberField(obj, ["confidence"]),
+    createdAt: stringField(obj, ["createdAt", "created_at"]),
+    validUntil: stringField(obj, ["validUntil", "valid_until"]),
+    lastVerifiedAt: stringField(obj, ["lastVerifiedAt", "last_verified_at"]),
+    metadata: obj
+  };
+}
+function memoryKind(value, obj = {}) {
+  if (value === "message" || value === "entity" || value === "fact" || value === "preference" || value === "observation" || value === "reasoning-trace") {
+    return value;
+  }
+  if ("role" in obj && "content" in obj) return "message";
+  if ("name" in obj && ("type" in obj || "entityType" in obj)) return "entity";
+  if ("preference" in obj && "category" in obj) return "preference";
+  if ("task" in obj && "steps" in obj) return "reasoning-trace";
+  return "fact";
+}
+function rawHitsFrom(value) {
+  if (Array.isArray(value)) return value;
+  const obj = record(value);
+  if (!obj) return typeof value === "string" ? [value] : [];
+  if (Array.isArray(obj.hits)) return obj.hits;
+  if (Array.isArray(obj.results)) return obj.results;
+  if (Array.isArray(obj.messages)) return obj.messages;
+  if (Array.isArray(obj.recentMessages)) return obj.recentMessages;
+  if (Array.isArray(obj.observations)) return obj.observations;
+  if (Array.isArray(obj.reflections)) return obj.reflections;
+  if (typeof obj.content === "string" || typeof obj.text === "string") return [obj];
+  return [];
+}
+function textFromHitObject(obj, kind) {
+  const direct = stringField(obj, [
+    "text",
+    "content",
+    "body",
+    "summary",
+    "preference",
+    "description"
+  ]);
+  if (direct) return direct;
+  if (kind === "entity") return stringField(obj, ["name"]);
+  if (kind === "fact") {
+    const subject = stringField(obj, ["subject"]);
+    const predicate = stringField(obj, ["predicate"]);
+    const object = stringField(obj, ["object", "obj"]);
+    if (subject && predicate && object) return `${subject} ${predicate} ${object}`;
+  }
+  if (kind === "reasoning-trace") {
+    const task = stringField(obj, ["task"]);
+    const outcome = stringField(obj, ["outcome"]);
+    return [task, outcome].filter(Boolean).join("\n") || void 0;
+  }
+  return void 0;
+}
+function textFromConversationContext(value) {
+  const obj = record(value);
+  if (!obj) return void 0;
+  const parts = [
+    ...rawHitsFrom(obj.reflections).map((hit) => normalizeContextPart(hit)),
+    ...rawHitsFrom(obj.observations).map((hit) => normalizeContextPart(hit)),
+    ...rawHitsFrom(obj.recentMessages).map((hit) => normalizeContextPart(hit))
+  ].filter(Boolean);
+  return parts.length > 0 ? parts.join("\n\n") : void 0;
+}
+function normalizeConversationContextHits(value, options, adapterId) {
+  const obj = record(value);
+  if (!obj) return normalizeHits(value, options, adapterId);
+  const raw = [
+    ...rawHitsFrom(obj.reflections).map((hit) => tagContextHit(hit, "observation", "Reflection")),
+    ...rawHitsFrom(obj.observations).map((hit) => tagContextHit(hit, "observation", "Observation")),
+    ...rawHitsFrom(obj.recentMessages).map((hit) => tagContextHit(hit, "message"))
+  ];
+  return raw.length > 0 ? normalizeHits(raw, options, adapterId) : normalizeHits(value, options, adapterId);
+}
+function tagContextHit(value, kind, title) {
+  return value && typeof value === "object" && !Array.isArray(value) ? { kind, title, ...value } : { kind, title, content: value };
+}
+function normalizeContextPart(value) {
+  if (typeof value === "string") return value;
+  const obj = record(value);
+  return obj ? textFromHitObject(obj, memoryKind(stringField(obj, ["kind", "type", "label"]), obj)) : void 0;
+}
+function renderHits(hits) {
+  return hits.map((hit) => hit.text).join("\n\n");
+}
+function idFromResult(value) {
+  const obj = record(value);
+  return obj ? stringField(obj, ["id", "memoryId", "uuid"]) : void 0;
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringField(obj, names) {
+  for (const name of names) {
+    const value = obj[name];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
+function numberField(obj, names) {
+  for (const name of names) {
+    const value = obj[name];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+}
+
+// src/memory/schemas.ts
+import { z } from "zod";
+var AgentMemoryKindSchema = z.enum([
+  "message",
+  "entity",
+  "fact",
+  "preference",
+  "observation",
+  "reasoning-trace"
+]);
+var AgentMemoryScopeSchema = z.object({
+  tenantId: z.string().optional(),
+  userId: z.string().optional(),
+  sessionId: z.string().optional(),
+  namespace: z.string().optional(),
+  tags: z.record(z.string(), z.string()).optional()
+});
+var AgentMemoryHitSchema = z.object({
+  id: z.string().min(1),
+  uri: z.string().min(1),
+  kind: AgentMemoryKindSchema,
+  text: z.string().min(1),
+  title: z.string().optional(),
+  score: z.number().optional(),
+  normalizedScore: z.number().optional(),
+  confidence: z.number().optional(),
+  createdAt: z.string().optional(),
+  validUntil: z.string().optional(),
+  lastVerifiedAt: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var AgentMemoryWriteInputSchema = z.object({
+  kind: AgentMemoryKindSchema,
+  text: z.string().min(1),
+  id: z.string().optional(),
+  title: z.string().optional(),
+  role: z.enum(["system", "user", "assistant", "tool"]).optional(),
+  entityName: z.string().optional(),
+  entityType: z.string().optional(),
+  category: z.string().optional(),
+  predicate: z.string().optional(),
+  subject: z.string().optional(),
+  object: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  scope: AgentMemoryScopeSchema.optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+
+export {
+  memoryHitToSourceRecord,
+  memoryWriteResultToSourceRecord,
+  defaultGetMemoryContext,
+  renderMemoryContext,
+  createNeo4jAgentMemoryAdapter,
+  AgentMemoryKindSchema,
+  AgentMemoryScopeSchema,
+  AgentMemoryHitSchema,
+  AgentMemoryWriteInputSchema
+};
+//# sourceMappingURL=chunk-U6KQ4FS3.js.map