@agentmemory/agentmemory 0.7.0

package/src/mcp/transport.ts

@@ -0,0 +1,91 @@
+import { createInterface } from "node:readline";
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export type RequestHandler = (
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+export function createStdioTransport(handler: RequestHandler): {
+  start: () => void;
+  stop: () => void;
+} {
+  let rl: ReturnType<typeof createInterface> | null = null;
+
+  const onLine = async (line: string) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      const error: JsonRpcResponse = {
+        jsonrpc: "2.0",
+        id: null as unknown as number,
+        error: { code: -32700, message: "Parse error" },
+      };
+      process.stdout.write(JSON.stringify(error) + "\n");
+      return;
+    }
+
+    const request = parsed as JsonRpcRequest;
+    if (
+      !request ||
+      request.jsonrpc !== "2.0" ||
+      typeof request.method !== "string"
+    ) {
+      const error: JsonRpcResponse = {
+        jsonrpc: "2.0",
+        id: request?.id ?? (null as unknown as number),
+        error: { code: -32600, message: "Invalid Request" },
+      };
+      process.stdout.write(JSON.stringify(error) + "\n");
+      return;
+    }
+
+    try {
+      const result = await handler(request.method, request.params || {});
+      const response: JsonRpcResponse = {
+        jsonrpc: "2.0",
+        id: request.id,
+        result,
+      };
+      process.stdout.write(JSON.stringify(response) + "\n");
+    } catch (err) {
+      const response: JsonRpcResponse = {
+        jsonrpc: "2.0",
+        id: request.id,
+        error: {
+          code: -32603,
+          message: err instanceof Error ? err.message : String(err),
+        },
+      };
+      process.stdout.write(JSON.stringify(response) + "\n");
+    }
+  };
+
+  return {
+    start() {
+      rl = createInterface({ input: process.stdin });
+      rl.on("line", onLine);
+    },
+    stop() {
+      rl?.close();
+      rl = null;
+    },
+  };
+}

package/src/prompts/compression.ts

@@ -0,0 +1,67 @@
+export const COMPRESSION_SYSTEM = `You are a memory compression engine for an AI coding agent. Your job is to extract the essential information from a tool usage observation and compress it into structured data.
+
+Output EXACTLY this XML format with no additional text:
+
+<observation>
+  <type>one of: file_read, file_write, file_edit, command_run, search, web_fetch, conversation, error, decision, discovery, subagent, notification, task, other</type>
+  <title>Short descriptive title (max 80 chars)</title>
+  <subtitle>One-line context (optional)</subtitle>
+  <facts>
+    <fact>Specific factual detail 1</fact>
+    <fact>Specific factual detail 2</fact>
+  </facts>
+  <narrative>2-3 sentence summary of what happened and why it matters</narrative>
+  <concepts>
+    <concept>technical concept or pattern</concept>
+  </concepts>
+  <files>
+    <file>path/to/file</file>
+  </files>
+  <importance>1-10 scale, 10 being critical architectural decision</importance>
+</observation>
+
+Rules:
+- Be concise but preserve ALL technically relevant details
+- File paths must be exact
+- Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes
+- Concepts should be reusable search terms (e.g., "React hooks", "SQL migration", "auth middleware")
+- Strip any secrets, tokens, or credentials from the output`;
+
+export function buildCompressionPrompt(observation: {
+  hookType: string;
+  toolName?: string;
+  toolInput?: unknown;
+  toolOutput?: unknown;
+  userPrompt?: string;
+  timestamp: string;
+}): string {
+  const parts = [
+    `Timestamp: ${observation.timestamp}`,
+    `Hook: ${observation.hookType}`,
+  ];
+
+  if (observation.toolName) parts.push(`Tool: ${observation.toolName}`);
+  if (observation.toolInput) {
+    const input =
+      typeof observation.toolInput === "string"
+        ? observation.toolInput
+        : JSON.stringify(observation.toolInput, null, 2);
+    parts.push(`Input:\n${truncate(input, 4000)}`);
+  }
+  if (observation.toolOutput) {
+    const output =
+      typeof observation.toolOutput === "string"
+        ? observation.toolOutput
+        : JSON.stringify(observation.toolOutput, null, 2);
+    parts.push(`Output:\n${truncate(output, 4000)}`);
+  }
+  if (observation.userPrompt) {
+    parts.push(`User prompt:\n${truncate(observation.userPrompt, 2000)}`);
+  }
+
+  return parts.join("\n\n");
+}
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max) + "\n[...truncated]" : s;
+}

