@tjamescouch/gro 1.3.2

package/src/mcp/client.ts

@@ -0,0 +1,147 @@
+/**
+ * MCP client — connects to MCP servers, discovers tools, routes tool calls.
+ * Compatible with Claude Code's ~/.claude/settings.json mcpServers config.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Logger } from "../logger.js";
+import { groError, asError, errorLogFields } from "../errors.js";
+
+export interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema: any;
+  /** Which MCP server provides this tool. */
+  serverName: string;
+}
+
+interface ConnectedServer {
+  name: string;
+  client: Client;
+  transport: StdioClientTransport;
+  tools: McpTool[];
+}
+
+export class McpManager {
+  private servers = new Map<string, ConnectedServer>();
+
+  /**
+   * Connect to all configured MCP servers and discover their tools.
+   */
+  async connectAll(configs: Record<string, McpServerConfig>): Promise<void> {
+    const entries = Object.entries(configs);
+    if (entries.length === 0) return;
+
+    Logger.debug(`Connecting to ${entries.length} MCP server(s)...`);
+
+    await Promise.all(
+      entries.map(([name, cfg]) => this.connectOne(name, cfg).catch((e: unknown) => {
+        const ge = groError("mcp_error", `MCP server "${name}" failed to connect: ${asError(e).message}`, {
+          retryable: true,
+          cause: e,
+        });
+        Logger.warn(ge.message, errorLogFields(ge));
+      }))
+    );
+  }
+
+  private async connectOne(name: string, cfg: McpServerConfig): Promise<void> {
+    const transport = new StdioClientTransport({
+      command: cfg.command,
+      args: cfg.args ?? [],
+      env: { ...process.env, ...cfg.env } as Record<string, string>,
+      cwd: cfg.cwd,
+      stderr: "pipe",
+    });
+
+    const client = new Client(
+      { name: "gro", version: "0.2.0" },
+      { capabilities: {} }
+    );
+
+    await client.connect(transport);
+
+    // Discover tools
+    const toolsResult = await client.listTools();
+    const tools: McpTool[] = (toolsResult.tools ?? []).map((t: any) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      serverName: name,
+    }));
+
+    this.servers.set(name, { name, client, transport, tools });
+    Logger.debug(`MCP "${name}": ${tools.length} tool(s) available`);
+  }
+
+  /**
+   * Get all discovered tools in OpenAI function-calling format.
+   */
+  getToolDefinitions(): any[] {
+    const defs: any[] = [];
+    for (const server of this.servers.values()) {
+      for (const tool of server.tools) {
+        defs.push({
+          type: "function",
+          function: {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: tool.inputSchema ?? { type: "object", properties: {} },
+          },
+        });
+      }
+    }
+    return defs;
+  }
+
+  /**
+   * Execute a tool call by routing it to the correct MCP server.
+   */
+  async callTool(name: string, args: Record<string, any>): Promise<string> {
+    // Find which server provides this tool
+    for (const server of this.servers.values()) {
+      const tool = server.tools.find(t => t.name === name);
+      if (tool) {
+        const result = await server.client.callTool({ name, arguments: args }, undefined, { timeout: 5 * 60 * 1000 });
+        // Extract text content from result
+        if (Array.isArray(result.content)) {
+          return result.content
+            .map((c: any) => {
+              if (c.type === "text") return c.text;
+              return JSON.stringify(c);
+            })
+            .join("\n");
+        }
+        return JSON.stringify(result);
+      }
+    }
+    throw new Error(`No MCP server provides tool "${name}"`);
+  }
+
+  /**
+   * Check if a tool name is provided by any connected MCP server.
+   */
+  hasTool(name: string): boolean {
+    for (const server of this.servers.values()) {
+      if (server.tools.some(t => t.name === name)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Disconnect all MCP servers.
+   */
+  async disconnectAll(): Promise<void> {
+    for (const server of this.servers.values()) {
+      try { await server.client.close(); } catch {}
+    }
+    this.servers.clear();
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+export { McpManager } from "./client.js";
+export type { McpServerConfig, McpTool } from "./client.js";

package/src/memory/advanced-memory.ts

@@ -0,0 +1,263 @@
+import type { ChatDriver, ChatMessage } from "../drivers/types.js";
+import { AgentMemory } from "./agent-memory.js";
+import { saveSession, loadSession, ensureGroDir } from "../session.js";
+
+/**
+ * AdvancedMemory — swim-lane summarization with token budgeting.
+ *
+ * Maintains three lanes (assistant / system / user) and summarizes independently.
+ * Uses character-based token estimation with high/low watermark hysteresis.
+ * Background summarization never blocks the caller.
+ */
+export class AdvancedMemory extends AgentMemory {
+  private readonly driver: ChatDriver;
+  private readonly model: string;
+  private readonly summarizerDriver: ChatDriver;
+  private readonly summarizerModel: string;
+
+  private readonly contextTokens: number;
+  private readonly reserveHeaderTokens: number;
+  private readonly reserveResponseTokens: number;
+  private readonly highRatio: number;
+  private readonly lowRatio: number;
+  private readonly summaryRatio: number;
+  private readonly avgCharsPerToken: number;
+  private readonly keepRecentPerLane: number;
+  private readonly keepRecentTools: number;
+
+  constructor(args: {
+    driver: ChatDriver;
+    model: string;
+    summarizerDriver?: ChatDriver;
+    summarizerModel?: string;
+    systemPrompt?: string;
+    contextTokens?: number;
+    reserveHeaderTokens?: number;
+    reserveResponseTokens?: number;
+    highRatio?: number;
+    lowRatio?: number;
+    summaryRatio?: number;
+    avgCharsPerToken?: number;
+    keepRecentPerLane?: number;
+    keepRecentTools?: number;
+  }) {
+    super(args.systemPrompt);
+    this.driver = args.driver;
+    this.model = args.model;
+    this.summarizerDriver = args.summarizerDriver ?? args.driver;
+    this.summarizerModel = args.summarizerModel ?? args.model;
+
+    this.contextTokens = Math.max(2048, Math.floor(args.contextTokens ?? 8192));
+    this.reserveHeaderTokens = Math.max(0, Math.floor(args.reserveHeaderTokens ?? 1200));
+    this.reserveResponseTokens = Math.max(0, Math.floor(args.reserveResponseTokens ?? 800));
+    this.highRatio = Math.min(0.95, Math.max(0.55, args.highRatio ?? 0.70));
+    this.lowRatio = Math.min(this.highRatio - 0.05, Math.max(0.35, args.lowRatio ?? 0.50));
+    this.summaryRatio = Math.min(0.50, Math.max(0.15, args.summaryRatio ?? 0.35));
+    this.avgCharsPerToken = Math.max(1.5, Number(args.avgCharsPerToken ?? 4));
+    this.keepRecentPerLane = Math.max(1, Math.floor(args.keepRecentPerLane ?? 4));
+    this.keepRecentTools = Math.max(0, Math.floor(args.keepRecentTools ?? 3));
+  }
+
+  async load(id: string): Promise<void> {
+    const session = loadSession(id);
+    if (session) {
+      this.messagesBuffer = session.messages;
+    }
+  }
+
+  async save(id: string): Promise<void> {
+    ensureGroDir();
+    saveSession(id, this.messagesBuffer, {
+      id,
+      provider: "unknown",
+      model: this.model,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  protected async onAfterAdd(): Promise<void> {
+    const budget = this.budgetTokens();
+    const estTok = this.estimateTokens(this.messagesBuffer);
+    if (estTok <= Math.floor(this.highRatio * budget)) return;
+
+    await this.runOnce(async () => {
+      const budget2 = this.budgetTokens();
+      const estTok2 = this.estimateTokens(this.messagesBuffer);
+      if (estTok2 <= Math.floor(this.highRatio * budget2)) return;
+
+      const { firstSystemIndex, assistant, user, system, tool, other } = this.partition();
+      const tailN = this.keepRecentPerLane;
+
+      const olderAssistant = assistant.slice(0, Math.max(0, assistant.length - tailN));
+      const keepAssistant = assistant.slice(Math.max(0, assistant.length - tailN));
+
+      const sysHead = firstSystemIndex === 0 ? [this.messagesBuffer[0]] : [];
+      const remainingSystem = firstSystemIndex === 0 ? system.slice(1) : system.slice(0);
+      const olderSystem = remainingSystem.slice(0, Math.max(0, remainingSystem.length - tailN));
+      const keepSystem = remainingSystem.slice(Math.max(0, remainingSystem.length - tailN));
+
+      const olderUser = user.slice(0, Math.max(0, user.length - tailN));
+      const keepUser = user.slice(Math.max(0, user.length - tailN));
+
+      const keepTools = tool.slice(Math.max(0, tool.length - this.keepRecentTools));
+
+      const preserved: ChatMessage[] = [
+        ...sysHead, ...keepAssistant, ...keepSystem, ...keepUser, ...keepTools, ...other,
+      ];
+      const preservedTok = this.estimateTokens(preserved);
+      const lowTarget = Math.floor(this.lowRatio * budget2);
+      const maxSummaryTok = Math.floor(this.summaryRatio * budget2);
+
+      if (preservedTok <= lowTarget) {
+        const rebuilt = this.ordered([], sysHead, keepAssistant, keepSystem, keepUser, keepTools, other);
+        this.messagesBuffer.splice(0, this.messagesBuffer.length, ...rebuilt);
+        return;
+      }
+
+      const removedCharA = this.totalChars(olderAssistant);
+      const removedCharS = this.totalChars(olderSystem);
+      const removedCharU = this.totalChars(olderUser);
+      const removedTotal = Math.max(1, removedCharA + removedCharS + removedCharU);
+
+      const totalSummaryBudget = Math.max(64, Math.min(maxSummaryTok, lowTarget - preservedTok));
+      const budgetA = Math.max(48, Math.floor(totalSummaryBudget * (removedCharA / removedTotal)));
+      const budgetS = Math.max(48, Math.floor(totalSummaryBudget * (removedCharS / removedTotal)));
+      const budgetU = Math.max(48, Math.floor(totalSummaryBudget * (removedCharU / removedTotal)));
+
+      const [sumA, sumS, sumU] = await Promise.all([
+        olderAssistant.length ? this.summarizeLane("assistant", olderAssistant, budgetA) : "",
+        olderSystem.length ? this.summarizeLane("system", olderSystem, budgetS) : "",
+        olderUser.length ? this.summarizeLane("user", olderUser, budgetU) : "",
+      ]);
+
+      const summaries: ChatMessage[] = [];
+      if (sumA) summaries.push({ from: "Me", role: "assistant", content: `ASSISTANT SUMMARY:\n${sumA}` });
+      if (sumS) summaries.push({ from: "System", role: "system", content: `SYSTEM SUMMARY:\n${sumS}` });
+      if (sumU) summaries.push({ from: "Memory", role: "user", content: `USER SUMMARY:\n${sumU}` });
+
+      const rebuilt = this.ordered(summaries, sysHead, keepAssistant, keepSystem, keepUser, keepTools, other);
+      this.messagesBuffer.splice(0, this.messagesBuffer.length, ...rebuilt);
+
+      // Final clamp
+      let finalTok = this.estimateTokens(this.messagesBuffer);
+      if (finalTok > lowTarget) {
+        const pruned: ChatMessage[] = [];
+        for (const m of this.messagesBuffer) {
+          pruned.push(m);
+          finalTok = this.estimateTokens(pruned);
+          if (finalTok > lowTarget && m.role !== "system") {
+            pruned.pop();
+          }
+        }
+        this.messagesBuffer.splice(0, this.messagesBuffer.length, ...pruned);
+      }
+    });
+  }
+
+  private budgetTokens(): number {
+    return Math.max(512, this.contextTokens - this.reserveHeaderTokens - this.reserveResponseTokens);
+  }
+
+  private estimateTokens(msgs: ChatMessage[]): number {
+    return Math.ceil(this.totalChars(msgs) / this.avgCharsPerToken);
+  }
+
+  private totalChars(msgs: ChatMessage[]): number {
+    let c = 0;
+    for (const m of msgs) {
+      const s = String((m as any).content ?? "");
+      if (m.role === "tool" && s.length > 24_000) c += 24_000;
+      else c += s.length;
+      c += 32;
+    }
+    return c;
+  }
+
+  private partition() {
+    const assistant: ChatMessage[] = [];
+    const user: ChatMessage[] = [];
+    const system: ChatMessage[] = [];
+    const tool: ChatMessage[] = [];
+    const other: ChatMessage[] = [];
+
+    for (const m of this.messagesBuffer) {
+      switch (m.role) {
+        case "assistant": assistant.push(m); break;
+        case "user": user.push(m); break;
+        case "system": system.push(m); break;
+        case "tool": tool.push(m); break;
+        default: other.push(m); break;
+      }
+    }
+    const firstSystemIndex = this.messagesBuffer.findIndex(x => x.role === "system");
+    return { firstSystemIndex, assistant, user, system, tool, other };
+  }
+
+  private ordered(
+    summaries: ChatMessage[],
+    sysHead: ChatMessage[],
+    keepA: ChatMessage[],
+    keepS: ChatMessage[],
+    keepU: ChatMessage[],
+    keepT: ChatMessage[],
+    other: ChatMessage[],
+  ): ChatMessage[] {
+    const keepSet = new Set([...sysHead, ...keepA, ...keepS, ...keepU, ...keepT, ...other]);
+    const rest: ChatMessage[] = [];
+    for (const m of this.messagesBuffer) {
+      if (keepSet.has(m)) rest.push(m);
+    }
+    const orderedSummaries = [
+      ...summaries.filter(s => s.role === "assistant"),
+      ...summaries.filter(s => s.role === "system"),
+      ...summaries.filter(s => s.role === "user"),
+    ];
+    return [...orderedSummaries, ...rest];
+  }
+
+  private async summarizeLane(
+    laneName: "assistant" | "system" | "user",
+    messages: ChatMessage[],
+    tokenBudget: number,
+  ): Promise<string> {
+    if (messages.length === 0 || tokenBudget <= 0) return "";
+    const approxChars = Math.max(120, Math.floor(tokenBudget * this.avgCharsPerToken));
+
+    const header = (() => {
+      switch (laneName) {
+        case "assistant": return "Summarize prior ASSISTANT replies (decisions, plans, code edits, shell commands and outcomes).";
+        case "system": return "Summarize SYSTEM instructions (rules, goals, constraints) without changing their intent.";
+        case "user": return "Summarize USER requests, feedback, constraints, and acceptance criteria.";
+      }
+    })();
+
+    let acc = "";
+    for (const m of messages) {
+      let c = String((m as any).content ?? "");
+      if (c.length > 4000) c = c.slice(0, 4000) + "\n…(truncated)…";
+      const next = `- ${laneName.toUpperCase()}: ${c}\n\n`;
+      if (acc.length + next.length > approxChars * 3) break;
+      acc += next;
+    }
+
+    const sys: ChatMessage = {
+      role: "system",
+      from: "System",
+      content: [
+        "You are a precise summarizer.",
+        "Output concise bullet points; preserve facts, tasks, file paths, commands, constraints.",
+        `Hard limit: ~${approxChars} characters total.`,
+        "Avoid fluff; keep actionable details.",
+      ].join(" "),
+    };
+
+    const usr: ChatMessage = {
+      role: "user",
+      from: "User",
+      content: `${header}\n\nTranscript:\n${acc}`,
+    };
+
+    const out = await this.summarizerDriver.chat([sys, usr], { model: this.summarizerModel });
+    return String((out as any)?.text ?? "").trim();
+  }
+}

package/src/memory/agent-memory.ts

@@ -0,0 +1,61 @@
+import type { ChatMessage } from "../drivers/types.js";
+
+/**
+ * Base class for agent memory with background summarization support.
+ * Subclasses call `runOnce` to serialize/queue summarization so callers never block.
+ */
+export abstract class AgentMemory {
+  protected messagesBuffer: ChatMessage[] = [];
+
+  private summarizing = false;
+  private pending = false;
+
+  constructor(systemPrompt?: string) {
+    if (systemPrompt && systemPrompt.trim().length > 0) {
+      this.messagesBuffer.push({ role: "system", content: systemPrompt, from: "System" });
+    }
+  }
+
+  abstract load(id: string): Promise<void>;
+  abstract save(id: string): Promise<void>;
+
+  async add(msg: ChatMessage): Promise<void> {
+    this.messagesBuffer.push(msg);
+    await this.onAfterAdd();
+  }
+
+  async addIfNotExists(msg: ChatMessage): Promise<void> {
+    const exists = this.messagesBuffer.some(m => m.content === msg.content && m.role === msg.role);
+    if (!exists) {
+      this.messagesBuffer.push(msg);
+      await this.onAfterAdd();
+    }
+  }
+
+  protected abstract onAfterAdd(): Promise<void>;
+
+  messages(): ChatMessage[] {
+    return [...this.messagesBuffer];
+  }
+
+  protected nonSystemCount(): number {
+    if (this.messagesBuffer.length === 0) return 0;
+    return this.messagesBuffer[0].role === "system"
+      ? this.messagesBuffer.length - 1
+      : this.messagesBuffer.length;
+  }
+
+  protected async runOnce(task: () => Promise<void>): Promise<void> {
+    if (this.summarizing) { this.pending = true; return; }
+    this.summarizing = true;
+    try {
+      await task();
+    } finally {
+      this.summarizing = false;
+      if (this.pending) {
+        this.pending = false;
+        void this.runOnce(task);
+      }
+    }
+  }
+}

package/src/memory/agenthnsw.ts

@@ -0,0 +1,122 @@
+/**
+ * agenthnsw adapter — optional dynamic import.
+ *
+ * The "agenthnsw" package is an optional dependency.  We load it at
+ * runtime via a dynamic `import()` so that TypeScript compilation and
+ * Docker builds succeed even when the package is not installed.
+ *
+ * If agenthnsw is missing at runtime the factory function
+ * `createAgentHnswIndex()` will throw a clear error.
+ */
+
+import type { VectorIndex, VectorRecord, VectorSearchResult, Vector } from "./vector-index.js";
+
+// ── Dynamic loader ──────────────────────────────────────────────────────────
+
+interface InMemoryLinearIndexLike {
+  upsert(record: { id: string; vector: Vector; metadata?: unknown }): Promise<void>;
+  upsertMany(records: { id: string; vector: Vector; metadata?: unknown }[]): Promise<void>;
+  search(query: Vector, k: number): Promise<{ id: string; score: number; metadata?: unknown }[]>;
+  delete(id: string): Promise<void>;
+  save(dir: string): Promise<void>;
+  load(dir: string): Promise<void>;
+  stats(): Promise<{ count: number; dims?: number }>;
+}
+
+interface AgentHnswModule {
+  InMemoryLinearIndex: new (opts?: { metric?: "cosine" | "l2" }) => InMemoryLinearIndexLike;
+}
+
+/**
+ * Dynamically import "agenthnsw".
+ *
+ * We use `eval("(m) => import(m)")` to prevent the TypeScript compiler
+ * and bundlers from resolving the specifier at compile time.
+ */
+async function importAgentHnsw(): Promise<AgentHnswModule> {
+  try {
+    const dynImport: (m: string) => Promise<AgentHnswModule> = eval("(m) => import(m)");
+    return await dynImport("agenthnsw");
+  } catch (err: unknown) {
+    throw new Error(
+      `Optional dependency "agenthnsw" is not installed. ` +
+      `Install it with:  npm install agenthnsw\n` +
+      `Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+// ── AgentHnswIndex class ────────────────────────────────────────────────────
+
+export class AgentHnswIndex implements VectorIndex {
+  private idx: InMemoryLinearIndexLike | null = null;
+  private readonly metric: "cosine" | "l2" | undefined;
+
+  constructor(opts?: { metric?: "cosine" | "l2" }) {
+    this.metric = opts?.metric;
+  }
+
+  /** Lazily initialise the underlying index on first use. */
+  private async ensureIndex(): Promise<InMemoryLinearIndexLike> {
+    if (!this.idx) {
+      const mod = await importAgentHnsw();
+      this.idx = new mod.InMemoryLinearIndex({ metric: this.metric });
+    }
+    return this.idx;
+  }
+
+  async upsert(record: VectorRecord): Promise<void> {
+    const idx = await this.ensureIndex();
+    await idx.upsert({ id: record.id, vector: record.vector, metadata: record.metadata });
+  }
+
+  async upsertMany(records: VectorRecord[]): Promise<void> {
+    const idx = await this.ensureIndex();
+    await idx.upsertMany(
+      records.map((r: VectorRecord) => ({ id: r.id, vector: r.vector, metadata: r.metadata }))
+    );
+  }
+
+  async search(query: Vector, k: number): Promise<VectorSearchResult[]> {
+    const idx = await this.ensureIndex();
+    const res = await idx.search(query, k);
+    return res.map((r: { id: string; score: number; metadata?: unknown }) => ({
+      id: r.id,
+      score: r.score,
+      metadata: r.metadata,
+    }));
+  }
+
+  async delete(id: string): Promise<void> {
+    const idx = await this.ensureIndex();
+    await idx.delete(id);
+  }
+
+  async save(dir: string): Promise<void> {
+    const idx = await this.ensureIndex();
+    await idx.save(dir);
+  }
+
+  async load(dir: string): Promise<void> {
+    const idx = await this.ensureIndex();
+    await idx.load(dir);
+  }
+
+  async stats(): Promise<{ count: number; dims?: number }> {
+    const idx = await this.ensureIndex();
+    return await idx.stats();
+  }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create an AgentHnswIndex.
+ *
+ * The underlying "agenthnsw" package is loaded lazily — this function
+ * itself never throws even when the package is absent.  The first call
+ * to any index method will attempt the dynamic import.
+ */
+export function createAgentHnswIndex(opts?: { metric?: "cosine" | "l2" }): AgentHnswIndex {
+  return new AgentHnswIndex(opts);
+}

package/src/memory/index.ts

@@ -0,0 +1,6 @@
+export * from "./vector-index.js";
+export * from "./agenthnsw.js";
+
+export { AgentMemory } from "./agent-memory.js";
+export { AdvancedMemory } from "./advanced-memory.js";
+export { SimpleMemory } from "./simple-memory.js";

package/src/memory/simple-memory.ts

@@ -0,0 +1,41 @@
+import type { ChatMessage } from "../drivers/types.js";
+import { AgentMemory } from "./agent-memory.js";
+import { saveSession, loadSession, ensureGroDir } from "../session.js";
+
+/**
+ * SimpleMemory — unbounded message buffer.
+ * No summarization, no token budgeting. Useful for short conversations
+ * or when the caller manages context externally.
+ */
+export class SimpleMemory extends AgentMemory {
+  private provider = "";
+  private model = "";
+
+  constructor(systemPrompt?: string) {
+    super(systemPrompt);
+  }
+
+  setMeta(provider: string, model: string): void {
+    this.provider = provider;
+    this.model = model;
+  }
+
+  async load(id: string): Promise<void> {
+    const session = loadSession(id);
+    if (session) {
+      this.messagesBuffer = session.messages;
+    }
+  }
+
+  async save(id: string): Promise<void> {
+    ensureGroDir();
+    saveSession(id, this.messagesBuffer, {
+      id,
+      provider: this.provider,
+      model: this.model,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  protected async onAfterAdd(): Promise<void> {}
+}

package/src/memory/vector-index.ts

@@ -0,0 +1,30 @@
+/**
+ * Pluggable vector index interface for retrieval-backed memory.
+ *
+ * This is intentionally small so backends can live in separate packages
+ * (e.g. agenthnsw) and be imported by gro.
+ */
+
+export type Vector = Float32Array | number[];
+
+export interface VectorRecord {
+  id: string;
+  vector: Vector;
+  metadata?: unknown;
+}
+
+export interface VectorSearchResult {
+  id: string;
+  score: number;
+  metadata?: unknown;
+}
+
+export interface VectorIndex {
+  upsert(record: VectorRecord): Promise<void>;
+  upsertMany(records: VectorRecord[]): Promise<void>;
+  search(query: Vector, k: number): Promise<VectorSearchResult[]>;
+  delete(id: string): Promise<void>;
+  save(dir: string): Promise<void>;
+  load(dir: string): Promise<void>;
+  stats(): Promise<{ count: number; dims?: number }>;
+}