@orquentra/codebuddy 0.0.0-stage → 2.4.1

package/dist/memory-NIBFAMY4.js

@@ -0,0 +1,57 @@
+import {
+  memoryCandidateSchema
+} from "./chunk-IHQM2ZDV.js";
+import {
+  chatJson
+} from "./chunk-IE2OUO54.js";
+import {
+  redactSensitive
+} from "./chunk-GDJH7XJC.js";
+import {
+  resolveLlmConfig
+} from "./chunk-ITGRANYW.js";
+import "./chunk-K63EOA4B.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/llm/memory.ts
+import { z } from "zod";
+var TIMEOUT_MS = 2e4;
+var schema = z.object({ candidates: z.array(memoryCandidateSchema).max(10) });
+var SYSTEM = [
+  "You turn the summary of one coding turn into durable project memory.",
+  'Answer with JSON only: {"candidates":[{"class":"fact|decision|incident|note|ignored","content":"...","subject":"...","predicate":"...","object":"...","confidence":0.0,"paths":["..."],"severity":null}]}.',
+  "Keep only what will still be true and useful in a later session: decisions, confirmed bugs and their causes, project facts.",
+  "Use only paths named in the input. Confidence below 0.7 for anything uncertain. Chatter is class ignored.",
+  "Never include secrets."
+].join(" ");
+function createLlmMemoryExtractor(root, config) {
+  return {
+    async extract(input) {
+      const result = await chatJson(config, {
+        system: SYSTEM,
+        user: JSON.stringify({
+          summary: redactSensitive(input.summary),
+          changedFiles: (input.changedFiles ?? []).map(redactSensitive),
+          verification: (input.verification ?? []).map(redactSensitive)
+        }),
+        schema,
+        maxTokens: 800,
+        deadlineMs: TIMEOUT_MS,
+        purpose: "background",
+        repositoryRoot: root
+      });
+      if (!result.ok) throw new Error(`llm memory extraction: ${result.reason}`);
+      return result.value.candidates;
+    }
+  };
+}
+async function llmCaptureOptions(root, env = process.env) {
+  const config = await resolveLlmConfig(root, env);
+  if (!config.enabled || !config.features.memory) return {};
+  return { extractor: createLlmMemoryExtractor(root, config), retries: 0 };
+}
+export {
+  createLlmMemoryExtractor,
+  llmCaptureOptions
+};
+//# sourceMappingURL=memory-NIBFAMY4.js.map