package/src/prompts/consolidation.ts

@@ -0,0 +1,48 @@
+export const SEMANTIC_MERGE_SYSTEM = `You are a memory consolidation engine. Given overlapping episodic memories (session summaries), extract stable factual knowledge.
+
+Output format (XML):
+<facts>
+  <fact confidence="0.0-1.0">Concise factual statement</fact>
+</facts>
+
+Rules:
+- Extract only facts that appear in 2+ episodes or are highly confident
+- Confidence reflects how well-supported the fact is across episodes
+- Combine overlapping information into single concise facts
+- Skip ephemeral details (specific error messages, temporary states)`;
+
+export function buildSemanticMergePrompt(
+  episodes: Array<{ title: string; narrative: string; concepts: string[] }>,
+): string {
+  const items = episodes
+    .map(
+      (e, i) =>
+        `[Episode ${i + 1}]\nTitle: ${e.title}\nNarrative: ${e.narrative}\nConcepts: ${e.concepts.join(", ")}`,
+    )
+    .join("\n\n");
+  return `Consolidate these episodic memories into stable facts:\n\n${items}`;
+}
+
+export const PROCEDURAL_EXTRACTION_SYSTEM = `You are a procedural memory extractor. Given repeated patterns and workflows observed across sessions, extract reusable procedures.
+
+Output format (XML):
+<procedures>
+  <procedure name="short descriptive name" trigger="when to use this procedure">
+    <step>Step 1 description</step>
+    <step>Step 2 description</step>
+  </procedure>
+</procedures>
+
+Rules:
+- Only extract procedures observed 2+ times
+- Steps should be concrete and actionable
+- Trigger condition should be specific enough to match automatically`;
+
+export function buildProceduralExtractionPrompt(
+  patterns: Array<{ content: string; frequency: number }>,
+): string {
+  const items = patterns
+    .map((p, i) => `[Pattern ${i + 1}] (seen ${p.frequency}x)\n${p.content}`)
+    .join("\n\n");
+  return `Extract reusable procedures from these recurring patterns:\n\n${items}`;
+}

package/src/prompts/graph-extraction.ts

@@ -0,0 +1,35 @@
+export const GRAPH_EXTRACTION_SYSTEM = `You are a knowledge graph extraction engine. Given a compressed observation from a coding session, extract entities and relationships.
+
+Output format (XML):
+<entities>
+  <entity type="file|function|concept|error|decision|pattern|library|person" name="exact name">
+    <property key="key">value</property>
+  </entity>
+</entities>
+<relationships>
+  <relationship type="uses|imports|modifies|causes|fixes|depends_on|related_to" source="entity name" target="entity name" weight="0.1-1.0"/>
+</relationships>
+
+Rules:
+- Extract concrete entities only (real file paths, function names, library names)
+- Use the most specific type available
+- Weight relationships by how strong/direct the connection is
+- If no entities found, output empty tags`;
+
+export function buildGraphExtractionPrompt(
+  observations: Array<{
+    title: string;
+    narrative: string;
+    concepts: string[];
+    files: string[];
+    type: string;
+  }>,
+): string {
+  const items = observations
+    .map(
+      (o, i) =>
+        `[${i + 1}] Type: ${o.type}\nTitle: ${o.title}\nNarrative: ${o.narrative}\nConcepts: ${(o.concepts ?? []).join(", ")}\nFiles: ${(o.files ?? []).join(", ")}`,
+    )
+    .join("\n\n");
+  return `Extract entities and relationships from these observations:\n\n${items}`;
+}

package/src/prompts/summary.ts

