@agentmemory/agentmemory 0.7.0

package/src/cli.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+agentmemory — persistent memory for AI coding agents
+
+Usage: agentmemory [options]
+
+Options:
+  --help, -h         Show this help
+  --tools all|core   Tool visibility (default: core = 7 tools)
+  --no-engine        Skip auto-starting iii-engine
+  --port <N>         Override REST port (default: 3111)
+
+Environment:
+  AGENTMEMORY_TOOLS=all    Expose all 41 MCP tools
+  AGENTMEMORY_SECRET=xxx   Auth secret for REST/MCP
+  CONSOLIDATION_ENABLED=true   Enable auto-consolidation (off by default)
+  OBSIDIAN_AUTO_EXPORT=true    Auto-export on consolidation
+
+Quick start:
+  npx agentmemory             # auto-starts iii-engine, runs worker
+  npx agentmemory-mcp         # standalone MCP server (no engine needed)
+`);
+  process.exit(0);
+}
+
+const toolsIdx = args.indexOf("--tools");
+if (toolsIdx !== -1 && args[toolsIdx + 1]) {
+  process.env["AGENTMEMORY_TOOLS"] = args[toolsIdx + 1];
+}
+
+const portIdx = args.indexOf("--port");
+if (portIdx !== -1 && args[portIdx + 1]) {
+  process.env["III_REST_PORT"] = args[portIdx + 1];
+}
+
+const skipEngine = args.includes("--no-engine");
+
+function getRestPort(): number {
+  return parseInt(process.env["III_REST_PORT"] || "3111", 10) || 3111;
+}
+
+async function isEngineRunning(): Promise<boolean> {
+  try {
+    const res = await fetch(`http://localhost:${getRestPort()}/agentmemory/livez`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function findIiiConfig(): string {
+  const candidates = [
+    join(__dirname, "iii-config.yaml"),
+    join(__dirname, "..", "iii-config.yaml"),
+    join(process.cwd(), "iii-config.yaml"),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return "";
+}
+
+function whichBinary(name: string): string | null {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  try {
+    return execFileSync(cmd, [name], { encoding: "utf-8" }).trim().split("\n")[0];
+  } catch {
+    return null;
+  }
+}
+
+async function startEngine(): Promise<boolean> {
+  const configPath = findIiiConfig();
+
+  const iiiBin = whichBinary("iii");
+  if (iiiBin && configPath) {
+    console.log(`[agentmemory] Starting iii-engine: ${iiiBin} --config ${configPath}`);
+    const child = spawn(iiiBin, ["--config", configPath], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return true;
+  }
+
+  const dockerCompose = join(__dirname, "..", "docker-compose.yml");
+  const dcExists = existsSync(dockerCompose) || existsSync(join(process.cwd(), "docker-compose.yml"));
+  const dockerBin = whichBinary("docker");
+
+  if (dockerBin && dcExists) {
+    const composeFile = existsSync(dockerCompose) ? dockerCompose : join(process.cwd(), "docker-compose.yml");
+    console.log(`[agentmemory] Starting iii-engine via Docker...`);
+    const child = spawn(dockerBin, ["compose", "-f", composeFile, "up", "-d"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return true;
+  }
+
+  return false;
+}
+
+async function waitForEngine(timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isEngineRunning()) return true;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+async function main() {
+  if (!skipEngine && !(await isEngineRunning())) {
+    const started = await startEngine();
+    if (!started) {
+      console.error(`
+[agentmemory] iii-engine is not running and could not be auto-started.
+
+Install one of:
+  1. iii CLI:    npm install -g iii-engine
+  2. Docker:     docker compose up -d (with docker-compose.yml)
+
+Or run with --no-engine to connect to a remote engine.
+`);
+      process.exit(1);
+    }
+
+    console.log(`[agentmemory] Waiting for iii-engine to start...`);
+    const ready = await waitForEngine(15000);
+    if (!ready) {
+      const port = getRestPort();
+      console.error(`[agentmemory] iii-engine did not become ready within 15s.`);
+      console.error(`[agentmemory] Check that ports ${port}, ${port + 1}, 49134 are available.`);
+      process.exit(1);
+    }
+    console.log(`[agentmemory] iii-engine is ready.`);
+  }
+
+  await import("./index.js");
+}
+
+main().catch((err) => {
+  console.error(`[agentmemory] Fatal:`, err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,221 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type {
+  AgentMemoryConfig,
+  ProviderConfig,
+  EmbeddingConfig,
+  FallbackConfig,
+  ClaudeBridgeConfig,
+  TeamConfig,
+} from "./types.js";
+
+function safeParseInt(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const parsed = parseInt(value, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+const DATA_DIR = join(homedir(), ".agentmemory");
+const ENV_FILE = join(DATA_DIR, ".env");
+
+function loadEnvFile(): Record<string, string> {
+  if (!existsSync(ENV_FILE)) return {};
+  const content = readFileSync(ENV_FILE, "utf-8");
+  const vars: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let val = trimmed.slice(eqIdx + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    vars[key] = val;
+  }
+  return vars;
+}
+
+function detectProvider(env: Record<string, string>): ProviderConfig {
+  const maxTokens = parseInt(env["MAX_TOKENS"] || "4096", 10);
+
+  if (env["ANTHROPIC_API_KEY"]) {
+    return {
+      provider: "anthropic",
+      model: env["ANTHROPIC_MODEL"] || "claude-sonnet-4-20250514",
+      maxTokens,
+    };
+  }
+  if (env["GEMINI_API_KEY"]) {
+    return {
+      provider: "gemini",
+      model: env["GEMINI_MODEL"] || "gemini-2.0-flash",
+      maxTokens,
+    };
+  }
+  if (env["OPENROUTER_API_KEY"]) {
+    return {
+      provider: "openrouter",
+      model: env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-4-20250514",
+      maxTokens,
+    };
+  }
+  return {
+    provider: "agent-sdk",
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 4096,
+  };
+}
+
+export function loadConfig(): AgentMemoryConfig {
+  const env = getMergedEnv();
+
+  const provider = detectProvider(env);
+
+  return {
+    engineUrl: env["III_ENGINE_URL"] || "ws://localhost:49134",
+    restPort: parseInt(env["III_REST_PORT"] || "3111", 10) || 3111,
+    streamsPort: parseInt(env["III_STREAMS_PORT"] || "3112", 10) || 3112,
+    provider,
+    tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),
+    maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),
+    compressionModel: provider.model,
+    dataDir: DATA_DIR,
+  };
+}
+
+function getMergedEnv(
+  overrides?: Record<string, string>,
+): Record<string, string> {
+  const fileEnv = loadEnvFile();
+  return { ...fileEnv, ...process.env, ...overrides } as Record<string, string>;
+}
+
+export function getEnvVar(key: string): string | undefined {
+  return getMergedEnv()[key];
+}
+
+export function loadEmbeddingConfig(): EmbeddingConfig {
+  const env = getMergedEnv();
+  let bm25Weight = parseFloat(env["BM25_WEIGHT"] || "0.4");
+  let vectorWeight = parseFloat(env["VECTOR_WEIGHT"] || "0.6");
+  bm25Weight =
+    isNaN(bm25Weight) || bm25Weight < 0 ? 0.4 : Math.min(bm25Weight, 1);
+  vectorWeight =
+    isNaN(vectorWeight) || vectorWeight < 0 ? 0.6 : Math.min(vectorWeight, 1);
+  return {
+    provider: env["EMBEDDING_PROVIDER"] || undefined,
+    bm25Weight,
+    vectorWeight,
+  };
+}
+
+export function detectEmbeddingProvider(
+  env?: Record<string, string>,
+): string | null {
+  const source = env ?? getMergedEnv();
+  const forced = source["EMBEDDING_PROVIDER"];
+  if (forced) return forced;
+
+  if (source["GEMINI_API_KEY"]) return "gemini";
+  if (source["OPENAI_API_KEY"]) return "openai";
+  if (source["VOYAGE_API_KEY"]) return "voyage";
+  if (source["COHERE_API_KEY"]) return "cohere";
+  if (source["OPENROUTER_API_KEY"]) return "openrouter";
+  return null;
+}
+
+export function loadClaudeBridgeConfig(): ClaudeBridgeConfig {
+  const env = getMergedEnv();
+  const enabled = env["CLAUDE_MEMORY_BRIDGE"] === "true";
+  const projectPath = env["CLAUDE_PROJECT_PATH"] || "";
+  const lineBudget = safeParseInt(env["CLAUDE_MEMORY_LINE_BUDGET"], 200);
+  let memoryFilePath = "";
+  if (enabled && projectPath) {
+    const safePath = projectPath.replace(/[/\\]/g, "-").replace(/^-/, "");
+    memoryFilePath = join(
+      homedir(),
+      ".claude",
+      "projects",
+      safePath,
+      "memory",
+      "MEMORY.md",
+    );
+  }
+  return { enabled, projectPath, memoryFilePath, lineBudget };
+}
+
+export function loadTeamConfig(): TeamConfig | null {
+  const env = getMergedEnv();
+  const teamId = env["TEAM_ID"];
+  const userId = env["USER_ID"];
+  if (!teamId || !userId) return null;
+  const mode = env["TEAM_MODE"] === "shared" ? "shared" : "private";
+  return { teamId, userId, mode };
+}
+
+export function loadSnapshotConfig(): {
+  enabled: boolean;
+  interval: number;
+  dir: string;
+} {
+  const env = getMergedEnv();
+  return {
+    enabled: env["SNAPSHOT_ENABLED"] === "true",
+    interval: safeParseInt(env["SNAPSHOT_INTERVAL"], 3600),
+    dir: env["SNAPSHOT_DIR"] || join(homedir(), ".agentmemory", "snapshots"),
+  };
+}
+
+export function isGraphExtractionEnabled(): boolean {
+  return getMergedEnv()["GRAPH_EXTRACTION_ENABLED"] === "true";
+}
+
+export function getGraphBatchSize(): number {
+  return safeParseInt(getMergedEnv()["GRAPH_EXTRACTION_BATCH_SIZE"], 10);
+}
+
+export function isConsolidationEnabled(): boolean {
+  return getMergedEnv()["CONSOLIDATION_ENABLED"] === "true";
+}
+
+export function getConsolidationDecayDays(): number {
+  return safeParseInt(getMergedEnv()["CONSOLIDATION_DECAY_DAYS"], 30);
+}
+
+export function isStandaloneMcp(): boolean {
+  return getMergedEnv()["STANDALONE_MCP"] === "true";
+}
+
+export function getStandalonePersistPath(): string {
+  const env = getMergedEnv();
+  return (
+    env["STANDALONE_PERSIST_PATH"] ||
+    join(homedir(), ".agentmemory", "standalone.json")
+  );
+}
+
+const VALID_PROVIDERS = new Set([
+  "anthropic",
+  "gemini",
+  "openrouter",
+  "agent-sdk",
+]);
+
+export function loadFallbackConfig(): FallbackConfig {
+  const env = getMergedEnv();
+  const raw = env["FALLBACK_PROVIDERS"] || "";
+  const providers = raw
+    .split(",")
+    .map((p) => p.trim())
+    .filter(
+      (p): p is FallbackConfig["providers"][number] =>
+        Boolean(p) && VALID_PROVIDERS.has(p),
+    );
+  return { providers };
+}

package/src/eval/metrics-store.ts

@@ -0,0 +1,65 @@
+import type { FunctionMetrics } from "../types.js";
+import type { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+
+export class MetricsStore {
+  private cache = new Map<string, FunctionMetrics>();
+  private qualityCallCounts = new Map<string, number>();
+
+  constructor(private kv: StateKV) {}
+
+  async record(
+    functionId: string,
+    latencyMs: number,
+    success: boolean,
+    qualityScore?: number,
+  ): Promise<void> {
+    let m = this.cache.get(functionId);
+    if (!m) {
+      m = (await this.kv.get<FunctionMetrics>(KV.metrics, functionId)) ?? {
+        functionId,
+        totalCalls: 0,
+        successCount: 0,
+        failureCount: 0,
+        avgLatencyMs: 0,
+        avgQualityScore: 0,
+      };
+    }
+
+    const prev = m.totalCalls;
+    m.totalCalls += 1;
+    m.avgLatencyMs = (m.avgLatencyMs * prev + latencyMs) / m.totalCalls;
+    if (success) {
+      m.successCount += 1;
+    } else {
+      m.failureCount += 1;
+    }
+    if (qualityScore !== undefined) {
+      const prevQualityCalls = this.qualityCallCounts.get(functionId) || 0;
+      m.avgQualityScore =
+        (m.avgQualityScore * prevQualityCalls + qualityScore) /
+        (prevQualityCalls + 1);
+      this.qualityCallCounts.set(functionId, prevQualityCalls + 1);
+    }
+
+    this.cache.set(functionId, m);
+    await this.kv.set(KV.metrics, functionId, m).catch(() => {});
+  }
+
+  async get(functionId: string): Promise<FunctionMetrics | null> {
+    return (
+      this.cache.get(functionId) ??
+      (await this.kv.get<FunctionMetrics>(KV.metrics, functionId))
+    );
+  }
+
+  async getAll(): Promise<FunctionMetrics[]> {
+    const kvMetrics = await this.kv
+      .list<FunctionMetrics>(KV.metrics)
+      .catch(() => []);
+    const merged = new Map<string, FunctionMetrics>();
+    for (const m of kvMetrics) merged.set(m.functionId, m);
+    for (const [id, m] of this.cache) merged.set(id, m);
+    return Array.from(merged.values());
+  }
+}

package/src/eval/quality.ts

@@ -0,0 +1,51 @@
+export function scoreCompression(obs: {
+  type?: string;
+  title?: string;
+  facts?: string[];
+  narrative?: string;
+  concepts?: string[];
+  importance?: number;
+}): number {
+  let score = 0;
+  if (obs.facts && obs.facts.length > 0) score += 25;
+  if (obs.facts && obs.facts.length >= 3) score += 10;
+  if (obs.narrative && obs.narrative.length >= 20) score += 20;
+  if (obs.narrative && obs.narrative.length >= 50) score += 5;
+  if (obs.title && obs.title.length >= 5 && obs.title.length <= 120) score += 15;
+  if (obs.concepts && obs.concepts.length > 0) score += 15;
+  if (obs.importance && obs.importance >= 1 && obs.importance <= 10) score += 10;
+  return Math.min(100, score);
+}
+
+export function scoreSummary(summary: {
+  title?: string;
+  narrative?: string;
+  keyDecisions?: string[];
+  filesModified?: string[];
+  concepts?: string[];
+}): number {
+  let score = 0;
+  if (summary.title && summary.title.length >= 5) score += 20;
+  if (summary.narrative && summary.narrative.length >= 20) score += 25;
+  if (summary.narrative && summary.narrative.length >= 100) score += 5;
+  if (summary.keyDecisions && summary.keyDecisions.length > 0) score += 20;
+  if (summary.filesModified && summary.filesModified.length > 0) score += 15;
+  if (summary.concepts && summary.concepts.length > 0) score += 15;
+  return Math.min(100, score);
+}
+
+export function scoreContextRelevance(
+  context: string,
+  project: string,
+): number {
+  let score = 0;
+  if (context.length > 0) score += 20;
+  if (project && context.toLowerCase().includes(project.toLowerCase())) score += 20;
+  if (context.includes("<")) score += 15;
+  const sectionCount = (context.match(/<\w+>/g) || []).length;
+  if (sectionCount >= 2) score += 15;
+  if (sectionCount >= 4) score += 10;
+  if (context.length >= 100) score += 10;
+  if (context.length >= 500) score += 10;
+  return Math.min(100, score);
+}

package/src/eval/schemas.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+
+const HookTypeEnum = z.enum([
+  "session_start",
+  "prompt_submit",
+  "pre_tool_use",
+  "post_tool_use",
+  "post_tool_failure",
+  "pre_compact",
+  "subagent_start",
+  "subagent_stop",
+  "notification",
+  "task_completed",
+  "stop",
+  "session_end",
+]);
+
+const ObservationTypeEnum = z.enum([
+  "file_read",
+  "file_write",
+  "file_edit",
+  "command_run",
+  "search",
+  "web_fetch",
+  "conversation",
+  "error",
+  "decision",
+  "discovery",
+  "subagent",
+  "notification",
+  "task",
+  "other",
+]);
+
+export const ObserveInputSchema = z.object({
+  hookType: HookTypeEnum,
+  sessionId: z.string().min(1),
+  project: z.string().min(1),
+  cwd: z.string().min(1),
+  timestamp: z.string().min(1),
+  data: z.unknown(),
+});
+
+export const CompressOutputSchema = z.object({
+  type: ObservationTypeEnum,
+  title: z.string().min(1).max(120),
+  subtitle: z.string().optional(),
+  facts: z.array(z.string()).min(1),
+  narrative: z.string().min(10),
+  concepts: z.array(z.string()),
+  files: z.array(z.string()),
+  importance: z.number().int().min(1).max(10),
+});
+
+export const SummaryOutputSchema = z.object({
+  title: z.string().min(1),
+  narrative: z.string().min(20),
+  keyDecisions: z.array(z.string()),
+  filesModified: z.array(z.string()),
+  concepts: z.array(z.string()),
+});
+
+export const SearchInputSchema = z.object({
+  query: z.string().min(1),
+  limit: z.number().int().positive().optional(),
+});
+
+export const ContextInputSchema = z.object({
+  sessionId: z.string().min(1),
+  project: z.string().min(1),
+  budget: z.number().positive().optional(),
+});
+
+export const RememberInputSchema = z.object({
+  content: z.string().min(1),
+  type: z
+    .enum(["pattern", "preference", "architecture", "bug", "workflow", "fact"])
+    .optional(),
+  concepts: z.array(z.string()).optional(),
+  files: z.array(z.string()).optional(),
+});
+
+export const SmartSearchInputSchema = z.object({
+  query: z.string().optional(),
+  expandIds: z.array(z.string()).optional(),
+  limit: z.number().int().positive().optional(),
+});
+
+export const TimelineInputSchema = z.object({
+  anchor: z.string().min(1),
+  project: z.string().optional(),
+  before: z.number().int().nonnegative().optional(),
+  after: z.number().int().nonnegative().optional(),
+});
+
+export const ProfileInputSchema = z.object({
+  project: z.string().min(1),
+  refresh: z.boolean().optional(),
+});
+
+export const RelateInputSchema = z.object({
+  sourceId: z.string().min(1),
+  targetId: z.string().min(1),
+  type: z.enum(["supersedes", "extends", "derives", "contradicts", "related"]),
+});
+
+export const EvolveInputSchema = z.object({
+  memoryId: z.string().min(1),
+  newContent: z.string().min(1),
+  newTitle: z.string().optional(),
+});
+
+export const ExportImportInputSchema = z.object({
+  exportData: z.object({
+    version: z.union([z.literal("0.3.0"), z.literal("0.4.0")]),
+    exportedAt: z.string(),
+    sessions: z.array(z.unknown()),
+    observations: z.record(z.string(), z.array(z.unknown())),
+    memories: z.array(z.unknown()),
+    summaries: z.array(z.unknown()),
+    profiles: z.array(z.unknown()).optional(),
+  }),
+  strategy: z.enum(["merge", "replace", "skip"]).optional(),
+});

package/src/eval/self-correct.ts

@@ -0,0 +1,28 @@
+import type { MemoryProvider } from "../types.js";
+
+const STRICTER_SUFFIX = `
+
+IMPORTANT: Your previous response was invalid. Please ensure your output strictly follows the required XML format. Every required field must be present with valid values.`;
+
+export async function compressWithRetry(
+  provider: MemoryProvider,
+  systemPrompt: string,
+  userPrompt: string,
+  validator: (response: string) => { valid: boolean; errors?: string[] },
+  maxRetries = 1,
+): Promise<{ response: string; retried: boolean }> {
+  const first = await provider.compress(systemPrompt, userPrompt);
+  const result = validator(first);
+  if (result.valid) return { response: first, retried: false };
+
+  for (let i = 0; i < maxRetries; i++) {
+    const retry = await provider.compress(
+      systemPrompt + STRICTER_SUFFIX,
+      userPrompt,
+    );
+    const retryResult = validator(retry);
+    if (retryResult.valid) return { response: retry, retried: true };
+  }
+
+  return { response: first, retried: true };
+}

package/src/eval/validator.ts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import type { EvalResult } from "../types.js";
+
+export function validateInput<T>(
+  schema: z.ZodType<T>,
+  data: unknown,
+  functionId: string,
+): { valid: true; data: T } | { valid: false; result: EvalResult } {
+  const parsed = schema.safeParse(data);
+  if (parsed.success) {
+    return { valid: true, data: parsed.data };
+  }
+  return {
+    valid: false,
+    result: {
+      valid: false,
+      errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`),
+      qualityScore: 0,
+      latencyMs: 0,
+      functionId,
+    },
+  };
+}
+
+export function validateOutput<T>(
+  schema: z.ZodType<T>,
+  data: unknown,
+  functionId: string,
+): { valid: true; data: T } | { valid: false; result: EvalResult } {
+  return validateInput(schema, data, functionId);
+}