package/dist/memory-NIBFAMY4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/llm/memory.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { MemoryExtractor } from \"../memory-extract/llm.js\";\nimport { redactSensitive } from \"../memory-extract/sensitive.js\";\nimport { type ExtractionInput, memoryCandidateSchema } from \"../memory-extract/types.js\";\nimport { chatJson } from \"./client.js\";\nimport { type EnabledLlmConfig, resolveLlmConfig } from \"./config.js\";\n\n/**\n * Optional BYOK memory extraction through the existing `MemoryExtractor`\n * seam. Output must match `memoryCandidateSchema` and then passes the same\n * gate as deterministic candidates (sensitive scan, confidence, review);\n * any failure falls back to deterministic extraction.\n */\nconst TIMEOUT_MS = 20_000;\nconst schema = z.object({ candidates: z.array(memoryCandidateSchema).max(10) });\n\nconst SYSTEM = [\n  \"You turn the summary of one coding turn into durable project memory.\",\n  'Answer with JSON only: {\"candidates\":[{\"class\":\"fact|decision|incident|note|ignored\",\"content\":\"...\",\"subject\":\"...\",\"predicate\":\"...\",\"object\":\"...\",\"confidence\":0.0,\"paths\":[\"...\"],\"severity\":null}]}.',\n  \"Keep only what will still be true and useful in a later session: decisions, confirmed bugs and their causes, project facts.\",\n  \"Use only paths named in the input. Confidence below 0.7 for anything uncertain. Chatter is class ignored.\",\n  \"Never include secrets.\",\n].join(\" \");\n\nexport function createLlmMemoryExtractor(root: string, config: EnabledLlmConfig): MemoryExtractor {\n  return {\n    async extract(input: ExtractionInput) {\n      const result = await chatJson(config, {\n        system: SYSTEM,\n        user: JSON.stringify({\n          summary: redactSensitive(input.summary),\n          changedFiles: (input.changedFiles ?? []).map(redactSensitive),\n          verification: (input.verification ?? []).map(redactSensitive),\n        }),\n        schema,\n        maxTokens: 800,\n        deadlineMs: TIMEOUT_MS,\n        purpose: \"background\",\n        repositoryRoot: root,\n      });\n      if (!result.ok) throw new Error(`llm memory extraction: ${result.reason}`);\n      return result.value.candidates;\n    },\n  };\n}\n\n/** Extra `captureAfterTurn` options when the memory feature is on: one attempt, then deterministic. */\nexport async function llmCaptureOptions(\n  root: string,\n  env: NodeJS.ProcessEnv = process.env,\n): Promise<{ extractor?: MemoryExtractor; retries?: number }> {\n  const config = await resolveLlmConfig(root, env);\n  if (!config.enabled || !config.features.memory) return {};\n  return { extractor: createLlmMemoryExtractor(root, config), retries: 0 };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA,SAAS,SAAS;AAalB,IAAM,aAAa;AACnB,IAAM,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,EAAE,IAAI,EAAE,EAAE,CAAC;AAE9E,IAAM,SAAS;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAEH,SAAS,yBAAyB,MAAc,QAA2C;AAChG,SAAO;AAAA,IACL,MAAM,QAAQ,OAAwB;AACpC,YAAM,SAAS,MAAM,SAAS,QAAQ;AAAA,QACpC,QAAQ;AAAA,QACR,MAAM,KAAK,UAAU;AAAA,UACnB,SAAS,gBAAgB,MAAM,OAAO;AAAA,UACtC,eAAe,MAAM,gBAAgB,CAAC,GAAG,IAAI,eAAe;AAAA,UAC5D,eAAe,MAAM,gBAAgB,CAAC,GAAG,IAAI,eAAe;AAAA,QAC9D,CAAC;AAAA,QACD;AAAA,QACA,WAAW;AAAA,QACX,YAAY;AAAA,QACZ,SAAS;AAAA,QACT,gBAAgB;AAAA,MAClB,CAAC;AACD,UAAI,CAAC,OAAO,GAAI,OAAM,IAAI,MAAM,0BAA0B,OAAO,MAAM,EAAE;AACzE,aAAO,OAAO,MAAM;AAAA,IACtB;AAAA,EACF;AACF;AAGA,eAAsB,kBACpB,MACA,MAAyB,QAAQ,KAC2B;AAC5D,QAAM,SAAS,MAAM,iBAAiB,MAAM,GAAG;AAC/C,MAAI,CAAC,OAAO,WAAW,CAAC,OAAO,SAAS,OAAQ,QAAO,CAAC;AACxD,SAAO,EAAE,WAAW,yBAAyB,MAAM,MAAM,GAAG,SAAS,EAAE;AACzE;","names":[]}

package/dist/pretool-command-MQQ2UNQM.js

@@ -0,0 +1,10 @@
+import {
+  runPreToolHookCommand
+} from "./chunk-WHZSVY2L.js";
+import "./chunk-PYLH4MH5.js";
+import "./chunk-PQK3GKZH.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  runPreToolHookCommand
+};
+//# sourceMappingURL=pretool-command-MQQ2UNQM.js.map

package/dist/pretool-command-MQQ2UNQM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/rerank-Q7MIFNKA.js