@@ -0,0 +1,38 @@
+export const SUMMARY_SYSTEM = `You are a session summarizer for an AI coding agent's memory system. Given all compressed observations from a coding session, produce a concise session summary.
+
+Output EXACTLY this XML format with no additional text:
+
+<summary>
+  <title>Short session title (max 100 chars)</title>
+  <narrative>3-5 sentence narrative of what was accomplished</narrative>
+  <decisions>
+    <decision>Key technical decision made</decision>
+  </decisions>
+  <files>
+    <file>path/to/modified/file</file>
+  </files>
+  <concepts>
+    <concept>key concept from session</concept>
+  </concepts>
+</summary>
+
+Rules:
+- Focus on outcomes, not individual tool calls
+- Highlight decisions and their rationale
+- List all files that were created or modified
+- Concepts should be searchable terms for future context retrieval`
+
+export function buildSummaryPrompt(observations: Array<{
+  type: string
+  title: string
+  facts: string[]
+  narrative: string
+  files: string[]
+  concepts: string[]
+}>): string {
+  const lines = observations.map((obs, i) => {
+    const facts = obs.facts.map((f) => `  - ${f}`).join('\n')
+    return `[${i + 1}] ${obs.type}: ${obs.title}\n${obs.narrative}\nFacts:\n${facts}\nFiles: ${obs.files.join(', ')}`
+  })
+  return `Session observations (${observations.length} total):\n\n${lines.join('\n\n---\n\n')}`
+}

package/src/prompts/xml.ts

@@ -0,0 +1,26 @@
+const VALID_TAG = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+export function getXmlTag(xml: string, tag: string): string {
+  if (!VALID_TAG.test(tag)) return "";
+  const match = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+  return match ? match[1].trim() : "";
+}
+
+export function getXmlChildren(
+  xml: string,
+  parentTag: string,
+  childTag: string,
+): string[] {
+  if (!VALID_TAG.test(parentTag) || !VALID_TAG.test(childTag)) return [];
+  const parentMatch = xml.match(
+    new RegExp(`<${parentTag}>([\\s\\S]*?)</${parentTag}>`),
+  );
+  if (!parentMatch) return [];
+  const items: string[] = [];
+  const re = new RegExp(`<${childTag}>([\\s\\S]*?)</${childTag}>`, "g");
+  let m;
+  while ((m = re.exec(parentMatch[1])) !== null) {
+    items.push(m[1].trim());
+  }
+  return items;
+}

package/src/providers/agent-sdk.ts

@@ -0,0 +1,34 @@
+import type { MemoryProvider } from '../types.js'
+
+export class AgentSDKProvider implements MemoryProvider {
+  name = 'agent-sdk'
+
+  async compress(systemPrompt: string, userPrompt: string): Promise<string> {
+    return this.query(systemPrompt, userPrompt)
+  }
+
+  async summarize(systemPrompt: string, userPrompt: string): Promise<string> {
+    return this.query(systemPrompt, userPrompt)
+  }
+
+  private async query(systemPrompt: string, userPrompt: string): Promise<string> {
+    const { query } = await import('@anthropic-ai/claude-agent-sdk')
+
+    const messages = query({
+      prompt: userPrompt,
+      options: {
+        systemPrompt,
+        maxTurns: 1,
+        allowedTools: [],
+      },
+    })
+
+    let result = ''
+    for await (const msg of messages) {
+      if (msg.type === 'result') {
+        result = typeof msg.result === 'string' ? msg.result : JSON.stringify(msg.result)
+      }
+    }
+    return result
+  }
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,35 @@
+import Anthropic from '@anthropic-ai/sdk'
+import type { MemoryProvider } from '../types.js'
+
+export class AnthropicProvider implements MemoryProvider {
+  name = 'anthropic'
+  private client: Anthropic
+  private model: string
+  private maxTokens: number
+
+  constructor(apiKey: string, model: string, maxTokens: number) {
+    this.client = new Anthropic({ apiKey })
+    this.model = model
+    this.maxTokens = maxTokens
+  }
+
+  async compress(systemPrompt: string, userPrompt: string): Promise<string> {
+    return this.call(systemPrompt, userPrompt)
+  }
+
+  async summarize(systemPrompt: string, userPrompt: string): Promise<string> {
+    return this.call(systemPrompt, userPrompt)
+  }
+
+  private async call(systemPrompt: string, userPrompt: string): Promise<string> {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: this.maxTokens,
+      system: systemPrompt,
+      messages: [{ role: 'user', content: userPrompt }],
+    })
+
+    const textBlock = response.content.find((b) => b.type === 'text')
+    return textBlock?.text ?? ''
+  }
+}

