convex-agent-knowledge 0.0.1

package/dist/shared/ranking.js

@@ -0,0 +1,44 @@
+export function clamp(value, min = 0, max = 1) {
+    return Math.min(max, Math.max(min, value));
+}
+export function fuseMemoryScores(semanticCards, graphCards, options) {
+    const semanticWeight = options?.semanticWeight ?? 0.65;
+    const graphWeight = options?.graphWeight ?? 0.25;
+    const importanceWeight = options?.importanceWeight ?? 0.1;
+    const byMemoryId = new Map();
+    for (const card of semanticCards) {
+        byMemoryId.set(card.memoryId, {
+            ...card,
+            semanticScore: card.semanticScore ?? card.score,
+        });
+    }
+    for (const graphCard of graphCards) {
+        const current = byMemoryId.get(graphCard.memoryId);
+        if (current) {
+            byMemoryId.set(graphCard.memoryId, {
+                ...current,
+                graphScore: graphCard.graphScore ?? graphCard.score,
+            });
+        }
+        else {
+            byMemoryId.set(graphCard.memoryId, {
+                ...graphCard,
+                graphScore: graphCard.graphScore ?? graphCard.score,
+                semanticScore: graphCard.semanticScore ?? 0,
+            });
+        }
+    }
+    return [...byMemoryId.values()]
+        .map((card) => {
+        const semanticScore = card.semanticScore ?? 0;
+        const graphScore = card.graphScore ?? 0;
+        const importance = card.importance ?? 0;
+        return {
+            ...card,
+            score: semanticScore * semanticWeight + graphScore * graphWeight + importance * importanceWeight,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, options?.limit ?? 10);
+}
+//# sourceMappingURL=ranking.js.map

package/dist/shared/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../../src/shared/ranking.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,aAAkB,EAClB,UAAe,EACf,OAKC;IAED,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IACvD,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,IAAI,CAAC;IACjD,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,GAAG,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAa,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5B,GAAG,IAAI;YACP,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,KAAK;SAChD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,OAAO,EAAE,CAAC;YACZ,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,EAAE;gBACjC,GAAG,OAAO;gBACV,UAAU,EAAE,SAAS,CAAC,UAAU,IAAI,SAAS,CAAC,KAAK;aACpD,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,EAAE;gBACjC,GAAG,SAAS;gBACZ,UAAU,EAAE,SAAS,CAAC,UAAU,IAAI,SAAS,CAAC,KAAK;gBACnD,aAAa,EAAE,SAAS,CAAC,aAAa,IAAI,CAAC;aAC5C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;SAC5B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACxC,OAAO;YACL,GAAG,IAAI;YACP,KAAK,EACH,aAAa,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,gBAAgB;SAC5F,CAAC;IACJ,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "convex-agent-knowledge",
+  "version": "0.0.1",
+  "description": "Convex component for agent memory backed by Convex vector search and Neo4j graph traversal.",
+  "keywords": [
+    "agent",
+    "ai",
+    "convex",
+    "convex-component",
+    "knowledge-graph",
+    "memory",
+    "neo4j",
+    "vector-search"
+  ],
+  "homepage": "https://github.com/phl28/agent-knowledge#readme",
+  "bugs": {
+    "url": "https://github.com/phl28/agent-knowledge/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phl28/agent-knowledge.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/client/index.js",
+  "types": "./dist/client/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./convex.config": "./dist/component/convex.config.js",
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./chunking": {
+      "types": "./dist/client/chunking.d.ts",
+      "default": "./dist/client/chunking.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "ai": "^6.0.168",
+    "neo4j-driver": "^6.0.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "^3.0.53",
+    "@types/node": "^25.6.0",
+    "convex": "^1.35.1",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "convex": ">=1.29.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck",
+    "format": "oxfmt README.md package.json convex.json pnpm-workspace.yaml src example/convex '!src/component/_generated/**' '!example/convex/_generated/**'",
+    "format:check": "oxfmt --check README.md package.json convex.json pnpm-workspace.yaml src example/convex '!src/component/_generated/**' '!example/convex/_generated/**'",
+    "lint": "oxlint --deny correctness --vitest-plugin --ignore-pattern src/component/_generated --ignore-pattern example/convex/_generated .",
+    "lint:fix": "oxlint --deny correctness --vitest-plugin --fix --ignore-pattern src/component/_generated --ignore-pattern example/convex/_generated .",
+    "publish:alpha": "pnpm publish --tag alpha",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build:codegen": "convex codegen --component-dir ./src/component && pnpm build"
+  }
+}

package/src/client/chunking.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { chunkText } from "./chunking.js";
+
+describe("chunkText", () => {
+  it("returns no chunks for empty input", () => {
+    expect(chunkText("   ")).toEqual([]);
+  });
+
+  it("keeps short text as one chunk", () => {
+    expect(chunkText("Alice works on Convex components.")).toEqual([
+      {
+        text: "Alice works on Convex components.",
+        tokenCount: 9,
+      },
+    ]);
+  });
+
+  it("splits long text with overlap", () => {
+    const text = Array.from({ length: 60 }, (_, index) => `Sentence ${index}.`).join(" ");
+    const chunks = chunkText(text, { maxChars: 220, overlapChars: 30 });
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks[0]!.text.length).toBeLessThanOrEqual(220);
+    expect(chunks.at(-1)!.text).toContain("Sentence 59");
+  });
+});