@@ -0,0 +1,60 @@
+import {
+  chatJson
+} from "./chunk-IE2OUO54.js";
+import {
+  redactSensitive
+} from "./chunk-GDJH7XJC.js";
+import "./chunk-ITGRANYW.js";
+import "./chunk-K63EOA4B.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/llm/rerank.ts
+import { createHash } from "crypto";
+import { z } from "zod";
+var RERANK_PROMPT_VERSION = 1;
+var LIMITS = { candidates: 15, picks: 3, signatures: 5, reason: 80, maxTokens: 300 };
+var schema = z.object({
+  files: z.array(
+    z.object({
+      path: z.string(),
+      symbols: z.array(z.string()).default([]),
+      reason: z.string().default("")
+    })
+  ).default([]),
+  abstain: z.boolean().default(false)
+});
+var SYSTEM = [
+  "You pick the source files a coding agent must open for a task.",
+  'Answer with JSON only: {"files":[{"path":"...","symbols":["..."],"reason":"..."}],"abstain":false}.',
+  `Choose at most ${LIMITS.picks} files, best first, only from the candidates given;`,
+  "name the functions or classes to look at when you can (from the listed signatures);",
+  "reason: a few words. If no candidate fits the task, answer with an empty files list and abstain true."
+].join(" ");
+async function rerankCandidates(root, config, task, candidates, deadlineMs) {
+  const sent = candidates.slice(0, LIMITS.candidates).map((candidate) => ({
+    path: candidate.path,
+    summary: redactSensitive(candidate.summary),
+    signatures: candidate.signatures.slice(0, LIMITS.signatures).map(redactSensitive)
+  }));
+  const user = JSON.stringify({ task: redactSensitive(task), candidates: sent });
+  const result = await chatJson(config, {
+    system: SYSTEM,
+    user,
+    schema,
+    maxTokens: LIMITS.maxTokens,
+    deadlineMs,
+    purpose: "prompt",
+    repositoryRoot: root,
+    cacheKey: createHash("sha256").update(`rerank:${RERANK_PROMPT_VERSION}:${user}`).digest("hex")
+  });
+  if (!result.ok) return result;
+  const allowed = new Set(sent.map((candidate) => candidate.path));
+  const seen = /* @__PURE__ */ new Set();
+  const files = result.value.files.filter((file) => allowed.has(file.path) && !seen.has(file.path) && seen.add(file.path)).slice(0, LIMITS.picks).map((file) => ({ ...file, reason: file.reason.slice(0, LIMITS.reason) }));
+  return { ...result, value: { files, abstain: result.value.abstain && files.length === 0 } };
+}
+export {
+  RERANK_PROMPT_VERSION,
+  rerankCandidates
+};
+//# sourceMappingURL=rerank-Q7MIFNKA.js.map