package/src/providers/circuit-breaker.ts

@@ -0,0 +1,82 @@
+import type { CircuitBreakerState } from "../types.js";
+
+interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  failureWindowMs?: number;
+  recoveryTimeoutMs?: number;
+}
+
+function positiveFinite(val: number | undefined, fallback: number): number {
+  return Number.isFinite(val) && val! > 0 ? val! : fallback;
+}
+
+export class CircuitBreaker {
+  private state: "closed" | "open" | "half-open" = "closed";
+  private failures = 0;
+  private lastFailureAt: number | null = null;
+  private openedAt: number | null = null;
+
+  private readonly failureThreshold: number;
+  private readonly failureWindowMs: number;
+  private readonly recoveryTimeoutMs: number;
+
+  constructor(opts?: CircuitBreakerOptions) {
+    this.failureThreshold = Math.max(
+      1,
+      Math.floor(positiveFinite(opts?.failureThreshold, 3)),
+    );
+    this.failureWindowMs = positiveFinite(opts?.failureWindowMs, 60_000);
+    this.recoveryTimeoutMs = positiveFinite(opts?.recoveryTimeoutMs, 30_000);
+  }
+
+  get isAllowed(): boolean {
+    if (this.state === "closed") return true;
+    if (this.state === "open") {
+      if (
+        this.openedAt &&
+        Date.now() - this.openedAt >= this.recoveryTimeoutMs
+      ) {
+        this.state = "half-open";
+        return true;
+      }
+      return false;
+    }
+    return true;
+  }
+
+  recordSuccess(): void {
+    if (this.state === "half-open") {
+      this.state = "closed";
+      this.failures = 0;
+      this.lastFailureAt = null;
+      this.openedAt = null;
+    }
+  }
+
+  recordFailure(): void {
+    const now = Date.now();
+    if (this.state === "half-open") {
+      this.state = "open";
+      this.openedAt = now;
+      return;
+    }
+    if (this.lastFailureAt && now - this.lastFailureAt > this.failureWindowMs) {
+      this.failures = 0;
+    }
+    this.failures += 1;
+    this.lastFailureAt = now;
+    if (this.failures >= this.failureThreshold) {
+      this.state = "open";
+      this.openedAt = now;
+    }
+  }
+
+  getState(): CircuitBreakerState {
+    return {
+      state: this.state,
+      failures: this.failures,
+      lastFailureAt: this.lastFailureAt,
+      openedAt: this.openedAt,
+    };
+  }
+}

package/src/providers/embedding/cohere.ts

@@ -0,0 +1,46 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const API_URL = "https://api.cohere.ai/v1/embed";
+
+export class CohereEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "cohere";
+  readonly dimensions = 1024;
+  private apiKey: string;
+
+  constructor(apiKey?: string) {
+    this.apiKey = apiKey || getEnvVar("COHERE_API_KEY") || "";
+    if (!this.apiKey) throw new Error("COHERE_API_KEY is required");
+  }
+
+  async embed(text: string): Promise<Float32Array> {
+    const [result] = await this.embedBatch([text]);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<Float32Array[]> {
+    const response = await fetch(API_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: "embed-english-v3.0",
+        texts,
+        input_type: "search_document",
+      }),
+    });
+
+    if (!response.ok) {
+      const err = await response.text();
+      throw new Error(`Cohere embedding failed (${response.status}): ${err}`);
+    }
+
+    const data = (await response.json()) as {
+      embeddings: number[][];
+    };
+
+    return data.embeddings.map((e) => new Float32Array(e));
+  }
+}

package/src/providers/embedding/gemini.ts