package/src/client/chunking.ts

@@ -0,0 +1,45 @@
+import type { ChunkInput } from "./types.js";
+
+export type ChunkTextOptions = {
+  maxChars?: number;
+  overlapChars?: number;
+};
+
+export function chunkText(text: string, options?: ChunkTextOptions): ChunkInput[] {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return [];
+  }
+  const maxChars = Math.max(options?.maxChars ?? 1_500, 200);
+  const overlapChars = Math.min(options?.overlapChars ?? 150, Math.floor(maxChars / 3));
+  const chunks: ChunkInput[] = [];
+  let cursor = 0;
+
+  while (cursor < trimmed.length) {
+    const hardEnd = Math.min(cursor + maxChars, trimmed.length);
+    let end = hardEnd;
+    if (hardEnd < trimmed.length) {
+      const paragraphBreak = trimmed.lastIndexOf("\n\n", hardEnd);
+      const sentenceBreak = trimmed.lastIndexOf(". ", hardEnd);
+      const whitespaceBreak = trimmed.lastIndexOf(" ", hardEnd);
+      const bestBreak = Math.max(paragraphBreak, sentenceBreak, whitespaceBreak);
+      if (bestBreak > cursor + Math.floor(maxChars * 0.55)) {
+        end = bestBreak + (bestBreak === sentenceBreak ? 1 : 0);
+      }
+    }
+
+    const chunk = trimmed.slice(cursor, end).trim();
+    if (chunk) {
+      chunks.push({
+        text: chunk,
+        tokenCount: Math.ceil(chunk.length / 4),
+      });
+    }
+    if (end >= trimmed.length) {
+      break;
+    }
+    cursor = Math.max(end - overlapChars, cursor + 1);
+  }
+
+  return chunks;
+}

package/src/client/extraction.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { heuristicExtractKnowledge } from "./extraction.js";
+
+describe("heuristicExtractKnowledge", () => {
+  it("extracts capitalized entity candidates", () => {
+    const result = heuristicExtractKnowledge(
+      "agent:alice",
+      "Alice is building Agent Knowledge with Convex and Neo4j.",
+    );
+    expect(result.entities.map((entity) => entity.name)).toEqual(
+      expect.arrayContaining(["Alice", "Agent Knowledge", "Convex", "Neo4j"]),
+    );
+    expect(result.relationships).toEqual([]);
+  });
+});

package/src/client/extraction.ts