package/dist/rerank-Q7MIFNKA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/llm/rerank.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\nimport { redactSensitive } from \"../memory-extract/sensitive.js\";\nimport { chatJson, type LlmResult } from \"./client.js\";\nimport type { EnabledLlmConfig } from \"./config.js\";\n\n/**\n * Prompt-time rerank: the model sees the task and up to 15 candidate files\n * (path, one-line summary, a few signatures, never bodies) and picks at most\n * three, or abstains. The caller validates every pick against the candidates,\n * the symbol table and the evidence rules; this module only asks.\n */\nexport const RERANK_PROMPT_VERSION = 1;\nconst LIMITS = { candidates: 15, picks: 3, signatures: 5, reason: 80, maxTokens: 300 } as const;\n\nexport type RerankCandidate = { path: string; summary: string; signatures: string[] };\nexport type RerankPick = { path: string; symbols: string[]; reason: string };\n\nconst schema = z.object({\n  files: z\n    .array(\n      z.object({\n        path: z.string(),\n        symbols: z.array(z.string()).default([]),\n        reason: z.string().default(\"\"),\n      }),\n    )\n    .default([]),\n  abstain: z.boolean().default(false),\n});\n\nconst SYSTEM = [\n  \"You pick the source files a coding agent must open for a task.\",\n  'Answer with JSON only: {\"files\":[{\"path\":\"...\",\"symbols\":[\"...\"],\"reason\":\"...\"}],\"abstain\":false}.',\n  `Choose at most ${LIMITS.picks} files, best first, only from the candidates given;`,\n  \"name the functions or classes to look at when you can (from the listed signatures);\",\n  \"reason: a few words. If no candidate fits the task, answer with an empty files list and abstain true.\",\n].join(\" \");\n\nexport async function rerankCandidates(\n  root: string,\n  config: EnabledLlmConfig,\n  task: string,\n  candidates: RerankCandidate[],\n  deadlineMs: number,\n): Promise<LlmResult<{ files: RerankPick[]; abstain: boolean }>> {\n  const sent = candidates.slice(0, LIMITS.candidates).map((candidate) => ({\n    path: candidate.path,\n    summary: redactSensitive(candidate.summary),\n    signatures: candidate.signatures.slice(0, LIMITS.signatures).map(redactSensitive),\n  }));\n  const user = JSON.stringify({ task: redactSensitive(task), candidates: sent });\n  const result = await chatJson(config, {\n    system: SYSTEM,\n    user,\n    schema,\n    maxTokens: LIMITS.maxTokens,\n    deadlineMs,\n    purpose: \"prompt\",\n    repositoryRoot: root,\n    cacheKey: createHash(\"sha256\").update(`rerank:${RERANK_PROMPT_VERSION}:${user}`).digest(\"hex\"),\n  });\n  if (!result.ok) return result;\n  const allowed = new Set(sent.map((candidate) => candidate.path));\n  const seen = new Set<string>();\n  const files = result.value.files\n    .filter((file) => allowed.has(file.path) && !seen.has(file.path) && seen.add(file.path))\n    .slice(0, LIMITS.picks)\n    .map((file) => ({ ...file, reason: file.reason.slice(0, LIMITS.reason) }));\n  return { ...result, value: { files, abstain: result.value.abstain && files.length === 0 } };\n}\n"],"mappings":";;;;;;;;;;;AAAA,SAAS,kBAAkB;AAC3B,SAAS,SAAS;AAWX,IAAM,wBAAwB;AACrC,IAAM,SAAS,EAAE,YAAY,IAAI,OAAO,GAAG,YAAY,GAAG,QAAQ,IAAI,WAAW,IAAI;AAKrF,IAAM,SAAS,EAAE,OAAO;AAAA,EACtB,OAAO,EACJ;AAAA,IACC,EAAE,OAAO;AAAA,MACP,MAAM,EAAE,OAAO;AAAA,MACf,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;AAAA,MACvC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;AAAA,IAC/B,CAAC;AAAA,EACH,EACC,QAAQ,CAAC,CAAC;AAAA,EACb,SAAS,EAAE,QAAQ,EAAE,QAAQ,KAAK;AACpC,CAAC;AAED,IAAM,SAAS;AAAA,EACb;AAAA,EACA;AAAA,EACA,kBAAkB,OAAO,KAAK;AAAA,EAC9B;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAEV,eAAsB,iBACpB,MACA,QACA,MACA,YACA,YAC+D;AAC/D,QAAM,OAAO,WAAW,MAAM,GAAG,OAAO,UAAU,EAAE,IAAI,CAAC,eAAe;AAAA,IACtE,MAAM,UAAU;AAAA,IAChB,SAAS,gBAAgB,UAAU,OAAO;AAAA,IAC1C,YAAY,UAAU,WAAW,MAAM,GAAG,OAAO,UAAU,EAAE,IAAI,eAAe;AAAA,EAClF,EAAE;AACF,QAAM,OAAO,KAAK,UAAU,EAAE,MAAM,gBAAgB,IAAI,GAAG,YAAY,KAAK,CAAC;AAC7E,QAAM,SAAS,MAAM,SAAS,QAAQ;AAAA,IACpC,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,WAAW,OAAO;AAAA,IAClB;AAAA,IACA,SAAS;AAAA,IACT,gBAAgB;AAAA,IAChB,UAAU,WAAW,QAAQ,EAAE,OAAO,UAAU,qBAAqB,IAAI,IAAI,EAAE,EAAE,OAAO,KAAK;AAAA,EAC/F,CAAC;AACD,MAAI,CAAC,OAAO,GAAI,QAAO;AACvB,QAAM,UAAU,IAAI,IAAI,KAAK,IAAI,CAAC,cAAc,UAAU,IAAI,CAAC;AAC/D,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAQ,OAAO,MAAM,MACxB,OAAO,CAAC,SAAS,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,IAAI,CAAC,EACtF,MAAM,GAAG,OAAO,KAAK,EACrB,IAAI,CAAC,UAAU,EAAE,GAAG,MAAM,QAAQ,KAAK,OAAO,MAAM,GAAG,OAAO,MAAM,EAAE,EAAE;AAC3E,SAAO,EAAE,GAAG,QAAQ,OAAO,EAAE,OAAO,SAAS,OAAO,MAAM,WAAW,MAAM,WAAW,EAAE,EAAE;AAC5F;","names":[]}