@@ -0,0 +1,54 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const BATCH_LIMIT = 100;
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContent";
+
+export class GeminiEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "gemini";
+  readonly dimensions = 768;
+  private apiKey: string;
+
+  constructor(apiKey?: string) {
+    this.apiKey = apiKey || getEnvVar("GEMINI_API_KEY") || "";
+    if (!this.apiKey) throw new Error("GEMINI_API_KEY is required");
+  }
+
+  async embed(text: string): Promise<Float32Array> {
+    const [result] = await this.embedBatch([text]);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<Float32Array[]> {
+    const results: Float32Array[] = [];
+
+    for (let i = 0; i < texts.length; i += BATCH_LIMIT) {
+      const chunk = texts.slice(i, i + BATCH_LIMIT);
+      const response = await fetch(`${API_BASE}?key=${this.apiKey}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          requests: chunk.map((t) => ({
+            model: "models/text-embedding-004",
+            content: { parts: [{ text: t }] },
+          })),
+        }),
+      });
+
+      if (!response.ok) {
+        const err = await response.text();
+        throw new Error(`Gemini embedding failed (${response.status}): ${err}`);
+      }
+
+      const data = (await response.json()) as {
+        embeddings: Array<{ values: number[] }>;
+      };
+
+      for (const emb of data.embeddings) {
+        results.push(new Float32Array(emb.values));
+      }
+    }
+
+    return results;
+  }
+}

package/src/providers/embedding/index.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { detectEmbeddingProvider, getEnvVar } from "../../config.js";
+import { GeminiEmbeddingProvider } from "./gemini.js";
+import { OpenAIEmbeddingProvider } from "./openai.js";
+import { VoyageEmbeddingProvider } from "./voyage.js";
+import { CohereEmbeddingProvider } from "./cohere.js";
+import { OpenRouterEmbeddingProvider } from "./openrouter.js";
+import { LocalEmbeddingProvider } from "./local.js";
+
+export {
+  GeminiEmbeddingProvider,
+  OpenAIEmbeddingProvider,
+  VoyageEmbeddingProvider,
+  CohereEmbeddingProvider,
+  OpenRouterEmbeddingProvider,
+  LocalEmbeddingProvider,
+};
+
+export function createEmbeddingProvider(): EmbeddingProvider | null {
+  const detected = detectEmbeddingProvider();
+  if (!detected) return null;
+
+  switch (detected) {
+    case "gemini":
+      return new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!);
+    case "openai":
+      return new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!);
+    case "voyage":
+      return new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!);
+    case "cohere":
+      return new CohereEmbeddingProvider(getEnvVar("COHERE_API_KEY")!);
+    case "openrouter":
+      return new OpenRouterEmbeddingProvider(getEnvVar("OPENROUTER_API_KEY")!);
+    case "local":
+      return new LocalEmbeddingProvider();
+    default:
+      return null;
+  }
+}

package/src/providers/embedding/local.ts

@@ -0,0 +1,52 @@
+import type { EmbeddingProvider } from "../../types.js";
+
+type Pipeline = (
+  task: string,
+  model: string,
+) => Promise<
+  (
+    texts: string[],
+    options: { pooling: string; normalize: boolean },
+  ) => Promise<{ tolist: () => number[][] }>
+>;
+
+export class LocalEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "local";
+  readonly dimensions = 384;
+  private extractor: Awaited<ReturnType<Pipeline>> | null = null;
+
+  async embed(text: string): Promise<Float32Array> {
+    const [result] = await this.embedBatch([text]);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<Float32Array[]> {
+    const extractor = await this.getExtractor();
+    const output = await extractor(texts, {
+      pooling: "mean",
+      normalize: true,
+    });
+    const vectors = output.tolist();
+    return vectors.map((v: number[]) => new Float32Array(v));
+  }
+
+  private async getExtractor() {
+    if (this.extractor) return this.extractor;
+
+    let transformers: { pipeline: Pipeline };
+    try {
+      // @ts-ignore - optional peer dependency
+      transformers = await import("@xenova/transformers");
+    } catch {
+      throw new Error(
+        "Install @xenova/transformers for local embeddings: npm install @xenova/transformers",
+      );
+    }
+
+    this.extractor = await transformers.pipeline(
+      "feature-extraction",
+      "Xenova/all-MiniLM-L6-v2",
+    );
+    return this.extractor;
+  }
+}