@@ -0,0 +1,108 @@
+import { generateObject } from "ai";
+import { z } from "zod";
+import type { ExtractedKnowledge } from "./types.js";
+import { normalizeEntityId } from "./hash.js";
+
+const extractionSchema = z.object({
+  entities: z.array(
+    z.object({
+      name: z.string(),
+      type: z.string().default("entity"),
+      description: z.string().optional(),
+      aliases: z.array(z.string()).optional(),
+      confidence: z.number().min(0).max(1).optional(),
+    }),
+  ),
+  relationships: z.array(
+    z.object({
+      from: z.string(),
+      to: z.string(),
+      type: z.string(),
+      description: z.string().optional(),
+      confidence: z.number().min(0).max(1).optional(),
+      weight: z.number().min(0).max(1).optional(),
+    }),
+  ),
+});
+
+export type ExtractKnowledgeOptions = {
+  namespace: string;
+  text: string;
+  model?: unknown;
+};
+
+export async function extractKnowledge(
+  options: ExtractKnowledgeOptions,
+): Promise<ExtractedKnowledge> {
+  if (options.model) {
+    const result = await generateObject({
+      model: options.model as never,
+      schema: extractionSchema,
+      prompt: [
+        "Extract entities and relationships useful for long-lived agent memory.",
+        "Use concise entity names. Relationship types should be uppercase snake case.",
+        "Only include facts supported by the text.",
+        "",
+        options.text,
+      ].join("\n"),
+    });
+    const byName = new Map<string, string>();
+    const entities = result.object.entities.map((entity) => {
+      const externalId = normalizeEntityId(options.namespace, entity.name, entity.type);
+      byName.set(entity.name.toLowerCase(), externalId);
+      return {
+        externalId,
+        name: entity.name,
+        type: entity.type,
+        ...(entity.description === undefined ? {} : { description: entity.description }),
+        ...(entity.aliases === undefined ? {} : { aliases: entity.aliases }),
+        confidence: entity.confidence ?? 0.75,
+      };
+    });
+    return {
+      entities,
+      relationships: result.object.relationships
+        .map((relationship) => {
+          const fromEntityExternalId = byName.get(relationship.from.toLowerCase());
+          const toEntityExternalId = byName.get(relationship.to.toLowerCase());
+          if (!fromEntityExternalId || !toEntityExternalId) {
+            return null;
+          }
+          return {
+            fromEntityExternalId,
+            toEntityExternalId,
+            type: relationship.type,
+            ...(relationship.description === undefined
+              ? {}
+              : { description: relationship.description }),
+            confidence: relationship.confidence ?? 0.75,
+            weight: relationship.weight ?? 0.5,
+          };
+        })
+        .filter((relationship): relationship is NonNullable<typeof relationship> =>
+          Boolean(relationship),
+        ),
+    };
+  }
+
+  return heuristicExtractKnowledge(options.namespace, options.text);
+}
+
+export function heuristicExtractKnowledge(namespace: string, text: string): ExtractedKnowledge {
+  const candidates = new Set<string>();
+  for (const match of text.matchAll(
+    /\b[A-Z][a-zA-Z0-9_-]{2,}(?:\s+[A-Z][a-zA-Z0-9_-]{2,}){0,3}\b/g,
+  )) {
+    candidates.add(match[0]);
+  }
+  const entities = [...candidates].slice(0, 24).map((name) => ({
+    externalId: normalizeEntityId(namespace, name),
+    name,
+    type: "entity",
+    confidence: 0.45,
+  }));
+  return {
+    entities,
+    relationships: [],
+  };
+}

package/src/client/hash.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { normalizeEntityId, stableHash } from "./hash.js";
+
+describe("stableHash", () => {
+  it("is deterministic", () => {
+    expect(stableHash("agent memory")).toBe(stableHash("agent memory"));
+    expect(stableHash("agent memory")).not.toBe(stableHash("other memory"));
+  });
+});
+
+describe("normalizeEntityId", () => {
+  it("builds namespace-scoped entity IDs", () => {
+    expect(normalizeEntityId("agent:alice", "Convex Components", "tool")).toBe(
+      "agent:alice:tool:convex-components",
+    );
+  });
+});

package/src/client/hash.ts

@@ -0,0 +1,17 @@
+export function stableHash(value: string) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function normalizeEntityId(namespace: string, name: string, type = "entity") {
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return `${namespace}:${type}:${normalized || stableHash(name)}`;
+}

package/src/client/index.ts