package/dist/summaries-TSE44KUQ.js

@@ -0,0 +1,18 @@
+import {
+  SUMMARY_PROMPT_VERSION,
+  loadLlmSummaries,
+  summarizeRepository
+} from "./chunk-3ZELDCR3.js";
+import "./chunk-IBMJYIEP.js";
+import "./chunk-PQK3GKZH.js";
+import "./chunk-IE2OUO54.js";
+import "./chunk-GDJH7XJC.js";
+import "./chunk-ITGRANYW.js";
+import "./chunk-K63EOA4B.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  SUMMARY_PROMPT_VERSION,
+  loadLlmSummaries,
+  summarizeRepository
+};
+//# sourceMappingURL=summaries-TSE44KUQ.js.map

package/dist/summaries-TSE44KUQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/zvec-F27AR357.js

@@ -0,0 +1,23 @@
+import {
+  DEFAULT_ZVEC_MODEL,
+  buildZvecIndex,
+  parseHits,
+  refreshZvecIndex,
+  resetZvecCache,
+  zvecCandidates,
+  zvecExcludeGlobs,
+  zvecStatus
+} from "./chunk-TI5TQD6D.js";
+import "./chunk-K63EOA4B.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  DEFAULT_ZVEC_MODEL,
+  buildZvecIndex,
+  parseHits,
+  refreshZvecIndex,
+  resetZvecCache,
+  zvecCandidates,
+  zvecExcludeGlobs,
+  zvecStatus
+};
+//# sourceMappingURL=zvec-F27AR357.js.map

package/dist/zvec-F27AR357.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    container_name: codebuddy-postgres
+    environment:
+      POSTGRES_USER: codebuddy
+      POSTGRES_PASSWORD: codebuddy
+      POSTGRES_DB: codebuddy
+    ports:
+      - "5432:5432"
+    volumes:
+      - codebuddy-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U codebuddy -d codebuddy"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  codebuddy-postgres-data:

package/examples/claude-code/README.md