@@ -0,0 +1,307 @@
+import { embed, embedMany } from "ai";
+import { chunkText, type ChunkTextOptions } from "./chunking.js";
+import { extractKnowledge } from "./extraction.js";
+import { stableHash } from "./hash.js";
+import { fuseMemoryScores } from "../shared/ranking.js";
+import type {
+  AgentKnowledgeComponent,
+  ChunkInput,
+  ConvexActionCtx,
+  ConvexMutationCtx,
+  ConvexQueryCtx,
+  EmbeddedChunkInput,
+  ExtractedKnowledge,
+  GraphStore,
+  GraphSyncJob,
+  MemoryCard,
+  MemorySource,
+  SearchType,
+} from "./types.js";
+
+export type AgentKnowledgeOptions = {
+  textEmbeddingModel?: unknown;
+  embeddingDimension: number;
+  extractionModel?: unknown;
+  graph?: GraphStore;
+  chunking?: ChunkTextOptions;
+  extract?: (input: {
+    namespace: string;
+    text: string;
+    chunks: ChunkInput[];
+  }) => Promise<ExtractedKnowledge>;
+};
+
+export type RememberInput = {
+  namespace: string;
+  key?: string;
+  agentId?: string;
+  text: string;
+  source?: MemorySource;
+  metadata?: unknown;
+  importance?: number;
+  chunks?: ChunkInput[];
+  extracted?: ExtractedKnowledge;
+};
+
+export type RecallInput = {
+  namespace: string;
+  query: string;
+  searchType?: SearchType;
+  limit?: number;
+  agentId?: string;
+  entityHints?: string[];
+  queryEmbedding?: number[];
+  graph?: GraphStore;
+};
+
+export type ObserveInput = {
+  namespace: string;
+  memoryId: string;
+  query: string;
+  outcome: "helpful" | "not_helpful" | "neutral";
+  feedback?: string;
+  metadata?: unknown;
+};
+
+export class AgentKnowledge {
+  constructor(
+    private readonly component: AgentKnowledgeComponent,
+    private readonly options: AgentKnowledgeOptions,
+  ) {}
+
+  async remember(ctx: ConvexActionCtx, input: RememberInput) {
+    const chunks = input.chunks ?? chunkText(input.text, this.options.chunking);
+    if (chunks.length === 0) {
+      throw new Error("Cannot remember empty text");
+    }
+    const embeddedChunks = await this.embedChunks(chunks);
+    const extracted =
+      input.extracted ??
+      (this.options.extract
+        ? await this.options.extract({
+            namespace: input.namespace,
+            text: input.text,
+            chunks,
+          })
+        : await extractKnowledge({
+            namespace: input.namespace,
+            text: input.text,
+            model: this.options.extractionModel,
+          }));
+
+    const mutationArgs = {
+      namespace: input.namespace,
+      ...(input.key === undefined ? {} : { key: input.key }),
+      ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+      text: input.text,
+      contentHash: stableHash(`${input.namespace}:${input.text}`),
+      ...(input.source === undefined ? {} : { source: input.source }),
+      ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+      ...(input.importance === undefined ? {} : { importance: input.importance }),
+      embeddingDimension: this.options.embeddingDimension,
+      chunks: embeddedChunks,
+      entities: extracted.entities,
+      relationships: extracted.relationships,
+    };
+
+    const result = await ctx.runMutation(this.component.mutations.remember, mutationArgs);
+    if (this.options.graph) {
+      await this.syncGraph(ctx, { limit: 10 });
+    }
+    return result as {
+      memoryId: string;
+      replacedMemoryId?: string;
+      chunkCount: number;
+      entityCount: number;
+      relationshipCount: number;
+      graphSyncJobId: string;
+    };
+  }
+
+  async recall(ctx: ConvexActionCtx, input: RecallInput) {
+    const searchType = input.searchType ?? "hybrid";
+    const limit = input.limit ?? 10;
+    const queryEmbedding =
+      input.queryEmbedding ??
+      (searchType === "graph" ? undefined : await this.embedQuery(input.query));
+    const semanticResult =
+      searchType === "graph"
+        ? { results: [] as MemoryCard[] }
+        : ((await ctx.runAction(this.component.actions.recall, {
+            namespace: input.namespace,
+            query: input.query,
+            ...(queryEmbedding === undefined ? {} : { queryEmbedding }),
+            embeddingDimension: this.options.embeddingDimension,
+            searchType,
+            limit,
+            ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+          })) as { results: MemoryCard[] });
+
+    const graph = input.graph ?? this.options.graph;
+    if (!graph || searchType === "semantic") {
+      return semanticResult;
+    }
+
+    const graphScores = await graph.expand({
+      namespace: input.namespace,
+      seedMemoryIds: semanticResult.results.map((card) => card.memoryId),
+      hops: 2,
+      limit: Math.max(limit * 4, 16),
+      ...(input.entityHints === undefined ? {} : { entityHints: input.entityHints }),
+    });
+    const graphCards =
+      graphScores.length === 0
+        ? []
+        : ((await ctx.runQuery(this.component.queries.fetchMemoryCards, {
+            matches: graphScores.map((score) => ({
+              memoryId: score.memoryId,
+              score: score.graphScore,
+              graphScore: score.graphScore,
+            })),
+          })) as MemoryCard[]);
+
+    return {
+      results: fuseMemoryScores(semanticResult.results, graphCards, { limit }),
+    };
+  }
+
+  async observe(ctx: ConvexMutationCtx, input: ObserveInput) {
+    return await ctx.runMutation(this.component.mutations.observe, {
+      namespace: input.namespace,
+      memoryId: input.memoryId,
+      query: input.query,
+      outcome: input.outcome,
+      ...(input.feedback === undefined ? {} : { feedback: input.feedback }),
+      ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+    });
+  }
+
+  async promote(ctx: ConvexMutationCtx, input: { namespace: string; limit?: number }) {
+    return (await ctx.runMutation(this.component.mutations.promote, {
+      namespace: input.namespace,
+      ...(input.limit === undefined ? {} : { limit: input.limit }),
+    })) as { promoted: number };
+  }
+
+  async deleteByKey(ctx: ConvexMutationCtx, input: { namespace: string; key: string }) {
+    return (await ctx.runMutation(this.component.mutations.deleteByKey, {
+      namespace: input.namespace,
+      key: input.key,
+    })) as {
+      deleted: boolean;
+      memoryId?: string;
+      graphSyncJobId?: string;
+    };
+  }
+
+  async getMemory(ctx: ConvexQueryCtx, input: { memoryId: string }) {
+    return (await ctx.runQuery(this.component.queries.getMemory, {
+      memoryId: input.memoryId,
+    })) as MemoryCard | null;
+  }
+
+  async listMemories(
+    ctx: ConvexQueryCtx,
+    input: { namespace: string; limit?: number; cursor?: string },
+  ) {
+    return (await ctx.runQuery(this.component.queries.listMemories, {
+      namespace: input.namespace,
+      ...(input.limit === undefined ? {} : { limit: input.limit }),
+      ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+    })) as {
+      page: MemoryCard[];
+      continueCursor: string | null;
+      isDone: boolean;
+    };
+  }
+
+  async syncGraph(ctx: ConvexActionCtx, input?: { graph?: GraphStore; limit?: number }) {
+    const graph = input?.graph ?? this.options.graph;
+    if (!graph) {
+      return { succeeded: 0, failed: 0 };
+    }
+    const jobs = (await ctx.runQuery(this.component.queries.listPendingGraphSyncJobs, {
+      limit: input?.limit ?? 10,
+    })) as GraphSyncJob[];
+    let succeeded = 0;
+    let failed = 0;
+    for (const job of jobs) {
+      await ctx.runMutation(this.component.mutations.markGraphSyncJobRunning, {
+        jobId: job.jobId,
+      });
+      try {
+        await graph.syncJob(job);
+        await ctx.runMutation(this.component.mutations.markGraphSyncJobSucceeded, {
+          jobId: job.jobId,
+        });
+        succeeded += 1;
+      } catch (error) {
+        await ctx.runMutation(this.component.mutations.markGraphSyncJobFailed, {
+          jobId: job.jobId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        failed += 1;
+      }
+    }
+    return { succeeded, failed };
+  }
+
+  private async embedChunks(chunks: ChunkInput[]): Promise<EmbeddedChunkInput[]> {
+    if (!this.options.textEmbeddingModel) {
+      throw new Error("AgentKnowledge requires textEmbeddingModel to remember text");
+    }
+    const result = await embedMany({
+      model: this.options.textEmbeddingModel as never,
+      values: chunks.map((chunk) => chunk.text),
+    });
+    return chunks.map((chunk, index) => {
+      const embedding = result.embeddings[index];
+      if (!embedding) {
+        throw new Error(`Missing embedding for chunk ${index}`);
+      }
+      if (embedding.length !== this.options.embeddingDimension) {
+        throw new Error(
+          `Embedding dimension ${embedding.length} does not match configured dimension ${this.options.embeddingDimension}`,
+        );
+      }
+      return {
+        ...chunk,
+        embedding,
+      };
+    });
+  }
+
+  private async embedQuery(query: string) {
+    if (!this.options.textEmbeddingModel) {
+      throw new Error("AgentKnowledge requires textEmbeddingModel for semantic or hybrid recall");
+    }
+    const result = await embed({
+      model: this.options.textEmbeddingModel as never,
+      value: query,
+    });
+    if (result.embedding.length !== this.options.embeddingDimension) {
+      throw new Error(
+        `Embedding dimension ${result.embedding.length} does not match configured dimension ${this.options.embeddingDimension}`,
+      );
+    }
+    return result.embedding;
+  }
+}
+
+export { chunkText } from "./chunking.js";
+export { extractKnowledge, heuristicExtractKnowledge } from "./extraction.js";
+export type {
+  ChunkInput,
+  EmbeddedChunkInput,
+  ExtractedEntity,
+  ExtractedKnowledge,
+  ExtractedRelationship,
+  GraphExpandInput,
+  GraphMemoryScore,
+  GraphStore,
+  GraphSyncJob,
+  MemoryCard,
+  MemorySource,
+  Neo4jConfig,
+  SearchType,
+} from "./types.js";