@@ -0,0 +1,67 @@
+# Claude Code MCP Example
+
+Use CodeBuddy as a Claude Code memory server through MCP stdio.
+
+## Local Package Development
+
+From this repository:
+
+```bash
+npm install
+npm run build
+docker compose up -d
+```
+
+Set your environment:
+
+```bash
+export DATABASE_URL=postgres://codebuddy:codebuddy@localhost:5432/codebuddy
+export HF_TOKEN=hf_your_token
+export CODEBUDDY_NAMESPACE=claude-code
+```
+
+Run a quick health check:
+
+```bash
+node dist/cli/index.js doctor --skip-model-check
+```
+
+## Project MCP Config
+
+Add a `.mcp.json` file to the project where you use Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "codebuddy": {
+      "command": "node",
+      "args": ["/absolute/path/to/codebuddy/dist/cli/index.js", "serve"],
+      "env": {
+        "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
+        "HF_TOKEN": "hf_your_token",
+        "CODEBUDDY_NAMESPACE": "claude-code"
+      }
+    }
+  }
+}
+```
+
+For an installed package, use:
+
+```json
+{
+  "mcpServers": {
+    "codebuddy": {
+      "command": "codebuddy",
+      "args": ["serve"],
+      "env": {
+        "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
+        "HF_TOKEN": "hf_your_token",
+        "CODEBUDDY_NAMESPACE": "claude-code"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code after adding or changing MCP config. The available tools are `remember`, `remember_batch`, `recall`, `list_facts`, `list_namespaces`, `forget`, and `share`.

package/examples/claude-desktop/README.md

@@ -0,0 +1,54 @@
+# Claude Desktop MCP Example
+
+This example runs CodeBuddy as an MCP stdio server for Claude Desktop.
+
+## Prerequisites
+
+```bash
+docker compose up -d
+export DATABASE_URL=postgres://codebuddy:codebuddy@localhost:5432/codebuddy
+export HF_TOKEN=hf_your_token
+npm run build
+node dist/cli/index.js init
+node dist/cli/index.js doctor --skip-model-check
+```
+
+## Claude Desktop Config
+
+Copy `claude_desktop_config.json` into your Claude Desktop MCP configuration location and replace `hf_replace_me` with your Hugging Face token.
+
+The server command is:
+
+```bash
+npx codebuddy serve
+```
+
+For local development from this repository, use:
+
+```json
+{
+  "mcpServers": {
+    "codebuddy": {
+      "command": "node",
+      "args": ["/absolute/path/to/codebuddy/dist/cli/index.js", "serve"],
+      "env": {
+        "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
+        "HF_TOKEN": "hf_your_token",
+        "CODEBUDDY_NAMESPACE": "claude-desktop"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+- `remember`
+- `remember_batch`
+- `recall`
+- `list_facts`
+- `list_namespaces`
+- `forget`
+- `share`
+
+v0.1 intentionally ships MCP tools only over stdio. Resources, prompts, and HTTP transport are deferred.

package/examples/claude-desktop/claude_desktop_config.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "codebuddy": {
+      "command": "npx",
+      "args": ["codebuddy", "serve"],
+      "env": {
+        "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
+        "HF_TOKEN": "hf_replace_me",
+        "CODEBUDDY_NAMESPACE": "claude-desktop"
+      }
+    }
+  }
+}

package/examples/langgraph-agent/README.md

@@ -0,0 +1,32 @@
+# LangGraph Agent Example
+
+This example shows CodeBuddy inside a LangGraph flow with recall before the agent step and remember after the agent step.
+
+It demonstrates:
+
+- `CodeBuddyNode` in `recall` mode
+- `CodeBuddyNode` in `remember` mode
+- `CodeBuddyCheckpointer`
+- expected state fields: `messages`, `memory`, `sessionId`, `agentId`
+- `cacheTtlSeconds: 30`
+
+## Run
+
+```bash
+docker compose up -d
+export DATABASE_URL=postgres://codebuddy:codebuddy@localhost:5432/codebuddy
+export HF_TOKEN=hf_your_token
+npm install
+npm run build
+npm install @langchain/langgraph @langchain/core
+npx tsx examples/langgraph-agent/index.ts
+```
+
+The example imports from the public package surface:
+
+```ts
+import { createRuntime } from "codebuddy";
+import { CodeBuddyCheckpointer, CodeBuddyNode } from "codebuddy/langgraph";
+```
+
+If Hugging Face is cold or rate-limited, the embedding worker may need time to prepare vectors. Recall still falls back to recent context while embeddings are pending.

package/examples/langgraph-agent/index.ts

@@ -0,0 +1,71 @@
+import { type BaseMessage, HumanMessage } from "@langchain/core/messages";
+import { Annotation, StateGraph } from "@langchain/langgraph";
+import type { PlannedContext } from "codebuddy";
+import { createRuntime } from "codebuddy";
+import { CodeBuddyCheckpointer, CodeBuddyNode } from "codebuddy/langgraph";
+
+const postgresUrl = process.env.DATABASE_URL;
+if (!postgresUrl) {
+  throw new Error("DATABASE_URL is required.");
+}
+
+const runtime = await createRuntime({
+  postgresUrl,
+  provider: { type: "huggingface", apiKey: process.env.HF_TOKEN },
+  namespace: "langgraph-agent",
+  tokenBudget: 4000,
+});
+const { memory } = runtime;
+
+const State = Annotation.Root({
+  messages: Annotation<BaseMessage[]>({
+    reducer: (left, right) => left.concat(right),
+    default: () => [],
+  }),
+  memory: Annotation<PlannedContext | undefined>({
+    reducer: (_, right) => right,
+    default: () => undefined,
+  }),
+  sessionId: Annotation<string>({
+    reducer: (_, right) => right,
+  }),
+  agentId: Annotation<string | undefined>({
+    reducer: (_, right) => right,
+    default: () => undefined,
+  }),
+});
+
+async function agentNode(state: typeof State.State) {
+  const facts = state.memory?.messages.map((message) => message.content).join("\n") ?? "";
+  return {
+    messages: [
+      new HumanMessage(
+        facts
+          ? `Agent saw recalled memory:\n${facts}`
+          : "Agent had no recalled memory for this turn.",
+      ),
+    ],
+  };
+}
+
+const graph = new StateGraph(State)
+  .addNode("recall", new CodeBuddyNode({ memory, mode: "recall", cacheTtlSeconds: 30 }))
+  .addNode("agent", agentNode)
+  .addNode("remember", new CodeBuddyNode({ memory, mode: "remember" }))
+  .addEdge("__start__", "recall")
+  .addEdge("recall", "agent")
+  .addEdge("agent", "remember")
+  .addEdge("remember", "__end__")
+  .compile({ checkpointer: new CodeBuddyCheckpointer({ namespace: "langgraph-agent" }) });
+
+const result = await graph.invoke(
+  {
+    messages: [new HumanMessage("What do we know about deployment?")],
+    sessionId: "sess_langgraph_example",
+    agentId: "agent-langgraph",
+  },
+  { configurable: { thread_id: "thread_langgraph_example" } },
+);
+
+console.log(result.messages.at(-1)?.content);
+await runtime.close();

package/examples/multi-agent-handoff/README.md

@@ -0,0 +1,35 @@
+# Multi-Agent Handoff Example
+
+This example shows two namespaces sharing memory.
+
+Flow:
+
+1. `research-agent` writes a fact with `agentId` and `idempotencyKey`.
+2. `research-agent` shares that fact to `ops-agent` in `reference` mode.
+3. `ops-agent` recalls deployment context from its own namespace.
+4. `research-agent` also creates a `snapshot` share to show the second share mode.
+
+## Run
+
+```bash
+docker compose up -d
+export DATABASE_URL=postgres://codebuddy:codebuddy@localhost:5432/codebuddy
+export HF_TOKEN=hf_your_token
+npm run build
+npx tsx examples/multi-agent-handoff/index.ts
+```
+
+## Behaviors To Notice
+
+- namespaces isolate memory until a share is created
+- `reference` shares point to the live source fact
+- `snapshot` shares copy the fact for the target namespace
+- repeating the example returns `deduplicated: true` for the same `idempotencyKey`
+- `agentId` gives inspect and audit views a stable writer attribution
+
+Inspect after running:
+
+```bash
+node dist/cli/index.js inspect research-agent
+node dist/cli/index.js inspect ops-agent
+```

package/examples/multi-agent-handoff/index.ts

@@ -0,0 +1,68 @@
+import { createRuntime } from "codebuddy";
+
+const postgresUrl = process.env.DATABASE_URL;
+if (!postgresUrl) {
+  throw new Error("DATABASE_URL is required.");
+}
+
+const base = {
+  postgresUrl,
+  provider: { type: "huggingface" as const, apiKey: process.env.HF_TOKEN },
+  tokenBudget: 4000,
+};
+
+const research = await createRuntime({
+  ...base,
+  namespace: "research-agent",
+});
+
+const ops = await createRuntime({
+  ...base,
+  namespace: "ops-agent",
+});
+
+try {
+  const remembered = await research.memory.remember({
+    sessionId: "sess_handoff_example",
+    content: "The deployment target is eu-west-1 and requires layer-cached Docker builds.",
+    type: "fact",
+    idempotencyKey: "handoff:deployment-target:v1",
+    agentId: "agent-research",
+  });
+
+  console.log("remembered", remembered);
+
+  const referenceShare = await research.memory.share({
+    from: "research-agent",
+    to: "ops-agent",
+    factIds: [remembered.id],
+    mode: "reference",
+    agentId: "agent-research",
+  });
+
+  console.log("reference share", referenceShare);
+
+  const opsRecall = await ops.memory.recall({
+    sessionId: "sess_handoff_example",
+    query: "What deployment target should ops use?",
+    callerModel: "meta-llama/Llama-3.2-3B-Instruct",
+  });
+
+  console.log("ops recalled messages");
+  for (const message of opsRecall.messages) {
+    console.log("-", message.content);
+  }
+
+  const snapshotShare = await research.memory.share({
+    from: "research-agent",
+    to: "ops-agent",
+    factIds: [remembered.id],
+    mode: "snapshot",
+    agentId: "agent-research",
+  });
+
+  console.log("snapshot share", snapshotShare);
+} finally {
+  await research.close();
+  await ops.close();
+}