Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat: agentmemory v0.4.0 — the memory layer for all AI coding agents (#9)

Rohit Ghumare134cf961242e
diff --git a/README.md b/README.md
index 540c1101..08d9659c 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,13 @@ No manual notes. No copy-pasting. The agent just *knows*.
| **Auto-forgetting** | TTL expiry, contradiction detection, and importance-based eviction keep memory clean |
| **Privacy first** | API keys, secrets, and `<private>` tags are stripped before anything is stored |
| **Self-healing** | Circuit breaker, provider fallback chain, self-correcting LLM output, health monitoring |
+| **Claude Code bridge** | Bi-directional sync with `~/.claude/projects/*/memory/MEMORY.md` |
+| **Cross-agent MCP** | Standalone MCP server for Cursor, Codex, Gemini CLI, Windsurf, any MCP client |
+| **Knowledge graph** | Entity extraction + BFS traversal across files, functions, concepts, errors |
+| **4-tier memory** | Working → episodic → semantic → procedural consolidation with strength decay |
+| **Team memory** | Namespaced shared + private memory across team members |
+| **Governance** | Edit, delete, bulk-delete, and audit trail for all memory operations |
+| **Git snapshots** | Version, rollback, and diff memory state via git commits |
### How it compares
@@ -84,7 +91,7 @@ These agents support hooks natively. agentmemory captures tool usage automatical
### MCP support (any MCP-compatible agent)
-Any agent that connects to MCP servers can use agentmemory's 10 tools, 4 resources, and 3 prompts. The agent actively queries and saves memory through MCP calls.
+Any agent that connects to MCP servers can use agentmemory's 18 tools, 6 resources, and 3 prompts. The agent actively queries and saves memory through MCP calls.
| Agent | How to connect |
|---|---|
@@ -96,7 +103,7 @@ Any agent that connects to MCP servers can use agentmemory's 10 tools, 4 resourc
### REST API (any agent, any language)
-Agents without hooks or MCP can integrate via 34 REST endpoints directly. This works with any agent, language, or framework.
+Agents without hooks or MCP can integrate via 49 REST endpoints directly. This works with any agent, language, or framework.
```bash
POST /agentmemory/observe # Capture what the agent did
@@ -113,8 +120,8 @@ GET /agentmemory/profile # Get project intelligence
|---|---|
| Claude Code user | Plugin install (hooks + MCP + skills) |
| Building a custom agent with Claude SDK | AgentSDKProvider (zero config) |
-| Using Cursor, Windsurf, or any MCP client | MCP server (10 tools + 4 resources + 3 prompts) |
-| Building your own agent framework | REST API (34 endpoints) |
+| Using Cursor, Windsurf, or any MCP client | MCP server (18 tools + 6 resources + 3 prompts) |
+| Building your own agent framework | REST API (49 endpoints) |
| Sharing memory across multiple agents | All agents point to the same iii-engine instance |
## Quick Start
@@ -362,7 +369,7 @@ Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event lo
## MCP Server
-### Tools (10)
+### Tools (18)
| Tool | Description |
|------|-------------|
@@ -376,8 +383,16 @@ Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event lo
| `memory_profile` | Project profile with top concepts, files, patterns |
| `memory_export` | Export all memory data as JSON |
| `memory_relations` | Query memory relationship graph (with confidence filtering) |
+| `memory_claude_bridge_sync` | Sync memory to/from Claude Code's native MEMORY.md |
+| `memory_graph_query` | Query the knowledge graph for entities and relationships |
+| `memory_consolidate` | Run 4-tier memory consolidation pipeline |
+| `memory_team_share` | Share a memory or observation with team members |
+| `memory_team_feed` | Get recent shared items from all team members |
+| `memory_audit` | View the audit trail of memory operations |
+| `memory_governance_delete` | Delete specific memories with audit trail |
+| `memory_snapshot_create` | Create a git-versioned snapshot of memory state |
-### Resources (4)
+### Resources (6)
| URI | Description |
|-----|-------------|
@@ -385,6 +400,8 @@ Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event lo
| `agentmemory://project/{name}/profile` | Per-project intelligence (concepts, files, conventions) |
| `agentmemory://project/{name}/recent` | Last 5 session summaries for a project |
| `agentmemory://memories/latest` | Latest 10 active memories (id, title, type, strength) |
+| `agentmemory://graph/stats` | Knowledge graph node and edge counts by type |
+| `agentmemory://team/{id}/profile` | Team memory profile with shared concepts and patterns |
### Prompts (3)
@@ -394,7 +411,30 @@ Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event lo
| `session_handoff` | `session_id` | Returns session data + summary for handoff between agents |
| `detect_patterns` | `project` (optional) | Analyzes recurring patterns across sessions |
-### MCP Endpoints
+### Standalone MCP Server
+
+Run agentmemory as a standalone MCP server for any MCP-compatible agent (Cursor, Codex, Gemini CLI, Windsurf):
+
+```bash
+npx agentmemory-mcp
+```
+
+Or add to your agent's MCP config:
+
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["agentmemory-mcp"]
+ }
+ }
+}
+```
+
+The standalone server uses in-memory KV with optional JSON persistence (`STANDALONE_PERSIST_PATH`).
+
+### MCP Endpoints (embedded mode)
```http
GET /agentmemory/mcp/tools — List available tools
@@ -465,16 +505,42 @@ ANTHROPIC_API_KEY=sk-ant-...
# Memory tuning
# TOKEN_BUDGET=2000
# MAX_OBS_PER_SESSION=500
+
+# Claude Code Memory Bridge (v0.4.0)
+# CLAUDE_MEMORY_BRIDGE=false
+# CLAUDE_MEMORY_LINE_BUDGET=200
+
+# Standalone MCP Server (v0.4.0)
+# STANDALONE_MCP=false
+# STANDALONE_PERSIST_PATH=~/.agentmemory/standalone.json
+
+# Knowledge Graph (v0.4.0)
+# GRAPH_EXTRACTION_ENABLED=false
+# GRAPH_EXTRACTION_BATCH_SIZE=10
+
+# Consolidation Pipeline (v0.4.0)
+# CONSOLIDATION_ENABLED=false
+# CONSOLIDATION_DECAY_DAYS=30
+
+# Team Memory (v0.4.0)
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Git Snapshots (v0.4.0)
+# SNAPSHOT_ENABLED=false
+# SNAPSHOT_INTERVAL=3600
+# SNAPSHOT_DIR=~/.agentmemory/snapshots
```
## API
-34 endpoints on port `3111` (28 core + 6 MCP protocol). Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set.
+49 endpoints on port `3111` (43 core + 6 MCP protocol). Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set.
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check with metrics (always public) |
-| `GET` | `/agentmemory/liveness` | Liveness probe (always public) |
+| `GET` | `/agentmemory/livez` | Liveness probe (always public) |
| `POST` | `/agentmemory/session/start` | Start session + get context |
| `POST` | `/agentmemory/session/end` | Mark session complete |
| `POST` | `/agentmemory/observe` | Capture observation |
@@ -501,6 +567,21 @@ ANTHROPIC_API_KEY=sk-ant-...
| `GET` | `/agentmemory/sessions` | List all sessions |
| `GET` | `/agentmemory/observations` | Session observations (`?sessionId=X`) |
| `GET` | `/agentmemory/viewer` | Real-time web viewer |
+| `GET` | `/agentmemory/claude-bridge/read` | Read Claude Code native MEMORY.md |
+| `POST` | `/agentmemory/claude-bridge/sync` | Sync memories to MEMORY.md |
+| `POST` | `/agentmemory/graph/query` | Query knowledge graph (BFS traversal) |
+| `GET` | `/agentmemory/graph/stats` | Knowledge graph node/edge counts |
+| `POST` | `/agentmemory/graph/extract` | Extract entities from observations |
+| `POST` | `/agentmemory/consolidate-pipeline` | Run 4-tier consolidation pipeline |
+| `POST` | `/agentmemory/team/share` | Share memory with team members |
+| `GET` | `/agentmemory/team/feed` | Recent shared items from team |
+| `GET` | `/agentmemory/team/profile` | Aggregated team memory profile |
+| `GET` | `/agentmemory/audit` | Query audit trail (`?operation=X&limit=N`) |
+| `DELETE` | `/agentmemory/governance/memories` | Delete specific memories with audit |
+| `POST` | `/agentmemory/governance/bulk-delete` | Bulk delete by type/date/quality |
+| `GET` | `/agentmemory/snapshots` | List git snapshots |
+| `POST` | `/agentmemory/snapshot/create` | Create git-versioned snapshot |
+| `POST` | `/agentmemory/snapshot/restore` | Restore from snapshot commit |
| `GET` | `/agentmemory/mcp/tools` | List MCP tools |
| `POST` | `/agentmemory/mcp/call` | Execute MCP tool |
| `GET` | `/agentmemory/mcp/resources` | List MCP resources |
@@ -517,7 +598,7 @@ ANTHROPIC_API_KEY=sk-ant-...
/plugin install agentmemory
```
-Restart Claude Code. All 12 hooks, 4 skills, and MCP tools are registered automatically.
+Restart Claude Code. All 12 hooks, 4 skills, and 18 MCP tools are registered automatically.
### Plugin Commands
@@ -541,9 +622,9 @@ agentmemory is built on iii-engine's three primitives:
| Prometheus / Grafana | iii OTEL + built-in health monitor |
| Redis (circuit breaker) | In-process circuit breaker + fallback chain |
-**70 source files. ~8,200 LOC. 173 tests. 142KB bundled.**
+**83 source files. ~11,000 LOC. 216 tests. 208KB bundled (192KB main + 16KB standalone).**
-### Functions (22)
+### Functions (33)
| Function | Purpose |
|----------|---------|
@@ -568,9 +649,23 @@ agentmemory is built on iii-engine's three primitives:
| `mem::profile` | Aggregate project profile |
| `mem::auto-forget` | TTL expiry + contradiction detection |
| `mem::enrich` | Unified enrichment (file context + observations + bug memories) |
-| `mem::export` / `mem::import` | Full JSON round-trip |
-
-### Data Model
+| `mem::export` / `mem::import` | Full JSON round-trip (v0.3.0 + v0.4.0 formats) |
+| `mem::claude-bridge-read` | Read Claude Code native MEMORY.md |
+| `mem::claude-bridge-sync` | Sync top memories back to MEMORY.md |
+| `mem::graph-extract` | LLM-powered entity extraction from observations |
+| `mem::graph-query` | BFS traversal of knowledge graph |
+| `mem::graph-stats` | Node/edge counts by type |
+| `mem::consolidate-pipeline` | 4-tier memory consolidation with strength decay |
+| `mem::team-share` | Share memory/observation with team namespace |
+| `mem::team-feed` | Fetch recent shared items from team |
+| `mem::team-profile` | Aggregate team concepts, files, patterns |
+| `mem::governance-delete` | Delete specific memories with audit trail |
+| `mem::governance-bulk` | Bulk delete by type/date/quality filter |
+| `mem::snapshot-create` | Git commit memory state |
+| `mem::snapshot-list` | List all snapshots |
+| `mem::snapshot-restore` | Restore memory from snapshot commit |
+
+### Data Model (21 KV scopes)
| Scope | Stores |
|-------|--------|
@@ -585,13 +680,23 @@ agentmemory is built on iii-engine's three primitives:
| `mem:metrics` | Per-function metrics |
| `mem:health` | Health snapshots |
| `mem:config` | Runtime configuration overrides |
+| `mem:confidence` | Confidence scores for memories |
+| `mem:claude-bridge` | Claude Code MEMORY.md bridge state |
+| `mem:graph:nodes` | Knowledge graph entities |
+| `mem:graph:edges` | Knowledge graph relationships |
+| `mem:semantic` | Semantic memories (consolidated facts) |
+| `mem:procedural` | Procedural memories (extracted workflows) |
+| `mem:team:{id}:shared` | Team shared items |
+| `mem:team:{id}:users:{uid}` | Per-user team state |
+| `mem:team:{id}:profile` | Aggregated team profile |
+| `mem:audit` | Audit trail for all operations |
## Development
```bash
npm run dev # Hot reload
-npm run build # Production build (142KB)
-npm test # Unit tests (173 tests, ~1s)
+npm run build # Production build (208KB)
+npm test # Unit tests (216 tests, ~1s)
npm run test:integration # API tests (requires running services)
```
diff --git a/package.json b/package.json
index 0506557b..f378024d 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
"main": "dist/index.js",
"types": "dist/index.d.ts",
"bin": {
- "agentmemory": "dist/index.js"
+ "agentmemory": "dist/index.js",
+ "agentmemory-mcp": "dist/standalone.mjs"
},
"scripts": {
"build": "tsdown",
diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs
index d715d82a..261839ed 100755
--- a/plugin/scripts/pre-compact.mjs
+++ b/plugin/scripts/pre-compact.mjs
@@ -18,6 +18,13 @@ async function main() {
}
const sessionId = data.session_id || "unknown";
const project = data.cwd || process.cwd();
+ if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") try {
+ await fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {
+ method: "POST",
+ headers: authHeaders(),
+ signal: AbortSignal.timeout(5e3)
+ });
+ } catch {}
try {
const res = await fetch(`${REST_URL}/agentmemory/context`, {
method: "POST",
diff --git a/plugin/scripts/session-end.mjs b/plugin/scripts/session-end.mjs
index c4b0fc4f..aa29ad1c 100755
--- a/plugin/scripts/session-end.mjs
+++ b/plugin/scripts/session-end.mjs
@@ -25,6 +25,13 @@ async function main() {
signal: AbortSignal.timeout(5e3)
});
} catch {}
+ if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") try {
+ await fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {
+ method: "POST",
+ headers: authHeaders(),
+ signal: AbortSignal.timeout(5e3)
+ });
+ } catch {}
}
main();
diff --git a/src/config.ts b/src/config.ts
index bf80a0a8..4c3faedf 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -6,6 +6,8 @@ import type {
ProviderConfig,
EmbeddingConfig,
FallbackConfig,
+ ClaudeBridgeConfig,
+ TeamConfig,
} from "./types.js";
function safeParseInt(value: string | undefined, fallback: number): number {
@@ -128,6 +130,76 @@ export function detectEmbeddingProvider(
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",
diff --git a/src/functions/audit.ts b/src/functions/audit.ts
new file mode 100644
index 00000000..3827d3cc
--- /dev/null
+++ b/src/functions/audit.ts
@@ -0,0 +1,61 @@
+import type { AuditEntry } from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+export async function recordAudit(
+ kv: StateKV,
+ operation: AuditEntry["operation"],
+ functionId: string,
+ targetIds: string[],
+ details: Record<string, unknown> = {},
+ qualityScore?: number,
+ userId?: string,
+): Promise<AuditEntry> {
+ const entry: AuditEntry = {
+ id: generateId("aud"),
+ timestamp: new Date().toISOString(),
+ operation,
+ userId,
+ functionId,
+ targetIds,
+ details,
+ qualityScore,
+ };
+ await kv.set(KV.audit, entry.id, entry);
+ return entry;
+}
+
+export async function queryAudit(
+ kv: StateKV,
+ filter?: {
+ operation?: AuditEntry["operation"];
+ dateFrom?: string;
+ dateTo?: string;
+ limit?: number;
+ },
+): Promise<AuditEntry[]> {
+ const all = await kv.list<AuditEntry>(KV.audit);
+ let entries = [...all].sort(
+ (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+ );
+
+ if (filter?.operation) {
+ entries = entries.filter((e) => e.operation === filter.operation);
+ }
+ if (filter?.dateFrom) {
+ const from = new Date(filter.dateFrom).getTime();
+ if (Number.isNaN(from)) {
+ throw new Error(`Invalid dateFrom: ${filter.dateFrom}`);
+ }
+ entries = entries.filter((e) => new Date(e.timestamp).getTime() >= from);
+ }
+ if (filter?.dateTo) {
+ const to = new Date(filter.dateTo).getTime();
+ if (Number.isNaN(to)) {
+ throw new Error(`Invalid dateTo: ${filter.dateTo}`);
+ }
+ entries = entries.filter((e) => new Date(e.timestamp).getTime() <= to);
+ }
+
+ return entries.slice(0, filter?.limit || 100);
+}
diff --git a/src/functions/claude-bridge.ts b/src/functions/claude-bridge.ts
new file mode 100644
index 00000000..149bc938
--- /dev/null
+++ b/src/functions/claude-bridge.ts
@@ -0,0 +1,161 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Memory, ClaudeBridgeConfig } from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+function parseMemoryMd(content: string): {
+ sections: Map<string, string>;
+ raw: string;
+} {
+ const sections = new Map<string, string>();
+ let currentSection = "";
+ let currentContent: string[] = [];
+
+ for (const line of content.split("\n")) {
+ if (line.startsWith("## ")) {
+ if (currentSection) {
+ sections.set(currentSection, currentContent.join("\n").trim());
+ }
+ currentSection = line.slice(3).trim();
+ currentContent = [];
+ } else {
+ currentContent.push(line);
+ }
+ }
+ if (currentSection) {
+ sections.set(currentSection, currentContent.join("\n").trim());
+ }
+
+ return { sections, raw: content };
+}
+
+function serializeToMemoryMd(
+ memories: Memory[],
+ projectSummary: string,
+ lineBudget: number,
+): string {
+ const lines: string[] = [];
+ lines.push("# Agent Memory (auto-synced by agentmemory)");
+ lines.push("");
+
+ if (projectSummary) {
+ lines.push("## Project Summary");
+ lines.push(projectSummary);
+ lines.push("");
+ }
+
+ lines.push("## Key Memories");
+ lines.push("");
+
+ const sorted = [...memories]
+ .filter((m) => m.isLatest)
+ .sort((a, b) => b.strength - a.strength);
+
+ for (const mem of sorted) {
+ if (lines.length >= lineBudget - 2) break;
+ lines.push(`### ${mem.title}`);
+ const contentLines = mem.content.split("\n");
+ for (const cl of contentLines) {
+ if (lines.length >= lineBudget - 1) break;
+ lines.push(cl);
+ }
+ lines.push("");
+ }
+
+ return lines.slice(0, lineBudget).join("\n");
+}
+
+export function registerClaudeBridgeFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ config: ClaudeBridgeConfig,
+): void {
+ sdk.registerFunction(
+ { id: "mem::claude-bridge-read" },
+ async () => {
+ const ctx = getContext();
+ if (!config.enabled || !config.memoryFilePath) {
+ return { success: false, error: "Claude bridge not configured" };
+ }
+
+ try {
+ if (!existsSync(config.memoryFilePath)) {
+ return { success: true, content: "", parsed: false };
+ }
+ const content = readFileSync(config.memoryFilePath, "utf-8");
+ const { sections } = parseMemoryMd(content);
+
+ await kv.set(KV.claudeBridge, "last-read", {
+ timestamp: new Date().toISOString(),
+ sections: Object.fromEntries(sections),
+ lineCount: content.split("\n").length,
+ });
+
+ ctx.logger.info("Claude bridge: read MEMORY.md", {
+ path: config.memoryFilePath,
+ lines: content.split("\n").length,
+ });
+ return { success: true, content, sections: Object.fromEntries(sections) };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Claude bridge read failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::claude-bridge-sync" },
+ async () => {
+ const ctx = getContext();
+ if (!config.enabled || !config.memoryFilePath) {
+ return { success: false, error: "Claude bridge not configured" };
+ }
+
+ try {
+ const memories = await kv.list<Memory>(KV.memories);
+ const latestMemories = memories.filter((m) => m.isLatest);
+
+ let projectSummary = "";
+ if (config.projectPath) {
+ const profile = await kv
+ .get<{ summary?: string }>(KV.profiles, config.projectPath)
+ .catch(() => null);
+ projectSummary = profile?.summary || "";
+ }
+
+ const md = serializeToMemoryMd(
+ latestMemories,
+ projectSummary,
+ config.lineBudget,
+ );
+
+ const dir = dirname(config.memoryFilePath);
+ if (!existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+ writeFileSync(config.memoryFilePath, md, "utf-8");
+
+ await recordAudit(kv, "export", "mem::claude-bridge-sync", [], {
+ path: config.memoryFilePath,
+ memoryCount: latestMemories.length,
+ lines: md.split("\n").length,
+ });
+
+ ctx.logger.info("Claude bridge: synced to MEMORY.md", {
+ path: config.memoryFilePath,
+ memories: latestMemories.length,
+ });
+ return { success: true, path: config.memoryFilePath, lines: md.split("\n").length };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Claude bridge sync failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+}
diff --git a/src/functions/consolidation-pipeline.ts b/src/functions/consolidation-pipeline.ts
new file mode 100644
index 00000000..23042ab0
--- /dev/null
+++ b/src/functions/consolidation-pipeline.ts
@@ -0,0 +1,244 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ SemanticMemory,
+ ProceduralMemory,
+ SessionSummary,
+ Memory,
+ MemoryProvider,
+} from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import {
+ SEMANTIC_MERGE_SYSTEM,
+ buildSemanticMergePrompt,
+ PROCEDURAL_EXTRACTION_SYSTEM,
+ buildProceduralExtractionPrompt,
+} from "../prompts/consolidation.js";
+import { recordAudit } from "./audit.js";
+import { getConsolidationDecayDays } from "../config.js";
+
+function applyDecay(
+ items: Array<{
+ strength: number;
+ lastAccessedAt?: string;
+ updatedAt: string;
+ }>,
+ decayDays: number,
+): void {
+ if (decayDays <= 0 || !Number.isFinite(decayDays)) return;
+ const now = Date.now();
+ for (const item of items) {
+ const lastAccess = item.lastAccessedAt || item.updatedAt;
+ const daysSince =
+ (now - new Date(lastAccess).getTime()) / (1000 * 60 * 60 * 24);
+ if (daysSince > decayDays) {
+ const decayPeriods = Math.floor(daysSince / decayDays);
+ item.strength = Math.max(
+ 0.1,
+ item.strength * Math.pow(0.9, decayPeriods),
+ );
+ }
+ }
+}
+
+export function registerConsolidationPipelineFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ provider: MemoryProvider,
+): void {
+ sdk.registerFunction(
+ { id: "mem::consolidate-pipeline" },
+ async (data?: { tier?: string }) => {
+ const ctx = getContext();
+ const tier = data?.tier || "all";
+ const decayDays = getConsolidationDecayDays();
+ const results: Record<string, unknown> = {};
+
+ if (tier === "all" || tier === "semantic") {
+ const summaries = await kv.list<SessionSummary>(KV.summaries);
+ const existingSemantic = await kv.list<SemanticMemory>(KV.semantic);
+
+ if (summaries.length >= 5) {
+ const recentSummaries = summaries
+ .sort(
+ (a, b) =>
+ new Date(b.createdAt).getTime() -
+ new Date(a.createdAt).getTime(),
+ )
+ .slice(0, 20);
+
+ const prompt = buildSemanticMergePrompt(
+ recentSummaries.map((s) => ({
+ title: s.title,
+ narrative: s.narrative,
+ concepts: s.concepts,
+ })),
+ );
+
+ try {
+ const response = await provider.summarize(
+ SEMANTIC_MERGE_SYSTEM,
+ prompt,
+ );
+
+ const factRegex = /<fact\s+confidence="([^"]+)">([^<]+)<\/fact>/g;
+ let match;
+ let newFacts = 0;
+ const now = new Date().toISOString();
+
+ while ((match = factRegex.exec(response)) !== null) {
+ const parsedConf = parseFloat(match[1]);
+ const confidence = Number.isNaN(parsedConf) ? 0.5 : parsedConf;
+ const fact = match[2].trim();
+
+ const existing = existingSemantic.find(
+ (s) => s.fact.toLowerCase() === fact.toLowerCase(),
+ );
+ if (existing) {
+ existing.accessCount++;
+ existing.lastAccessedAt = now;
+ existing.updatedAt = now;
+ existing.confidence = Math.max(existing.confidence, confidence);
+ await kv.set(KV.semantic, existing.id, existing);
+ } else {
+ const sem: SemanticMemory = {
+ id: generateId("sem"),
+ fact,
+ confidence,
+ sourceSessionIds: recentSummaries.map((s) => s.sessionId),
+ sourceMemoryIds: [],
+ accessCount: 1,
+ lastAccessedAt: now,
+ strength: confidence,
+ createdAt: now,
+ updatedAt: now,
+ };
+ await kv.set(KV.semantic, sem.id, sem);
+ newFacts++;
+ }
+ }
+ results.semantic = { newFacts, totalSummaries: summaries.length };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Semantic consolidation failed", { error: msg });
+ results.semantic = { error: msg };
+ }
+ } else {
+ results.semantic = {
+ skipped: true,
+ reason: "fewer than 5 summaries",
+ };
+ }
+ }
+
+ if (tier === "all" || tier === "procedural") {
+ const memories = await kv.list<Memory>(KV.memories);
+ const patterns = memories
+ .filter((m) => m.isLatest && m.type === "pattern")
+ .map((m) => ({
+ content: m.content,
+ frequency: m.sessionIds.length || 1,
+ }))
+ .filter((p) => p.frequency >= 2);
+
+ if (patterns.length >= 2) {
+ const prompt = buildProceduralExtractionPrompt(patterns);
+
+ try {
+ const response = await provider.summarize(
+ PROCEDURAL_EXTRACTION_SYSTEM,
+ prompt,
+ );
+
+ const procRegex =
+ /<procedure\s+name="([^"]+)"\s+trigger="([^"]+)">([\s\S]*?)<\/procedure>/g;
+ let match;
+ let newProcs = 0;
+ const now = new Date().toISOString();
+ const existingProcs = await kv.list<ProceduralMemory>(
+ KV.procedural,
+ );
+
+ while ((match = procRegex.exec(response)) !== null) {
+ const name = match[1];
+ const trigger = match[2];
+ const stepsBlock = match[3];
+ const steps: string[] = [];
+
+ const stepRegex = /<step>([^<]+)<\/step>/g;
+ let stepMatch;
+ while ((stepMatch = stepRegex.exec(stepsBlock)) !== null) {
+ steps.push(stepMatch[1].trim());
+ }
+
+ const existing = existingProcs.find(
+ (p) => p.name.toLowerCase() === name.toLowerCase(),
+ );
+ if (existing) {
+ existing.frequency++;
+ existing.updatedAt = now;
+ existing.strength = Math.min(1, existing.strength + 0.1);
+ await kv.set(KV.procedural, existing.id, existing);
+ } else {
+ const proc: ProceduralMemory = {
+ id: generateId("proc"),
+ name,
+ steps,
+ triggerCondition: trigger,
+ frequency: 1,
+ sourceSessionIds: [],
+ strength: 0.5,
+ createdAt: now,
+ updatedAt: now,
+ };
+ await kv.set(KV.procedural, proc.id, proc);
+ newProcs++;
+ }
+ }
+ results.procedural = {
+ newProcedures: newProcs,
+ patternsAnalyzed: patterns.length,
+ };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Procedural extraction failed", { error: msg });
+ results.procedural = { error: msg };
+ }
+ } else {
+ results.procedural = {
+ skipped: true,
+ reason: "fewer than 2 recurring patterns",
+ };
+ }
+ }
+
+ if (tier === "all" || tier === "decay") {
+ const semantic = await kv.list<SemanticMemory>(KV.semantic);
+ applyDecay(semantic, decayDays);
+ for (const s of semantic) {
+ await kv.set(KV.semantic, s.id, s);
+ }
+
+ const procedural = await kv.list<ProceduralMemory>(KV.procedural);
+ applyDecay(procedural, decayDays);
+ for (const p of procedural) {
+ await kv.set(KV.procedural, p.id, p);
+ }
+
+ results.decay = {
+ semantic: semantic.length,
+ procedural: procedural.length,
+ };
+ }
+
+ await recordAudit(kv, "consolidate", "mem::consolidate-pipeline", [], {
+ tier,
+ results,
+ });
+
+ ctx.logger.info("Consolidation pipeline complete", { tier, results });
+ return { success: true, results };
+ },
+ );
+}
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index ac9dc41d..46dfb9e9 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -7,6 +7,10 @@ import type {
SessionSummary,
ProjectProfile,
ExportData,
+ GraphNode,
+ GraphEdge,
+ SemanticMemory,
+ ProceduralMemory,
} from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
@@ -40,14 +44,33 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
if (profile) profiles.push(profile);
}
+ const graphNodes = await kv
+ .list<GraphNode>(KV.graphNodes)
+ .catch(() => []);
+ const graphEdges = await kv
+ .list<GraphEdge>(KV.graphEdges)
+ .catch(() => []);
+ const semanticMemories = await kv
+ .list<SemanticMemory>(KV.semantic)
+ .catch(() => []);
+ const proceduralMemories = await kv
+ .list<ProceduralMemory>(KV.procedural)
+ .catch(() => []);
+
const exportData: ExportData = {
- version: "0.3.0",
+ version: "0.4.0",
exportedAt: new Date().toISOString(),
sessions,
observations,
memories,
summaries,
profiles: profiles.length > 0 ? profiles : undefined,
+ graphNodes: graphNodes.length > 0 ? graphNodes : undefined,
+ graphEdges: graphEdges.length > 0 ? graphEdges : undefined,
+ semanticMemories:
+ semanticMemories.length > 0 ? semanticMemories : undefined,
+ proceduralMemories:
+ proceduralMemories.length > 0 ? proceduralMemories : undefined,
};
const totalObs = Object.values(observations).reduce(
@@ -78,7 +101,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
const strategy = data.strategy || "merge";
const importData = data.exportData;
- if (importData.version !== "0.3.0") {
+ if (importData.version !== "0.3.0" && importData.version !== "0.4.0") {
return {
success: false,
error: `Unsupported export version: ${importData.version}`,
@@ -242,6 +265,27 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
stats.summaries++;
}
+ if (importData.graphNodes) {
+ for (const node of importData.graphNodes) {
+ await kv.set(KV.graphNodes, node.id, node);
+ }
+ }
+ if (importData.graphEdges) {
+ for (const edge of importData.graphEdges) {
+ await kv.set(KV.graphEdges, edge.id, edge);
+ }
+ }
+ if (importData.semanticMemories) {
+ for (const sem of importData.semanticMemories) {
+ await kv.set(KV.semantic, sem.id, sem);
+ }
+ }
+ if (importData.proceduralMemories) {
+ for (const proc of importData.proceduralMemories) {
+ await kv.set(KV.procedural, proc.id, proc);
+ }
+ }
+
ctx.logger.info("Import complete", { strategy, ...stats });
return { success: true, strategy, ...stats };
},
diff --git a/src/functions/governance.ts b/src/functions/governance.ts
new file mode 100644
index 00000000..efc0cd17
--- /dev/null
+++ b/src/functions/governance.ts
@@ -0,0 +1,118 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, GovernanceFilter, AuditEntry } from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit, queryAudit } from "./audit.js";
+
+export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ { id: "mem::governance-delete" },
+ async (data: { memoryIds: string[]; reason?: string }) => {
+ const ctx = getContext();
+ if (
+ !data.memoryIds ||
+ !Array.isArray(data.memoryIds) ||
+ data.memoryIds.length === 0
+ ) {
+ return { success: false, error: "memoryIds array is required" };
+ }
+
+ let deleted = 0;
+ for (const id of data.memoryIds) {
+ const mem = await kv.get<Memory>(KV.memories, id);
+ if (mem) {
+ await kv.delete(KV.memories, id);
+ deleted++;
+ }
+ }
+
+ await recordAudit(
+ kv,
+ "delete",
+ "mem::governance-delete",
+ data.memoryIds,
+ {
+ reason: data.reason || "manual deletion",
+ deleted,
+ },
+ );
+
+ ctx.logger.info("Governance delete", {
+ requested: data.memoryIds.length,
+ deleted,
+ });
+ return { success: true, deleted, total: data.memoryIds.length };
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::governance-bulk" },
+ async (data: GovernanceFilter & { dryRun?: boolean }) => {
+ const ctx = getContext();
+ const memories = await kv.list<Memory>(KV.memories);
+ let candidates = memories;
+
+ if (data.type && data.type.length > 0) {
+ candidates = candidates.filter((m) => data.type!.includes(m.type));
+ }
+ if (data.dateFrom) {
+ const from = new Date(data.dateFrom).getTime();
+ if (Number.isNaN(from)) {
+ return { success: false, error: "Invalid dateFrom format" };
+ }
+ candidates = candidates.filter(
+ (m) => new Date(m.createdAt).getTime() >= from,
+ );
+ }
+ if (data.dateTo) {
+ const to = new Date(data.dateTo).getTime();
+ if (Number.isNaN(to)) {
+ return { success: false, error: "Invalid dateTo format" };
+ }
+ candidates = candidates.filter(
+ (m) => new Date(m.createdAt).getTime() <= to,
+ );
+ }
+ if (data.qualityBelow !== undefined) {
+ candidates = candidates.filter((m) => m.strength < data.qualityBelow!);
+ }
+
+ if (data.dryRun) {
+ return {
+ success: true,
+ dryRun: true,
+ wouldDelete: candidates.length,
+ ids: candidates.map((m) => m.id),
+ };
+ }
+
+ for (const mem of candidates) {
+ await kv.delete(KV.memories, mem.id);
+ }
+
+ await recordAudit(
+ kv,
+ "delete",
+ "mem::governance-bulk",
+ candidates.map((m) => m.id),
+ { filter: data, deleted: candidates.length },
+ );
+
+ ctx.logger.info("Governance bulk delete", { deleted: candidates.length });
+ return { success: true, deleted: candidates.length };
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::audit-query" },
+ async (data?: {
+ operation?: AuditEntry["operation"];
+ dateFrom?: string;
+ dateTo?: string;
+ limit?: number;
+ }) => {
+ return queryAudit(kv, data);
+ },
+ );
+}
diff --git a/src/functions/graph.ts b/src/functions/graph.ts
new file mode 100644
index 00000000..3499b956
--- /dev/null
+++ b/src/functions/graph.ts
@@ -0,0 +1,275 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ GraphNode,
+ GraphEdge,
+ GraphQueryResult,
+ CompressedObservation,
+ MemoryProvider,
+} from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import {
+ GRAPH_EXTRACTION_SYSTEM,
+ buildGraphExtractionPrompt,
+} from "../prompts/graph-extraction.js";
+import { recordAudit } from "./audit.js";
+
+function parseGraphXml(
+ xml: string,
+ observationIds: string[],
+): {
+ nodes: GraphNode[];
+ edges: GraphEdge[];
+} {
+ const nodes: GraphNode[] = [];
+ const edges: GraphEdge[] = [];
+ const now = new Date().toISOString();
+
+ const entityRegex =
+ /<entity\s+type="([^"]+)"\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/entity>/g;
+ let match;
+ while ((match = entityRegex.exec(xml)) !== null) {
+ const type = match[1] as GraphNode["type"];
+ const name = match[2];
+ const propsBlock = match[3];
+ const properties: Record<string, string> = {};
+
+ const propRegex = /<property\s+key="([^"]+)">([^<]*)<\/property>/g;
+ let propMatch;
+ while ((propMatch = propRegex.exec(propsBlock)) !== null) {
+ properties[propMatch[1]] = propMatch[2];
+ }
+
+ nodes.push({
+ id: generateId("gn"),
+ type,
+ name,
+ properties,
+ sourceObservationIds: observationIds,
+ createdAt: now,
+ });
+ }
+
+ const relRegex =
+ /<relationship\s+type="([^"]+)"\s+source="([^"]+)"\s+target="([^"]+)"\s+weight="([^"]+)"\s*\/>/g;
+ while ((match = relRegex.exec(xml)) !== null) {
+ const type = match[1] as GraphEdge["type"];
+ const sourceName = match[2];
+ const targetName = match[3];
+ const parsedWeight = parseFloat(match[4]);
+ const weight = Number.isNaN(parsedWeight) ? 0.5 : parsedWeight;
+
+ const sourceNode = nodes.find((n) => n.name === sourceName);
+ const targetNode = nodes.find((n) => n.name === targetName);
+
+ if (sourceNode && targetNode) {
+ edges.push({
+ id: generateId("ge"),
+ type,
+ sourceNodeId: sourceNode.id,
+ targetNodeId: targetNode.id,
+ weight: Math.max(0, Math.min(1, weight)),
+ sourceObservationIds: observationIds,
+ createdAt: now,
+ });
+ }
+ }
+
+ return { nodes, edges };
+}
+
+export function registerGraphFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ provider: MemoryProvider,
+): void {
+ sdk.registerFunction(
+ { id: "mem::graph-extract" },
+ async (data: { observations: CompressedObservation[] }) => {
+ const ctx = getContext();
+ if (!data.observations || data.observations.length === 0) {
+ return { success: false, error: "No observations provided" };
+ }
+
+ const prompt = buildGraphExtractionPrompt(
+ data.observations.map((o) => ({
+ title: o.title,
+ narrative: o.narrative,
+ concepts: o.concepts,
+ files: o.files,
+ type: o.type,
+ })),
+ );
+
+ try {
+ const response = await provider.compress(
+ GRAPH_EXTRACTION_SYSTEM,
+ prompt,
+ );
+
+ const obsIds = data.observations.map((o) => o.id);
+ const { nodes, edges } = parseGraphXml(response, obsIds);
+
+ const existingNodes = await kv.list<GraphNode>(KV.graphNodes);
+ const existingEdges = await kv.list<GraphEdge>(KV.graphEdges);
+
+ for (const node of nodes) {
+ const existing = existingNodes.find(
+ (n) => n.name === node.name && n.type === node.type,
+ );
+ if (existing) {
+ const merged = {
+ ...existing,
+ sourceObservationIds: [
+ ...new Set([...existing.sourceObservationIds, ...obsIds]),
+ ],
+ properties: { ...existing.properties, ...node.properties },
+ };
+ await kv.set(KV.graphNodes, existing.id, merged);
+ const idx = existingNodes.findIndex((n) => n.id === existing.id);
+ if (idx !== -1) existingNodes[idx] = merged;
+ } else {
+ await kv.set(KV.graphNodes, node.id, node);
+ existingNodes.push(node);
+ }
+ }
+
+ for (const edge of edges) {
+ const edgeKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`;
+ const existingEdge = existingEdges.find(
+ (e) => `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` === edgeKey,
+ );
+ if (existingEdge) {
+ existingEdge.sourceObservationIds = [
+ ...new Set([...existingEdge.sourceObservationIds, ...obsIds]),
+ ];
+ await kv.set(KV.graphEdges, existingEdge.id, existingEdge);
+ } else {
+ await kv.set(KV.graphEdges, edge.id, edge);
+ existingEdges.push(edge);
+ }
+ }
+
+ await recordAudit(kv, "observe", "mem::graph-extract", obsIds, {
+ nodesExtracted: nodes.length,
+ edgesExtracted: edges.length,
+ });
+
+ ctx.logger.info("Graph extraction complete", {
+ nodes: nodes.length,
+ edges: edges.length,
+ });
+ return {
+ success: true,
+ nodesAdded: nodes.length,
+ edgesAdded: edges.length,
+ };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Graph extraction failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::graph-query" },
+ async (data: {
+ startNodeId?: string;
+ nodeType?: string;
+ maxDepth?: number;
+ query?: string;
+ }): Promise<GraphQueryResult> => {
+ const allNodes = await kv.list<GraphNode>(KV.graphNodes);
+ const allEdges = await kv.list<GraphEdge>(KV.graphEdges);
+ const maxDepth = Math.min(data.maxDepth || 3, 5);
+
+ if (data.query) {
+ const lower = data.query.toLowerCase();
+ const matchingNodes = allNodes.filter(
+ (n) =>
+ n.name.toLowerCase().includes(lower) ||
+ Object.values(n.properties).some((v) =>
+ v.toLowerCase().includes(lower),
+ ),
+ );
+ const nodeIds = new Set(matchingNodes.map((n) => n.id));
+ const relatedEdges = allEdges.filter(
+ (e) => nodeIds.has(e.sourceNodeId) || nodeIds.has(e.targetNodeId),
+ );
+ return { nodes: matchingNodes, edges: relatedEdges, depth: 0 };
+ }
+
+ if (data.startNodeId) {
+ const visited = new Set<string>();
+ const visitedEdges = new Set<string>();
+ const resultNodes: GraphNode[] = [];
+ const resultEdges: GraphEdge[] = [];
+ const queue: Array<{ nodeId: string; depth: number }> = [
+ { nodeId: data.startNodeId, depth: 0 },
+ ];
+
+ while (queue.length > 0) {
+ const { nodeId, depth } = queue.shift()!;
+ if (visited.has(nodeId) || depth > maxDepth) continue;
+ visited.add(nodeId);
+
+ const node = allNodes.find((n) => n.id === nodeId);
+ if (node) {
+ if (!data.nodeType || node.type === data.nodeType) {
+ resultNodes.push(node);
+ }
+ }
+
+ const neighborEdges = allEdges.filter(
+ (e) => e.sourceNodeId === nodeId || e.targetNodeId === nodeId,
+ );
+ for (const edge of neighborEdges) {
+ if (!visitedEdges.has(edge.id)) {
+ visitedEdges.add(edge.id);
+ resultEdges.push(edge);
+ }
+ const nextId =
+ edge.sourceNodeId === nodeId
+ ? edge.targetNodeId
+ : edge.sourceNodeId;
+ if (!visited.has(nextId)) {
+ queue.push({ nodeId: nextId, depth: depth + 1 });
+ }
+ }
+ }
+
+ return { nodes: resultNodes, edges: resultEdges, depth: maxDepth };
+ }
+
+ let filtered = allNodes;
+ if (data.nodeType) {
+ filtered = allNodes.filter((n) => n.type === data.nodeType);
+ }
+ return { nodes: filtered, edges: allEdges, depth: 0 };
+ },
+ );
+
+ sdk.registerFunction({ id: "mem::graph-stats" }, async () => {
+ const nodes = await kv.list<GraphNode>(KV.graphNodes);
+ const edges = await kv.list<GraphEdge>(KV.graphEdges);
+
+ const nodesByType: Record<string, number> = {};
+ for (const n of nodes) {
+ nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
+ }
+
+ const edgesByType: Record<string, number> = {};
+ for (const e of edges) {
+ edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+ }
+
+ return {
+ totalNodes: nodes.length,
+ totalEdges: edges.length,
+ nodesByType,
+ edgesByType,
+ };
+ });
+}
diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.ts
new file mode 100644
index 00000000..0b2aa3b5
--- /dev/null
+++ b/src/functions/snapshot.ts
@@ -0,0 +1,213 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SnapshotMeta, Session, Memory, GraphNode } from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+const execFileAsync = promisify(execFile);
+
+async function gitExec(dir: string, args: string[]): Promise<string> {
+ const { stdout } = await execFileAsync("git", args, { cwd: dir });
+ return stdout.trim();
+}
+
+async function ensureGitRepo(dir: string): Promise<void> {
+ if (!existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+ if (!existsSync(join(dir, ".git"))) {
+ await gitExec(dir, ["init"]);
+ await gitExec(dir, ["config", "user.email", "agentmemory@local"]);
+ await gitExec(dir, ["config", "user.name", "agentmemory"]);
+ }
+}
+
+export function registerSnapshotFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ snapshotDir: string,
+): void {
+ sdk.registerFunction(
+ { id: "mem::snapshot-create" },
+ async (data?: { message?: string }) => {
+ const ctx = getContext();
+
+ try {
+ await ensureGitRepo(snapshotDir);
+
+ const sessions = await kv.list<Session>(KV.sessions);
+ const memories = await kv.list<Memory>(KV.memories);
+ const graphNodes = await kv.list<GraphNode>(KV.graphNodes);
+
+ const observations: Record<string, unknown[]> = {};
+ for (const session of sessions) {
+ const obs = await kv
+ .list(KV.observations(session.id))
+ .catch(() => []);
+ if (obs.length > 0) {
+ observations[session.id] = obs;
+ }
+ }
+
+ const state = {
+ version: "0.4.0",
+ timestamp: new Date().toISOString(),
+ sessions,
+ memories,
+ graphNodes,
+ observations,
+ };
+
+ writeFileSync(
+ join(snapshotDir, "state.json"),
+ JSON.stringify(state, null, 2),
+ "utf-8",
+ );
+
+ await gitExec(snapshotDir, ["add", "."]);
+
+ const message = data?.message || `Snapshot ${new Date().toISOString()}`;
+ try {
+ await gitExec(snapshotDir, ["commit", "-m", message]);
+ } catch (commitErr) {
+ const errMsg =
+ commitErr instanceof Error ? commitErr.message : String(commitErr);
+ if (errMsg.includes("nothing to commit")) {
+ return { success: true, message: "No changes to snapshot" };
+ }
+ throw commitErr;
+ }
+
+ const commitHash = await gitExec(snapshotDir, ["rev-parse", "HEAD"]);
+
+ const meta: SnapshotMeta = {
+ id: generateId("snap"),
+ commitHash,
+ createdAt: new Date().toISOString(),
+ message,
+ stats: {
+ sessions: sessions.length,
+ observations: Object.values(observations).reduce(
+ (sum, arr) => sum + arr.length,
+ 0,
+ ),
+ memories: memories.length,
+ graphNodes: graphNodes.length,
+ },
+ };
+
+ await recordAudit(kv, "export", "mem::snapshot-create", [meta.id], {
+ commitHash,
+ stats: meta.stats,
+ });
+
+ ctx.logger.info("Snapshot created", { commitHash });
+ return { success: true, snapshot: meta };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Snapshot failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+
+ sdk.registerFunction({ id: "mem::snapshot-list" }, async () => {
+ try {
+ if (!existsSync(join(snapshotDir, ".git"))) {
+ return { snapshots: [] };
+ }
+ const log = await gitExec(snapshotDir, [
+ "log",
+ "--format=%H|%aI|%s",
+ "-20",
+ ]);
+ const snapshots = log
+ .split("\n")
+ .filter(Boolean)
+ .map((line) => {
+ const parts = line.split("|");
+ const [hash, date] = parts;
+ const msg = parts.slice(2).join("|");
+ return { commitHash: hash, createdAt: date, message: msg };
+ });
+ return { snapshots };
+ } catch {
+ return { snapshots: [] };
+ }
+ });
+
+ sdk.registerFunction(
+ { id: "mem::snapshot-restore" },
+ async (data: { commitHash: string }) => {
+ const ctx = getContext();
+ if (!data.commitHash) {
+ return { success: false, error: "commitHash is required" };
+ }
+
+ try {
+ await gitExec(snapshotDir, [
+ "checkout",
+ data.commitHash,
+ "--",
+ "state.json",
+ ]);
+ const content = readFileSync(join(snapshotDir, "state.json"), "utf-8");
+ const state = JSON.parse(content) as {
+ sessions?: Array<{ id: string } & Record<string, unknown>>;
+ memories?: Array<{ id: string } & Record<string, unknown>>;
+ graphNodes?: Array<{ id: string } & Record<string, unknown>>;
+ observations?: Record<
+ string,
+ Array<{ id: string } & Record<string, unknown>>
+ >;
+ };
+
+ if (state.sessions) {
+ for (const session of state.sessions) {
+ await kv.set(KV.sessions, session.id, session);
+ }
+ }
+ if (state.memories) {
+ for (const memory of state.memories) {
+ await kv.set(KV.memories, memory.id, memory);
+ }
+ }
+ if (state.graphNodes) {
+ for (const node of state.graphNodes) {
+ await kv.set(KV.graphNodes, node.id, node);
+ }
+ }
+ if (state.observations) {
+ for (const [sessionId, obs] of Object.entries(state.observations)) {
+ for (const o of obs) {
+ await kv.set(KV.observations(sessionId), o.id, o);
+ }
+ }
+ }
+
+ await gitExec(snapshotDir, ["checkout", "HEAD", "--", "state.json"]);
+
+ await recordAudit(kv, "import", "mem::snapshot-restore", [], {
+ commitHash: data.commitHash,
+ sessions: state.sessions?.length || 0,
+ memories: state.memories?.length || 0,
+ graphNodes: state.graphNodes?.length || 0,
+ });
+
+ ctx.logger.info("Snapshot restored", {
+ commitHash: data.commitHash,
+ });
+ return { success: true, commitHash: data.commitHash };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Snapshot restore failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+}
diff --git a/src/functions/team.ts b/src/functions/team.ts
new file mode 100644
index 00000000..68fb1cbc
--- /dev/null
+++ b/src/functions/team.ts
@@ -0,0 +1,134 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ TeamConfig,
+ TeamSharedItem,
+ TeamProfile,
+ Memory,
+} from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+export function registerTeamFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ config: TeamConfig,
+): void {
+ sdk.registerFunction(
+ { id: "mem::team-share" },
+ async (data: {
+ itemId: string;
+ itemType: "memory" | "pattern";
+ project?: string;
+ }) => {
+ const ctx = getContext();
+ if (!data.itemId || !data.itemType) {
+ return { success: false, error: "itemId and itemType are required" };
+ }
+
+ let content: unknown = null;
+ if (data.itemType === "memory" || data.itemType === "pattern") {
+ content = await kv.get<Memory>(KV.memories, data.itemId);
+ }
+
+ if (!content) {
+ return { success: false, error: "Item not found" };
+ }
+
+ const shared: TeamSharedItem = {
+ id: generateId("ts"),
+ sharedBy: config.userId,
+ sharedAt: new Date().toISOString(),
+ type: data.itemType,
+ content,
+ project: data.project || "",
+ visibility: "shared",
+ };
+
+ await kv.set(KV.teamShared(config.teamId), shared.id, shared);
+
+ await recordAudit(kv, "share", "mem::team-share", [data.itemId], {
+ teamId: config.teamId,
+ userId: config.userId,
+ itemType: data.itemType,
+ });
+
+ ctx.logger.info("Team share", {
+ teamId: config.teamId,
+ itemId: data.itemId,
+ });
+ return { success: true, sharedItem: shared };
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::team-feed" },
+ async (data?: { limit?: number }) => {
+ const limit = data?.limit || 20;
+ const items = await kv.list<TeamSharedItem>(KV.teamShared(config.teamId));
+
+ const filtered = items.filter((i) => i.visibility === "shared");
+ const sorted = filtered
+ .sort(
+ (a, b) =>
+ new Date(b.sharedAt).getTime() - new Date(a.sharedAt).getTime(),
+ )
+ .slice(0, limit);
+
+ return { items: sorted, total: filtered.length };
+ },
+ );
+
+ sdk.registerFunction({ id: "mem::team-profile" }, async () => {
+ const items = await kv.list<TeamSharedItem>(KV.teamShared(config.teamId));
+
+ const members = [...new Set(items.map((i) => i.sharedBy))];
+
+ const conceptCounts = new Map<string, number>();
+ const fileCounts = new Map<string, number>();
+ const patterns: string[] = [];
+
+ for (const item of items) {
+ if (item.type === "memory" || item.type === "pattern") {
+ const mem = item.content as Memory;
+ if (mem?.concepts) {
+ for (const c of mem.concepts) {
+ conceptCounts.set(c, (conceptCounts.get(c) || 0) + 1);
+ }
+ }
+ if (mem?.files) {
+ for (const f of mem.files) {
+ fileCounts.set(f, (fileCounts.get(f) || 0) + 1);
+ }
+ }
+ if (item.type === "pattern" && mem?.content) {
+ patterns.push(mem.content.slice(0, 100));
+ }
+ }
+ }
+
+ const topConcepts = [...conceptCounts.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 10)
+ .map(([concept, frequency]) => ({ concept, frequency }));
+
+ const topFiles = [...fileCounts.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 10)
+ .map(([file, frequency]) => ({ file, frequency }));
+
+ const profile: TeamProfile = {
+ teamId: config.teamId,
+ members,
+ topConcepts,
+ topFiles,
+ sharedPatterns: patterns.slice(0, 10),
+ totalSharedItems: items.length,
+ updatedAt: new Date().toISOString(),
+ };
+
+ await kv.set(KV.teamProfile(config.teamId), "profile", profile);
+ return profile;
+ });
+}
diff --git a/src/hooks/pre-compact.ts b/src/hooks/pre-compact.ts
index 9fb680ee..2e2ae370 100644
--- a/src/hooks/pre-compact.ts
+++ b/src/hooks/pre-compact.ts
@@ -25,6 +25,19 @@ async function main() {
const sessionId = (data.session_id as string) || "unknown";
const project = (data.cwd as string) || process.cwd();
+ if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") {
+ try {
+ await fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {
+ method: "POST",
+ headers: authHeaders(),
+ body: JSON.stringify({}),
+ signal: AbortSignal.timeout(5000),
+ });
+ } catch {
+ // best-effort
+ }
+ }
+
try {
const res = await fetch(`${REST_URL}/agentmemory/context`, {
method: "POST",
diff --git a/src/hooks/session-end.ts b/src/hooks/session-end.ts
index d5f088d5..6ea0dffe 100644
--- a/src/hooks/session-end.ts
+++ b/src/hooks/session-end.ts
@@ -34,6 +34,18 @@ async function main() {
} catch {
// best-effort
}
+
+ if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") {
+ try {
+ await fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {
+ method: "POST",
+ headers: authHeaders(),
+ signal: AbortSignal.timeout(5000),
+ });
+ } catch {
+ // best-effort
+ }
+ }
}
main();
diff --git a/src/index.ts b/src/index.ts
index 8b085a44..6f7b36ee 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,6 +4,11 @@ import {
getEnvVar,
loadEmbeddingConfig,
loadFallbackConfig,
+ loadClaudeBridgeConfig,
+ loadTeamConfig,
+ loadSnapshotConfig,
+ isGraphExtractionEnabled,
+ isConsolidationEnabled,
} from "./config.js";
import {
createProvider,
@@ -37,6 +42,12 @@ import { registerProfileFunction } from "./functions/profile.js";
import { registerAutoForgetFunction } from "./functions/auto-forget.js";
import { registerExportImportFunction } from "./functions/export-import.js";
import { registerEnrichFunction } from "./functions/enrich.js";
+import { registerClaudeBridgeFunction } from "./functions/claude-bridge.js";
+import { registerGraphFunction } from "./functions/graph.js";
+import { registerConsolidationPipelineFunction } from "./functions/consolidation-pipeline.js";
+import { registerTeamFunction } from "./functions/team.js";
+import { registerGovernanceFunction } from "./functions/governance.js";
+import { registerSnapshotFunction } from "./functions/snapshot.js";
import { registerApiTriggers } from "./triggers/api.js";
import { registerEventTriggers } from "./triggers/events.js";
import { registerMcpEndpoints } from "./mcp/server.js";
@@ -116,6 +127,42 @@ async function main() {
registerExportImportFunction(sdk, kv);
registerEnrichFunction(sdk, kv);
+ const claudeBridgeConfig = loadClaudeBridgeConfig();
+ if (claudeBridgeConfig.enabled) {
+ registerClaudeBridgeFunction(sdk, kv, claudeBridgeConfig);
+ console.log(
+ `[agentmemory] Claude bridge: syncing to ${claudeBridgeConfig.memoryFilePath}`,
+ );
+ }
+
+ if (isGraphExtractionEnabled()) {
+ registerGraphFunction(sdk, kv, provider);
+ console.log(`[agentmemory] Knowledge graph: extraction enabled`);
+ }
+
+ if (isConsolidationEnabled()) {
+ registerConsolidationPipelineFunction(sdk, kv, provider);
+ console.log(`[agentmemory] Consolidation pipeline: enabled`);
+ }
+
+ const teamConfig = loadTeamConfig();
+ if (teamConfig) {
+ registerTeamFunction(sdk, kv, teamConfig);
+ console.log(
+ `[agentmemory] Team memory: ${teamConfig.teamId} (${teamConfig.mode})`,
+ );
+ }
+
+ registerGovernanceFunction(sdk, kv);
+
+ const snapshotConfig = loadSnapshotConfig();
+ if (snapshotConfig.enabled) {
+ registerSnapshotFunction(sdk, kv, snapshotConfig.dir);
+ console.log(
+ `[agentmemory] Git snapshots: ${snapshotConfig.dir} (every ${snapshotConfig.interval}s)`,
+ );
+ }
+
const bm25Index = getSearchIndex();
const hybridSearch = new HybridSearch(
bm25Index,
@@ -174,7 +221,7 @@ async function main() {
`[agentmemory] Ready. ${embeddingProvider ? "Hybrid" : "BM25"} search active.`,
);
console.log(
- `[agentmemory] Endpoints: 29 REST + 10 MCP tools + 4 MCP resources + 3 MCP prompts + 22 functions`,
+ `[agentmemory] Endpoints: 43 REST + 18 MCP tools + 6 MCP resources + 3 MCP prompts + 33 functions`,
);
const shutdown = async () => {
diff --git a/src/mcp/in-memory-kv.ts b/src/mcp/in-memory-kv.ts
new file mode 100644
index 00000000..36147597
--- /dev/null
+++ b/src/mcp/in-memory-kv.ts
@@ -0,0 +1,61 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export class InMemoryKV {
+ private store = new Map<string, Map<string, unknown>>();
+
+ constructor(private persistPath?: string) {
+ if (persistPath && existsSync(persistPath)) {
+ try {
+ const data = JSON.parse(readFileSync(persistPath, "utf-8"));
+ for (const [scope, entries] of Object.entries(data)) {
+ const map = new Map<string, unknown>();
+ for (const [key, value] of Object.entries(
+ entries as Record<string, unknown>,
+ )) {
+ map.set(key, value);
+ }
+ this.store.set(scope, map);
+ }
+ } catch {
+ // start fresh
+ }
+ }
+ }
+
+ async get<T = unknown>(scope: string, key: string): Promise<T | null> {
+ return (this.store.get(scope)?.get(key) as T) ?? null;
+ }
+
+ async set<T = unknown>(scope: string, key: string, data: T): Promise<T> {
+ if (!this.store.has(scope)) this.store.set(scope, new Map());
+ this.store.get(scope)!.set(key, data);
+ return data;
+ }
+
+ async delete(scope: string, key: string): Promise<void> {
+ this.store.get(scope)?.delete(key);
+ }
+
+ async list<T = unknown>(scope: string): Promise<T[]> {
+ const entries = this.store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ }
+
+ persist(): void {
+ if (!this.persistPath) return;
+ try {
+ const dir = dirname(this.persistPath);
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+ const data: Record<string, Record<string, unknown>> = {};
+ for (const [scope, entries] of this.store) {
+ data[scope] = Object.fromEntries(entries);
+ }
+ writeFileSync(this.persistPath, JSON.stringify(data), "utf-8");
+ } catch (err) {
+ process.stderr.write(
+ `[agentmemory-mcp] Persist failed: ${err instanceof Error ? err.message : String(err)}\n`,
+ );
+ }
+ }
+}
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 433a69dc..f4f365f5 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -5,18 +5,10 @@ import type {
SessionSummary,
Memory,
Session,
- MemoryRelation,
+ GraphNode,
+ GraphEdge,
} from "../types.js";
-
-type McpTool = {
- name: string;
- description: string;
- inputSchema: {
- type: "object";
- properties: Record<string, { type: string; description: string }>;
- required?: string[];
- };
-};
+import { getAllTools } from "./tools-registry.js";
type McpResponse = {
status_code: number;
@@ -24,203 +16,6 @@ type McpResponse = {
body: unknown;
};
-const MCP_TOOLS: McpTool[] = [
- {
- name: "memory_recall",
- description:
- "Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
- inputSchema: {
- type: "object",
- properties: {
- query: {
- type: "string",
- description: "Search query (keywords, file names, concepts)",
- },
- limit: {
- type: "number",
- description: "Max results to return (default 10)",
- },
- },
- required: ["query"],
- },
- },
- {
- name: "memory_save",
- description:
- "Explicitly save an important insight, decision, or pattern to long-term memory. Use when you discover something worth remembering for future sessions.",
- inputSchema: {
- type: "object",
- properties: {
- content: {
- type: "string",
- description: "The insight or decision to remember",
- },
- type: {
- type: "string",
- description:
- "Memory type: pattern, preference, architecture, bug, workflow, or fact",
- },
- concepts: {
- type: "string",
- description: "Comma-separated key concepts for searchability",
- },
- files: {
- type: "string",
- description: "Comma-separated relevant file paths",
- },
- },
- required: ["content"],
- },
- },
- {
- name: "memory_file_history",
- description:
- "Get past observations about specific files. Use before modifying a file to understand its history and past changes.",
- inputSchema: {
- type: "object",
- properties: {
- files: {
- type: "string",
- description: "Comma-separated file paths to look up",
- },
- sessionId: {
- type: "string",
- description: "Current session ID to exclude from results",
- },
- },
- required: ["files"],
- },
- },
- {
- name: "memory_patterns",
- description:
- "Detect recurring patterns across sessions: files that change together, repeated errors, common workflows.",
- inputSchema: {
- type: "object",
- properties: {
- project: {
- type: "string",
- description:
- "Project path to analyze (optional, analyzes all if omitted)",
- },
- },
- },
- },
- {
- name: "memory_sessions",
- description:
- "List recent sessions with their status and observation counts.",
- inputSchema: {
- type: "object",
- properties: {},
- },
- },
- {
- name: "memory_smart_search",
- description:
- "Hybrid semantic+keyword search with progressive disclosure. Returns compact summaries first; pass expandIds to get full observation text.",
- inputSchema: {
- type: "object",
- properties: {
- query: {
- type: "string",
- description: "Search query combining semantic and keyword matching",
- },
- expandIds: {
- type: "string",
- description:
- "Comma-separated observation IDs to expand with full text",
- },
- limit: {
- type: "number",
- description: "Max results to return (default 10)",
- },
- },
- required: ["query"],
- },
- },
- {
- name: "memory_timeline",
- description:
- "Chronological observations around an anchor point. Use to see what happened before and after a specific date or event.",
- inputSchema: {
- type: "object",
- properties: {
- anchor: {
- type: "string",
- description:
- "Anchor point: ISO date (e.g. 2026-02-15) or keyword (today, yesterday, last-week)",
- },
- project: {
- type: "string",
- description: "Filter by project path",
- },
- before: {
- type: "number",
- description: "Number of observations before anchor (default 5)",
- },
- after: {
- type: "number",
- description: "Number of observations after anchor (default 5)",
- },
- },
- required: ["anchor"],
- },
- },
- {
- name: "memory_profile",
- description:
- "User/project profile with top concepts, frequently modified files, and recurring patterns.",
- inputSchema: {
- type: "object",
- properties: {
- project: {
- type: "string",
- description: "Project path to build profile for",
- },
- refresh: {
- type: "string",
- description: "Set to 'true' to force rebuild the profile cache",
- },
- },
- required: ["project"],
- },
- },
- {
- name: "memory_export",
- description:
- "Export all memory data as JSON. Useful for backup or migration.",
- inputSchema: {
- type: "object",
- properties: {},
- },
- },
- {
- name: "memory_relations",
- description:
- "Query the memory relationship graph. Returns related memories within a given hop distance.",
- inputSchema: {
- type: "object",
- properties: {
- memoryId: {
- type: "string",
- description: "ID of the memory to find relations for",
- },
- maxHops: {
- type: "number",
- description: "Maximum graph traversal depth (default 2)",
- },
- minConfidence: {
- type: "number",
- description:
- "Minimum confidence threshold to include (0-1, default 0)",
- },
- },
- required: ["memoryId"],
- },
- },
-];
-
export function registerMcpEndpoints(
sdk: ISdk,
kv: StateKV,
@@ -244,7 +39,7 @@ export function registerMcpEndpoints(
async (req: ApiRequest): Promise<McpResponse> => {
const authErr = checkAuth(req, secret);
if (authErr) return authErr;
- return { status_code: 200, body: { tools: MCP_TOOLS } };
+ return { status_code: 200, body: { tools: getAllTools() } };
},
);
sdk.registerTrigger({
@@ -486,6 +281,250 @@ export function registerMcpEndpoints(
};
}
+ case "memory_claude_bridge_sync": {
+ const direction = (args.direction as string) || "write";
+ const funcId =
+ direction === "read"
+ ? "mem::claude-bridge-read"
+ : "mem::claude-bridge-sync";
+ try {
+ const result = await sdk.trigger(funcId, {});
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Claude bridge not enabled. Set CLAUDE_MEMORY_BRIDGE=true",
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ case "memory_graph_query": {
+ try {
+ const result = await sdk.trigger("mem::graph-query", {
+ startNodeId: args.startNodeId as string,
+ nodeType: args.nodeType as string,
+ maxDepth: args.maxDepth as number,
+ query: args.query as string,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Knowledge graph not enabled. Set GRAPH_EXTRACTION_ENABLED=true",
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ case "memory_consolidate": {
+ try {
+ const result = await sdk.trigger("mem::consolidate-pipeline", {
+ tier: args.tier as string,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Consolidation not enabled. Set CONSOLIDATION_ENABLED=true",
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ case "memory_team_share": {
+ if (
+ typeof args.itemId !== "string" ||
+ typeof args.itemType !== "string"
+ ) {
+ return {
+ status_code: 400,
+ body: { error: "itemId and itemType are required" },
+ };
+ }
+ try {
+ const result = await sdk.trigger("mem::team-share", {
+ itemId: args.itemId,
+ itemType: args.itemType,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Team memory not enabled. Set TEAM_ID and USER_ID",
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ case "memory_team_feed": {
+ try {
+ const result = await sdk.trigger("mem::team-feed", {
+ limit: (args.limit as number) || 20,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Team memory not enabled. Set TEAM_ID and USER_ID",
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ case "memory_audit": {
+ try {
+ const result = await sdk.trigger("mem::audit-query", {
+ operation: args.operation as string,
+ limit: (args.limit as number) || 50,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [{ type: "text", text: "Audit query failed" }],
+ isError: true,
+ },
+ };
+ }
+ }
+
+ case "memory_governance_delete": {
+ if (typeof args.memoryIds !== "string") {
+ return {
+ status_code: 400,
+ body: { error: "memoryIds is required" },
+ };
+ }
+ const ids = (args.memoryIds as string)
+ .split(",")
+ .map((id) => id.trim())
+ .filter(Boolean);
+ try {
+ const result = await sdk.trigger("mem::governance-delete", {
+ memoryIds: ids,
+ reason: args.reason as string,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [{ type: "text", text: "Governance delete failed" }],
+ isError: true,
+ },
+ };
+ }
+ }
+
+ case "memory_snapshot_create": {
+ try {
+ const result = await sdk.trigger("mem::snapshot-create", {
+ message: args.message as string,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ {
+ type: "text",
+ text: "Snapshots not enabled. Set SNAPSHOT_ENABLED=true",
+ },
+ ],
+ },
+ };
+ }
+ }
+
default:
return {
status_code: 400,
@@ -534,6 +573,18 @@ export function registerMcpEndpoints(
description: "Top 10 latest memories with their type and strength",
mimeType: "application/json",
},
+ {
+ uri: "agentmemory://graph/stats",
+ name: "Knowledge Graph Stats",
+ description: "Node and edge counts by type in the knowledge graph",
+ mimeType: "application/json",
+ },
+ {
+ uri: "agentmemory://team/{id}/profile",
+ name: "Team Profile",
+ description: "Team memory profile with shared concepts and patterns",
+ mimeType: "application/json",
+ },
];
sdk.registerFunction(
@@ -681,6 +732,93 @@ export function registerMcpEndpoints(
};
}
+ if (uri === "agentmemory://graph/stats") {
+ try {
+ const nodes = await kv.list<GraphNode>(KV.graphNodes);
+ const edges = await kv.list<GraphEdge>(KV.graphEdges);
+ const nodesByType: Record<string, number> = {};
+ for (const n of nodes)
+ nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
+ const edgesByType: Record<string, number> = {};
+ for (const e of edges)
+ edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+ return {
+ status_code: 200,
+ body: {
+ contents: [
+ {
+ uri,
+ mimeType: "application/json",
+ text: JSON.stringify({
+ totalNodes: nodes.length,
+ totalEdges: edges.length,
+ nodesByType,
+ edgesByType,
+ }),
+ },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ contents: [
+ {
+ uri,
+ mimeType: "application/json",
+ text: JSON.stringify({
+ totalNodes: 0,
+ totalEdges: 0,
+ }),
+ },
+ ],
+ },
+ };
+ }
+ }
+
+ const teamProfileMatch = uri.match(
+ /^agentmemory:\/\/team\/(.+)\/profile$/,
+ );
+ if (teamProfileMatch) {
+ try {
+ const teamId = decodeURIComponent(teamProfileMatch[1]);
+ const items = await kv.list(KV.teamShared(teamId));
+ return {
+ status_code: 200,
+ body: {
+ contents: [
+ {
+ uri,
+ mimeType: "application/json",
+ text: JSON.stringify({
+ teamId,
+ sharedItems: items.length,
+ }),
+ },
+ ],
+ },
+ };
+ } catch {
+ return {
+ status_code: 200,
+ body: {
+ contents: [
+ {
+ uri,
+ mimeType: "application/json",
+ text: JSON.stringify({
+ teamId: teamProfileMatch[1],
+ sharedItems: 0,
+ }),
+ },
+ ],
+ },
+ };
+ }
+ }
+
return {
status_code: 404,
body: { error: `Unknown resource: ${uri}` },
diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts
new file mode 100644
index 00000000..bb18db77
--- /dev/null
+++ b/src/mcp/standalone.ts
@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import { InMemoryKV } from "./in-memory-kv.js";
+import { createStdioTransport } from "./transport.js";
+import { getAllTools } from "./tools-registry.js";
+import { getStandalonePersistPath } from "../config.js";
+
+const SERVER_INFO = {
+ name: "agentmemory",
+ version: "0.4.0",
+ protocolVersion: "2024-11-05",
+};
+
+const kv = new InMemoryKV(getStandalonePersistPath());
+
+async function handleToolCall(
+ toolName: string,
+ args: Record<string, unknown>,
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+ switch (toolName) {
+ case "memory_save": {
+ const content = args.content as string;
+ if (!content?.trim()) throw new Error("content is required");
+ const id = `mem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+ await kv.set("mem:memories", id, {
+ id,
+ type: (args.type as string) || "fact",
+ title: content.slice(0, 80),
+ content,
+ concepts: args.concepts
+ ? (args.concepts as string).split(",").map((c) => c.trim())
+ : [],
+ files: args.files
+ ? (args.files as string).split(",").map((f) => f.trim())
+ : [],
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ strength: 7,
+ version: 1,
+ isLatest: true,
+ sessionIds: [],
+ });
+ return {
+ content: [{ type: "text", text: JSON.stringify({ saved: id }) }],
+ };
+ }
+
+ case "memory_recall": {
+ const query = (args.query as string)?.toLowerCase() || "";
+ const limit = (args.limit as number) || 10;
+ const all = await kv.list<Record<string, unknown>>("mem:memories");
+ const results = all
+ .filter((m) => {
+ const text = `${m.title} ${m.content}`.toLowerCase();
+ return text.includes(query);
+ })
+ .slice(0, limit);
+ return {
+ content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+ };
+ }
+
+ case "memory_sessions": {
+ const sessions = await kv.list("mem:sessions");
+ return {
+ content: [
+ { type: "text", text: JSON.stringify({ sessions }, null, 2) },
+ ],
+ };
+ }
+
+ case "memory_export": {
+ const memories = await kv.list("mem:memories");
+ const sessions = await kv.list("mem:sessions");
+ return {
+ content: [
+ {
+ type: "text",
+ text: JSON.stringify(
+ { version: "0.4.0", memories, sessions },
+ null,
+ 2,
+ ),
+ },
+ ],
+ };
+ }
+
+ case "memory_audit": {
+ const entries = await kv.list("mem:audit");
+ const limit = (args.limit as number) || 50;
+ return {
+ content: [
+ {
+ type: "text",
+ text: JSON.stringify(
+ (entries as Array<Record<string, unknown>>).slice(0, limit),
+ null,
+ 2,
+ ),
+ },
+ ],
+ };
+ }
+
+ default:
+ throw new Error(`Unknown tool: ${toolName}`);
+ }
+}
+
+const transport = createStdioTransport(async (method, params) => {
+ switch (method) {
+ case "initialize":
+ return {
+ protocolVersion: SERVER_INFO.protocolVersion,
+ capabilities: {
+ tools: { listChanged: false },
+ },
+ serverInfo: {
+ name: SERVER_INFO.name,
+ version: SERVER_INFO.version,
+ },
+ };
+
+ case "notifications/initialized":
+ return {};
+
+ case "tools/list":
+ return { tools: getAllTools() };
+
+ case "tools/call": {
+ const toolName = params.name as string;
+ const toolArgs = (params.arguments as Record<string, unknown>) || {};
+ try {
+ return await handleToolCall(toolName, toolArgs);
+ } catch (err) {
+ return {
+ content: [
+ {
+ type: "text",
+ text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+ },
+ ],
+ isError: true,
+ };
+ }
+ }
+
+ default:
+ throw new Error(`Unknown method: ${method}`);
+ }
+});
+
+process.stderr.write(
+ `[agentmemory-mcp] Standalone MCP server v${SERVER_INFO.version} starting...\n`,
+);
+transport.start();
+
+process.on("SIGINT", () => {
+ kv.persist();
+ process.exit(0);
+});
+process.on("SIGTERM", () => {
+ kv.persist();
+ process.exit(0);
+});
diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts
new file mode 100644
index 00000000..3f9f3b26
--- /dev/null
+++ b/src/mcp/tools-registry.ts
@@ -0,0 +1,291 @@
+export type McpToolDef = {
+ name: string;
+ description: string;
+ inputSchema: {
+ type: "object";
+ properties: Record<string, { type: string; description: string }>;
+ required?: string[];
+ };
+};
+
+export const CORE_TOOLS: McpToolDef[] = [
+ {
+ name: "memory_recall",
+ description:
+ "Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description: "Search query (keywords, file names, concepts)",
+ },
+ limit: {
+ type: "number",
+ description: "Max results to return (default 10)",
+ },
+ },
+ required: ["query"],
+ },
+ },
+ {
+ name: "memory_save",
+ description:
+ "Explicitly save an important insight, decision, or pattern to long-term memory.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ content: {
+ type: "string",
+ description: "The insight or decision to remember",
+ },
+ type: {
+ type: "string",
+ description:
+ "Memory type: pattern, preference, architecture, bug, workflow, or fact",
+ },
+ concepts: {
+ type: "string",
+ description: "Comma-separated key concepts",
+ },
+ files: {
+ type: "string",
+ description: "Comma-separated relevant file paths",
+ },
+ },
+ required: ["content"],
+ },
+ },
+ {
+ name: "memory_file_history",
+ description: "Get past observations about specific files.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ files: { type: "string", description: "Comma-separated file paths" },
+ sessionId: {
+ type: "string",
+ description: "Current session ID to exclude",
+ },
+ },
+ required: ["files"],
+ },
+ },
+ {
+ name: "memory_patterns",
+ description: "Detect recurring patterns across sessions.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ project: { type: "string", description: "Project path to analyze" },
+ },
+ },
+ },
+ {
+ name: "memory_sessions",
+ description:
+ "List recent sessions with their status and observation counts.",
+ inputSchema: { type: "object", properties: {} },
+ },
+ {
+ name: "memory_smart_search",
+ description: "Hybrid semantic+keyword search with progressive disclosure.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ query: { type: "string", description: "Search query" },
+ expandIds: {
+ type: "string",
+ description: "Comma-separated observation IDs to expand",
+ },
+ limit: { type: "number", description: "Max results (default 10)" },
+ },
+ required: ["query"],
+ },
+ },
+ {
+ name: "memory_timeline",
+ description: "Chronological observations around an anchor point.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ anchor: {
+ type: "string",
+ description: "Anchor point: ISO date or keyword",
+ },
+ project: { type: "string", description: "Filter by project path" },
+ before: {
+ type: "number",
+ description: "Observations before anchor (default 5)",
+ },
+ after: {
+ type: "number",
+ description: "Observations after anchor (default 5)",
+ },
+ },
+ required: ["anchor"],
+ },
+ },
+ {
+ name: "memory_profile",
+ description: "User/project profile with top concepts and file patterns.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ project: { type: "string", description: "Project path" },
+ refresh: {
+ type: "string",
+ description: "Set to 'true' to force rebuild",
+ },
+ },
+ required: ["project"],
+ },
+ },
+ {
+ name: "memory_export",
+ description: "Export all memory data as JSON.",
+ inputSchema: { type: "object", properties: {} },
+ },
+ {
+ name: "memory_relations",
+ description: "Query the memory relationship graph.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ memoryId: {
+ type: "string",
+ description: "Memory ID to find relations for",
+ },
+ maxHops: {
+ type: "number",
+ description: "Max traversal depth (default 2)",
+ },
+ minConfidence: {
+ type: "number",
+ description: "Min confidence (0-1, default 0)",
+ },
+ },
+ required: ["memoryId"],
+ },
+ },
+];
+
+export const V040_TOOLS: McpToolDef[] = [
+ {
+ name: "memory_claude_bridge_sync",
+ description:
+ "Sync memory state to/from Claude Code's native MEMORY.md file.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ direction: {
+ type: "string",
+ description:
+ "'read' to import from MEMORY.md, 'write' to export to MEMORY.md",
+ },
+ },
+ required: ["direction"],
+ },
+ },
+ {
+ name: "memory_graph_query",
+ description: "Query the knowledge graph for entities and relationships.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ startNodeId: {
+ type: "string",
+ description: "Starting node ID for traversal",
+ },
+ nodeType: { type: "string", description: "Filter by node type" },
+ maxDepth: {
+ type: "number",
+ description: "Max BFS depth (default 3, max 5)",
+ },
+ query: { type: "string", description: "Search nodes by name" },
+ },
+ },
+ },
+ {
+ name: "memory_consolidate",
+ description:
+ "Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural).",
+ inputSchema: {
+ type: "object",
+ properties: {
+ tier: {
+ type: "string",
+ description: "Target tier: episodic, semantic, or procedural",
+ },
+ },
+ },
+ },
+ {
+ name: "memory_team_share",
+ description: "Share a memory or observation with team members.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ itemId: {
+ type: "string",
+ description: "ID of memory or observation to share",
+ },
+ itemType: {
+ type: "string",
+ description: "Type: observation, memory, or pattern",
+ },
+ },
+ required: ["itemId", "itemType"],
+ },
+ },
+ {
+ name: "memory_team_feed",
+ description: "Get recent shared items from all team members.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ limit: { type: "number", description: "Max items (default 20)" },
+ },
+ },
+ },
+ {
+ name: "memory_audit",
+ description: "View the audit trail of memory operations.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: { type: "string", description: "Filter by operation type" },
+ limit: { type: "number", description: "Max entries (default 50)" },
+ },
+ },
+ },
+ {
+ name: "memory_governance_delete",
+ description: "Delete specific memories with audit trail.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ memoryIds: {
+ type: "string",
+ description: "Comma-separated memory IDs to delete",
+ },
+ reason: { type: "string", description: "Reason for deletion" },
+ },
+ required: ["memoryIds"],
+ },
+ },
+ {
+ name: "memory_snapshot_create",
+ description: "Create a git-versioned snapshot of current memory state.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ message: { type: "string", description: "Snapshot description" },
+ },
+ },
+ },
+];
+
+export function getAllTools(): McpToolDef[] {
+ return [...CORE_TOOLS, ...V040_TOOLS];
+}
diff --git a/src/mcp/transport.ts b/src/mcp/transport.ts
new file mode 100644
index 00000000..4dac9d73
--- /dev/null
+++ b/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;
+ },
+ };
+}
diff --git a/src/prompts/consolidation.ts b/src/prompts/consolidation.ts
new file mode 100644
index 00000000..76580b8a
--- /dev/null
+++ b/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}`;
+}
diff --git a/src/prompts/graph-extraction.ts b/src/prompts/graph-extraction.ts
new file mode 100644
index 00000000..4f1049c1
--- /dev/null
+++ b/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}`;
+}
diff --git a/src/state/schema.ts b/src/state/schema.ts
index 344739c9..6d68d504 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -10,6 +10,16 @@ export const KV = {
bm25Index: "mem:index:bm25",
relations: "mem:relations",
profiles: "mem:profiles",
+ claudeBridge: "mem:claude-bridge",
+ graphNodes: "mem:graph:nodes",
+ graphEdges: "mem:graph:edges",
+ semantic: "mem:semantic",
+ procedural: "mem:procedural",
+ teamShared: (teamId: string) => `mem:team:${teamId}:shared`,
+ teamUsers: (teamId: string, userId: string) =>
+ `mem:team:${teamId}:users:${userId}`,
+ teamProfile: (teamId: string) => `mem:team:${teamId}:profile`,
+ audit: "mem:audit",
} as const;
export const STREAM = {
diff --git a/src/telemetry/setup.ts b/src/telemetry/setup.ts
index e88dbfb2..bfa37d3a 100644
--- a/src/telemetry/setup.ts
+++ b/src/telemetry/setup.ts
@@ -6,7 +6,7 @@ interface OtelConfig {
export const OTEL_CONFIG: OtelConfig = {
serviceName: "agentmemory",
- serviceVersion: "0.3.0",
+ serviceVersion: "0.4.0",
metricsExportIntervalMs: 30_000,
};
@@ -30,6 +30,13 @@ interface Counters {
vectorSearchTotal: Counter;
autoForgetTotal: Counter;
profileGenerated: Counter;
+ claudeBridgeSync: Counter;
+ graphExtraction: Counter;
+ consolidationRun: Counter;
+ teamShare: Counter;
+ auditLog: Counter;
+ snapshotCreate: Counter;
+ governanceDelete: Counter;
}
interface Histograms {
@@ -65,6 +72,13 @@ const COUNTER_NAMES: Array<[keyof Counters, string]> = [
["vectorSearchTotal", "vector_search.total"],
["autoForgetTotal", "auto_forget.total"],
["profileGenerated", "profile.generated"],
+ ["claudeBridgeSync", "claude_bridge.sync"],
+ ["graphExtraction", "graph.extraction"],
+ ["consolidationRun", "consolidation.run"],
+ ["teamShare", "team.share"],
+ ["auditLog", "audit.log"],
+ ["snapshotCreate", "snapshot.create"],
+ ["governanceDelete", "governance.delete"],
];
const HISTOGRAM_NAMES: Array<[keyof Histograms, string]> = [
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 2bdd1cbf..9ec0d412 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -616,6 +616,362 @@ export function registerApiTriggers(
config: { api_path: "/agentmemory/auto-forget", http_method: "POST" },
});
+ sdk.registerFunction(
+ { id: "api::claude-bridge-read" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::claude-bridge-read", {});
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Claude bridge not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::claude-bridge-read",
+ config: { api_path: "/agentmemory/claude-bridge/read", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::claude-bridge-sync" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::claude-bridge-sync", {});
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Claude bridge not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::claude-bridge-sync",
+ config: {
+ api_path: "/agentmemory/claude-bridge/sync",
+ http_method: "POST",
+ },
+ });
+
+ sdk.registerFunction(
+ { id: "api::graph-query" },
+ async (
+ req: ApiRequest<{
+ startNodeId?: string;
+ nodeType?: string;
+ maxDepth?: number;
+ query?: string;
+ }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::graph-query", req.body || {});
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Knowledge graph not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::graph-query",
+ config: { api_path: "/agentmemory/graph/query", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::graph-stats" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::graph-stats", {});
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Knowledge graph not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::graph-stats",
+ config: { api_path: "/agentmemory/graph/stats", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::graph-extract" },
+ async (req: ApiRequest<{ observations: unknown[] }>): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (
+ !Array.isArray(req.body?.observations) ||
+ req.body.observations.length === 0
+ ) {
+ return {
+ status_code: 400,
+ body: { error: "observations array is required" },
+ };
+ }
+ try {
+ const result = await sdk.trigger("mem::graph-extract", req.body);
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Knowledge graph not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::graph-extract",
+ config: { api_path: "/agentmemory/graph/extract", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::consolidate-pipeline" },
+ async (req: ApiRequest<{ tier?: string }>): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger(
+ "mem::consolidate-pipeline",
+ req.body || {},
+ );
+ return { status_code: 200, body: result };
+ } catch {
+ return {
+ status_code: 404,
+ body: { error: "Consolidation pipeline not enabled" },
+ };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::consolidate-pipeline",
+ config: {
+ api_path: "/agentmemory/consolidate-pipeline",
+ http_method: "POST",
+ },
+ });
+
+ sdk.registerFunction(
+ { id: "api::team-share" },
+ async (
+ req: ApiRequest<{ itemId: string; itemType: string; project?: string }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.itemId || !req.body?.itemType) {
+ return {
+ status_code: 400,
+ body: { error: "itemId and itemType are required" },
+ };
+ }
+ try {
+ const result = await sdk.trigger("mem::team-share", req.body);
+ return { status_code: 201, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Team memory not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::team-share",
+ config: { api_path: "/agentmemory/team/share", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::team-feed" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const limit = parseInt(req.query_params?.["limit"] as string) || 20;
+ const result = await sdk.trigger("mem::team-feed", { limit });
+ return { status_code: 200, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Team memory not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::team-feed",
+ config: { api_path: "/agentmemory/team/feed", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::team-profile" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::team-profile", {});
+ return { status_code: 200, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Team memory not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::team-profile",
+ config: { api_path: "/agentmemory/team/profile", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::audit" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ const result = await sdk.trigger("mem::audit-query", {
+ operation: req.query_params?.["operation"],
+ limit: parseInt(req.query_params?.["limit"] as string) || 50,
+ });
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::audit",
+ config: { api_path: "/agentmemory/audit", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::governance-delete" },
+ async (
+ req: ApiRequest<{ memoryIds: string[]; reason?: string }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.memoryIds || !Array.isArray(req.body.memoryIds)) {
+ return {
+ status_code: 400,
+ body: { error: "memoryIds array is required" },
+ };
+ }
+ const result = await sdk.trigger("mem::governance-delete", req.body);
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::governance-delete",
+ config: {
+ api_path: "/agentmemory/governance/memories",
+ http_method: "DELETE",
+ },
+ });
+
+ sdk.registerFunction(
+ { id: "api::governance-bulk" },
+ async (
+ req: ApiRequest<{
+ type?: string[];
+ dateFrom?: string;
+ dateTo?: string;
+ qualityBelow?: number;
+ dryRun?: boolean;
+ }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ const result = await sdk.trigger("mem::governance-bulk", req.body || {});
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::governance-bulk",
+ config: {
+ api_path: "/agentmemory/governance/bulk-delete",
+ http_method: "POST",
+ },
+ });
+
+ sdk.registerFunction(
+ { id: "api::snapshots" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger("mem::snapshot-list", {});
+ return { status_code: 200, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Snapshots not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::snapshots",
+ config: { api_path: "/agentmemory/snapshots", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::snapshot-create" },
+ async (req: ApiRequest<{ message?: string }>): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger(
+ "mem::snapshot-create",
+ req.body || {},
+ );
+ return { status_code: 201, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Snapshots not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::snapshot-create",
+ config: { api_path: "/agentmemory/snapshot/create", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::snapshot-restore" },
+ async (req: ApiRequest<{ commitHash: string }>): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.commitHash) {
+ return { status_code: 400, body: { error: "commitHash is required" } };
+ }
+ try {
+ const result = await sdk.trigger("mem::snapshot-restore", req.body);
+ return { status_code: 200, body: result };
+ } catch {
+ return { status_code: 404, body: { error: "Snapshots not enabled" } };
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::snapshot-restore",
+ config: { api_path: "/agentmemory/snapshot/restore", http_method: "POST" },
+ });
+
sdk.registerFunction({ id: "api::viewer" }, async (): Promise<Response> => {
const headers = {
"Content-Type": "text/html",
diff --git a/src/types.ts b/src/types.ts
index f9ce7bc9..ee7c5af8 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -237,13 +237,17 @@ export interface ProjectProfile {
}
export interface ExportData {
- version: "0.3.0";
+ version: "0.3.0" | "0.4.0";
exportedAt: string;
sessions: Session[];
observations: Record<string, CompressedObservation[]>;
memories: Memory[];
summaries: SessionSummary[];
profiles?: ProjectProfile[];
+ graphNodes?: GraphNode[];
+ graphEdges?: GraphEdge[];
+ semanticMemories?: SemanticMemory[];
+ proceduralMemories?: ProceduralMemory[];
}
export interface EmbeddingConfig {
@@ -255,3 +259,162 @@ export interface EmbeddingConfig {
export interface FallbackConfig {
providers: ProviderType[];
}
+
+export interface ClaudeBridgeConfig {
+ enabled: boolean;
+ projectPath: string;
+ memoryFilePath: string;
+ lineBudget: number;
+}
+
+export interface StandaloneConfig {
+ dataDir: string;
+ persistPath: string;
+ agentType?: string;
+}
+
+export interface GraphNode {
+ id: string;
+ type:
+ | "file"
+ | "function"
+ | "concept"
+ | "error"
+ | "decision"
+ | "pattern"
+ | "library"
+ | "person";
+ name: string;
+ properties: Record<string, string>;
+ sourceObservationIds: string[];
+ createdAt: string;
+}
+
+export interface GraphEdge {
+ id: string;
+ type:
+ | "uses"
+ | "imports"
+ | "modifies"
+ | "causes"
+ | "fixes"
+ | "depends_on"
+ | "related_to";
+ sourceNodeId: string;
+ targetNodeId: string;
+ weight: number;
+ sourceObservationIds: string[];
+ createdAt: string;
+}
+
+export interface GraphQueryResult {
+ nodes: GraphNode[];
+ edges: GraphEdge[];
+ depth: number;
+}
+
+export type ConsolidationTier =
+ | "working"
+ | "episodic"
+ | "semantic"
+ | "procedural";
+
+export interface SemanticMemory {
+ id: string;
+ fact: string;
+ confidence: number;
+ sourceSessionIds: string[];
+ sourceMemoryIds: string[];
+ accessCount: number;
+ lastAccessedAt: string;
+ strength: number;
+ createdAt: string;
+ updatedAt: string;
+}
+
+export interface ProceduralMemory {
+ id: string;
+ name: string;
+ steps: string[];
+ triggerCondition: string;
+ frequency: number;
+ sourceSessionIds: string[];
+ strength: number;
+ createdAt: string;
+ updatedAt: string;
+}
+
+export interface TeamConfig {
+ teamId: string;
+ userId: string;
+ mode: "shared" | "private";
+}
+
+export interface TeamSharedItem {
+ id: string;
+ sharedBy: string;
+ sharedAt: string;
+ type: "observation" | "memory" | "pattern";
+ content: unknown;
+ project: string;
+ visibility: "shared" | "private";
+}
+
+export interface TeamProfile {
+ teamId: string;
+ members: string[];
+ topConcepts: Array<{ concept: string; frequency: number }>;
+ topFiles: Array<{ file: string; frequency: number }>;
+ sharedPatterns: string[];
+ totalSharedItems: number;
+ updatedAt: string;
+}
+
+export interface AuditEntry {
+ id: string;
+ timestamp: string;
+ operation:
+ | "observe"
+ | "compress"
+ | "remember"
+ | "forget"
+ | "evolve"
+ | "consolidate"
+ | "share"
+ | "delete"
+ | "import"
+ | "export";
+ userId?: string;
+ functionId: string;
+ targetIds: string[];
+ details: Record<string, unknown>;
+ qualityScore?: number;
+}
+
+export interface GovernanceFilter {
+ type?: string[];
+ dateFrom?: string;
+ dateTo?: string;
+ project?: string;
+ qualityBelow?: number;
+}
+
+export interface SnapshotMeta {
+ id: string;
+ commitHash: string;
+ createdAt: string;
+ message: string;
+ stats: {
+ sessions: number;
+ observations: number;
+ memories: number;
+ graphNodes: number;
+ };
+}
+
+export interface SnapshotDiff {
+ fromCommit: string;
+ toCommit: string;
+ added: { memories: number; observations: number; graphNodes: number };
+ removed: { memories: number; observations: number; graphNodes: number };
+}
diff --git a/test/audit.test.ts b/test/audit.test.ts
new file mode 100644
index 00000000..12c1970c
--- /dev/null
+++ b/test/audit.test.ts
@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { recordAudit, queryAudit } from "../src/functions/audit.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+describe("Audit Functions", () => {
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ kv = mockKV();
+ });
+
+ it("recordAudit creates an entry with proper fields", async () => {
+ const entry = await recordAudit(
+ kv as never,
+ "observe",
+ "mem::compress",
+ ["obs_1", "obs_2"],
+ { count: 2 },
+ 0.85,
+ "user-1",
+ );
+
+ expect(entry.id).toMatch(/^aud_/);
+ expect(entry.timestamp).toBeDefined();
+ expect(entry.operation).toBe("observe");
+ expect(entry.functionId).toBe("mem::compress");
+ expect(entry.targetIds).toEqual(["obs_1", "obs_2"]);
+ expect(entry.details).toEqual({ count: 2 });
+ expect(entry.qualityScore).toBe(0.85);
+ expect(entry.userId).toBe("user-1");
+ });
+
+ it("queryAudit returns entries sorted by timestamp desc", async () => {
+ await recordAudit(kv as never, "observe", "fn1", ["a"], {});
+ await new Promise((r) => setTimeout(r, 10));
+ await recordAudit(kv as never, "delete", "fn2", ["b"], {});
+
+ const entries = await queryAudit(kv as never);
+ expect(entries.length).toBe(2);
+ expect(
+ new Date(entries[0].timestamp).getTime(),
+ ).toBeGreaterThanOrEqual(new Date(entries[1].timestamp).getTime());
+ });
+
+ it("queryAudit filters by operation", async () => {
+ await recordAudit(kv as never, "observe", "fn1", [], {});
+ await recordAudit(kv as never, "delete", "fn2", [], {});
+ await recordAudit(kv as never, "observe", "fn3", [], {});
+
+ const entries = await queryAudit(kv as never, { operation: "observe" });
+ expect(entries.length).toBe(2);
+ expect(entries.every((e) => e.operation === "observe")).toBe(true);
+ });
+
+ it("queryAudit filters by dateFrom/dateTo", async () => {
+ const early = await recordAudit(kv as never, "observe", "fn1", [], {});
+ await new Promise((r) => setTimeout(r, 20));
+ const late = await recordAudit(kv as never, "delete", "fn2", [], {});
+
+ const entries = await queryAudit(kv as never, {
+ dateFrom: late.timestamp,
+ });
+ expect(entries.length).toBe(1);
+ expect(entries[0].operation).toBe("delete");
+
+ const entriesBefore = await queryAudit(kv as never, {
+ dateTo: early.timestamp,
+ });
+ expect(entriesBefore.length).toBe(1);
+ expect(entriesBefore[0].operation).toBe("observe");
+ });
+
+ it("queryAudit respects limit", async () => {
+ for (let i = 0; i < 10; i++) {
+ await recordAudit(kv as never, "observe", `fn${i}`, [], {});
+ }
+
+ const entries = await queryAudit(kv as never, { limit: 3 });
+ expect(entries.length).toBe(3);
+ });
+});
diff --git a/test/claude-bridge.test.ts b/test/claude-bridge.test.ts
new file mode 100644
index 00000000..3edc2a0c
--- /dev/null
+++ b/test/claude-bridge.test.ts
@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+vi.mock("node:fs", () => ({
+ existsSync: vi.fn(),
+ readFileSync: vi.fn(),
+ writeFileSync: vi.fn(),
+ mkdirSync: vi.fn(),
+}));
+
+vi.mock("node:path", async () => ({
+ ...(await vi.importActual("node:path")),
+ dirname: vi.fn().mockReturnValue("/tmp"),
+}));
+
+import { registerClaudeBridgeFunction } from "../src/functions/claude-bridge.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { ClaudeBridgeConfig, Memory } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+const enabledConfig: ClaudeBridgeConfig = {
+ enabled: true,
+ projectPath: "/tmp/my-project",
+ memoryFilePath: "/tmp/.claude/MEMORY.md",
+ lineBudget: 200,
+};
+
+const disabledConfig: ClaudeBridgeConfig = {
+ enabled: false,
+ projectPath: "",
+ memoryFilePath: "",
+ lineBudget: 200,
+};
+
+describe("Claude Bridge Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ kv = mockKV();
+ vi.clearAllMocks();
+ });
+
+ it("claude-bridge-read returns content when file exists", async () => {
+ registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
+
+ vi.mocked(existsSync).mockReturnValue(true);
+ vi.mocked(readFileSync).mockReturnValue(
+ "# Memory\n\n## Project Summary\nA test project\n\n## Key Memories\nSome memories",
+ );
+
+ const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
+ success: boolean;
+ content: string;
+ sections: Record<string, string>;
+ };
+
+ expect(result.success).toBe(true);
+ expect(result.content).toContain("# Memory");
+ expect(result.sections).toBeDefined();
+ expect(result.sections["Project Summary"]).toBe("A test project");
+ });
+
+ it("claude-bridge-read returns empty when file does not exist", async () => {
+ registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
+
+ vi.mocked(existsSync).mockReturnValue(false);
+
+ const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
+ success: boolean;
+ content: string;
+ parsed: boolean;
+ };
+
+ expect(result.success).toBe(true);
+ expect(result.content).toBe("");
+ expect(result.parsed).toBe(false);
+ });
+
+ it("claude-bridge-sync writes MEMORY.md with memories", async () => {
+ registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
+
+ const mem: Memory = {
+ id: "mem_1",
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type: "pattern",
+ title: "Auth pattern",
+ content: "Always validate tokens",
+ concepts: ["auth"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ };
+ await kv.set("mem:memories", "mem_1", mem);
+
+ vi.mocked(existsSync).mockReturnValue(true);
+
+ const result = (await sdk.trigger("mem::claude-bridge-sync", {})) as {
+ success: boolean;
+ path: string;
+ lines: number;
+ };
+
+ expect(result.success).toBe(true);
+ expect(result.path).toBe("/tmp/.claude/MEMORY.md");
+ expect(writeFileSync).toHaveBeenCalled();
+ const writtenContent = vi.mocked(writeFileSync).mock.calls[0][1] as string;
+ expect(writtenContent).toContain("Auth pattern");
+ });
+
+ it("claude-bridge-sync returns error when not configured", async () => {
+ registerClaudeBridgeFunction(sdk as never, kv as never, disabledConfig);
+
+ const result = (await sdk.trigger("mem::claude-bridge-sync", {})) as {
+ success: boolean;
+ error: string;
+ };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("not configured");
+ });
+
+ it("claude-bridge-read returns error when not configured", async () => {
+ registerClaudeBridgeFunction(sdk as never, kv as never, disabledConfig);
+
+ const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
+ success: boolean;
+ error: string;
+ };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("not configured");
+ });
+});
diff --git a/test/consolidation-pipeline.test.ts b/test/consolidation-pipeline.test.ts
new file mode 100644
index 00000000..46cab447
--- /dev/null
+++ b/test/consolidation-pipeline.test.ts
@@ -0,0 +1,209 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+vi.mock("../src/config.js", () => ({
+ getConsolidationDecayDays: () => 30,
+}));
+
+import { registerConsolidationPipelineFunction } from "../src/functions/consolidation-pipeline.js";
+import type { SessionSummary, Memory, SemanticMemory, ProceduralMemory } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+function makeSummary(i: number): SessionSummary {
+ return {
+ sessionId: `ses_${i}`,
+ project: "test-project",
+ createdAt: new Date(Date.now() - i * 86400000).toISOString(),
+ title: `Session ${i} summary`,
+ narrative: `Worked on feature ${i}`,
+ keyDecisions: [`Decision ${i}`],
+ filesModified: [`src/file${i}.ts`],
+ concepts: ["typescript", "testing"],
+ observationCount: 5,
+ };
+}
+
+function makePattern(i: number): Memory {
+ return {
+ id: `mem_${i}`,
+ createdAt: "2026-01-01T00:00:00Z",
+ updatedAt: "2026-01-01T00:00:00Z",
+ type: "pattern",
+ title: `Pattern ${i}`,
+ content: `Always do thing ${i}`,
+ concepts: ["testing"],
+ files: [],
+ sessionIds: ["ses_1", "ses_2"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ };
+}
+
+describe("Consolidation Pipeline", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ kv = mockKV();
+ });
+
+ it("pipeline skips semantic when fewer than 5 summaries", async () => {
+ const provider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn(),
+ };
+ registerConsolidationPipelineFunction(sdk as never, kv as never, provider as never);
+
+ for (let i = 0; i < 3; i++) {
+ await kv.set("mem:summaries", `ses_${i}`, makeSummary(i));
+ }
+
+ const result = (await sdk.trigger("mem::consolidate-pipeline", {
+ tier: "semantic",
+ })) as { success: boolean; results: Record<string, unknown> };
+
+ expect(result.success).toBe(true);
+ const semantic = result.results.semantic as { skipped: boolean; reason: string };
+ expect(semantic.skipped).toBe(true);
+ expect(semantic.reason).toContain("fewer than 5");
+ expect(provider.summarize).not.toHaveBeenCalled();
+ });
+
+ it("pipeline skips procedural when fewer than 2 patterns", async () => {
+ const provider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn(),
+ };
+ registerConsolidationPipelineFunction(sdk as never, kv as never, provider as never);
+
+ const mem: Memory = {
+ ...makePattern(1),
+ sessionIds: ["ses_1", "ses_2"],
+ };
+ await kv.set("mem:memories", "mem_1", mem);
+
+ const result = (await sdk.trigger("mem::consolidate-pipeline", {
+ tier: "procedural",
+ })) as { success: boolean; results: Record<string, unknown> };
+
+ expect(result.success).toBe(true);
+ const procedural = result.results.procedural as { skipped: boolean; reason: string };
+ expect(procedural.skipped).toBe(true);
+ expect(procedural.reason).toContain("fewer than 2");
+ });
+
+ it("with enough summaries, creates semantic memories from provider response", async () => {
+ const provider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn().mockResolvedValue(
+ `<facts><fact confidence="0.9">TypeScript is the primary language</fact></facts>`,
+ ),
+ };
+ registerConsolidationPipelineFunction(sdk as never, kv as never, provider as never);
+
+ for (let i = 0; i < 6; i++) {
+ await kv.set("mem:summaries", `ses_${i}`, makeSummary(i));
+ }
+
+ const result = (await sdk.trigger("mem::consolidate-pipeline", {
+ tier: "semantic",
+ })) as { success: boolean; results: Record<string, unknown> };
+
+ expect(result.success).toBe(true);
+ const semantic = result.results.semantic as { newFacts: number };
+ expect(semantic.newFacts).toBe(1);
+
+ const stored = await kv.list<SemanticMemory>("mem:semantic");
+ expect(stored.length).toBe(1);
+ expect(stored[0].fact).toBe("TypeScript is the primary language");
+ expect(stored[0].confidence).toBe(0.9);
+ });
+
+ it("with enough patterns, creates procedural memories from provider response", async () => {
+ const provider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn().mockResolvedValue(
+ `<procedures><procedure name="Test Workflow" trigger="when writing tests"><step>Create test file</step><step>Write assertions</step></procedure></procedures>`,
+ ),
+ };
+ registerConsolidationPipelineFunction(sdk as never, kv as never, provider as never);
+
+ for (let i = 0; i < 3; i++) {
+ await kv.set("mem:memories", `mem_${i}`, makePattern(i));
+ }
+
+ const result = (await sdk.trigger("mem::consolidate-pipeline", {
+ tier: "procedural",
+ })) as { success: boolean; results: Record<string, unknown> };
+
+ expect(result.success).toBe(true);
+ const procedural = result.results.procedural as { newProcedures: number };
+ expect(procedural.newProcedures).toBe(1);
+
+ const stored = await kv.list<ProceduralMemory>("mem:procedural");
+ expect(stored.length).toBe(1);
+ expect(stored[0].name).toBe("Test Workflow");
+ expect(stored[0].steps.length).toBe(2);
+ expect(stored[0].triggerCondition).toBe("when writing tests");
+ });
+
+ it("consolidation records an audit entry", async () => {
+ const provider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn(),
+ };
+ registerConsolidationPipelineFunction(sdk as never, kv as never, provider as never);
+
+ await sdk.trigger("mem::consolidate-pipeline", { tier: "semantic" });
+
+ const audits = await kv.list("mem:audit");
+ expect(audits.length).toBe(1);
+ });
+});
diff --git a/test/export-import.test.ts b/test/export-import.test.ts
index 4fb2a41c..f3aa3ce2 100644
--- a/test/export-import.test.ts
+++ b/test/export-import.test.ts
@@ -118,7 +118,7 @@ describe("Export/Import Functions", () => {
it("export produces valid ExportData structure", async () => {
const result = (await sdk.trigger("mem::export", {})) as ExportData;
- expect(result.version).toBe("0.3.0");
+ expect(result.version).toBe("0.4.0");
expect(result.exportedAt).toBeDefined();
expect(result.sessions.length).toBe(1);
expect(result.sessions[0].id).toBe("ses_1");
@@ -131,13 +131,9 @@ describe("Export/Import Functions", () => {
const exportData: ExportData = {
version: "0.3.0",
exportedAt: new Date().toISOString(),
- sessions: [
- { ...testSession, id: "ses_2", observationCount: 0 },
- ],
+ sessions: [{ ...testSession, id: "ses_2", observationCount: 0 }],
observations: {},
- memories: [
- { ...testMemory, id: "mem_2", title: "New pattern" },
- ],
+ memories: [{ ...testMemory, id: "mem_2", title: "New pattern" }],
summaries: [],
};
@@ -214,14 +210,22 @@ describe("Export/Import Functions", () => {
const importResult = (await freshSdk.trigger("mem::import", {
exportData: exported,
strategy: "merge",
- })) as { success: boolean; sessions: number; observations: number; memories: number };
+ })) as {
+ success: boolean;
+ sessions: number;
+ observations: number;
+ memories: number;
+ };
expect(importResult.success).toBe(true);
expect(importResult.sessions).toBe(1);
expect(importResult.observations).toBe(1);
expect(importResult.memories).toBe(1);
- const reExported = (await freshSdk.trigger("mem::export", {})) as ExportData;
+ const reExported = (await freshSdk.trigger(
+ "mem::export",
+ {},
+ )) as ExportData;
expect(reExported.sessions.length).toBe(exported.sessions.length);
expect(reExported.memories.length).toBe(exported.memories.length);
});
diff --git a/test/governance.test.ts b/test/governance.test.ts
new file mode 100644
index 00000000..f725fd19
--- /dev/null
+++ b/test/governance.test.ts
@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerGovernanceFunction } from "../src/functions/governance.js";
+import type { Memory, AuditEntry } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+function makeMemory(id: string, type: Memory["type"] = "pattern"): Memory {
+ return {
+ id,
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type,
+ title: `Memory ${id}`,
+ content: `Content for ${id}`,
+ concepts: ["test"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ };
+}
+
+describe("Governance Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerGovernanceFunction(sdk as never, kv as never);
+
+ await kv.set("mem:memories", "mem_1", makeMemory("mem_1", "pattern"));
+ await kv.set("mem:memories", "mem_2", makeMemory("mem_2", "bug"));
+ await kv.set("mem:memories", "mem_3", makeMemory("mem_3", "pattern"));
+ });
+
+ it("governance-delete removes specified memories", async () => {
+ const result = (await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["mem_1"],
+ reason: "outdated",
+ })) as { success: boolean; deleted: number; total: number };
+
+ expect(result.success).toBe(true);
+ expect(result.deleted).toBe(1);
+ expect(result.total).toBe(1);
+
+ const remaining = await kv.list("mem:memories");
+ expect(remaining.length).toBe(2);
+ });
+
+ it("governance-delete handles non-existent IDs gracefully", async () => {
+ const result = (await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["nonexistent_1", "nonexistent_2"],
+ })) as { success: boolean; deleted: number; total: number };
+
+ expect(result.success).toBe(true);
+ expect(result.deleted).toBe(0);
+ expect(result.total).toBe(2);
+
+ const remaining = await kv.list("mem:memories");
+ expect(remaining.length).toBe(3);
+ });
+
+ it("governance-bulk deletes by type filter", async () => {
+ const result = (await sdk.trigger("mem::governance-bulk", {
+ type: ["pattern"],
+ })) as { success: boolean; deleted: number };
+
+ expect(result.success).toBe(true);
+ expect(result.deleted).toBe(2);
+
+ const remaining = await kv.list<Memory>("mem:memories");
+ expect(remaining.length).toBe(1);
+ expect(remaining[0].type).toBe("bug");
+ });
+
+ it("governance-bulk respects dryRun", async () => {
+ const result = (await sdk.trigger("mem::governance-bulk", {
+ type: ["pattern"],
+ dryRun: true,
+ })) as { success: boolean; dryRun: boolean; wouldDelete: number; ids: string[] };
+
+ expect(result.success).toBe(true);
+ expect(result.dryRun).toBe(true);
+ expect(result.wouldDelete).toBe(2);
+ expect(result.ids).toContain("mem_1");
+ expect(result.ids).toContain("mem_3");
+
+ const remaining = await kv.list("mem:memories");
+ expect(remaining.length).toBe(3);
+ });
+
+ it("audit-query returns audit entries", async () => {
+ await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["mem_1"],
+ reason: "cleanup",
+ });
+
+ const entries = (await sdk.trigger("mem::audit-query", {})) as AuditEntry[];
+
+ expect(entries.length).toBe(1);
+ expect(entries[0].operation).toBe("delete");
+ expect(entries[0].functionId).toBe("mem::governance-delete");
+ });
+});
diff --git a/test/graph.test.ts b/test/graph.test.ts
new file mode 100644
index 00000000..661cbc14
--- /dev/null
+++ b/test/graph.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerGraphFunction } from "../src/functions/graph.js";
+import type {
+ CompressedObservation,
+ GraphNode,
+ GraphEdge,
+ GraphQueryResult,
+} from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+const mockProvider = {
+ name: "test",
+ compress: vi.fn().mockResolvedValue(`<entities>
+<entity type="file" name="src/index.ts"><property key="path">src/index.ts</property></entity>
+<entity type="function" name="main"><property key="lang">typescript</property></entity>
+</entities>
+<relationships>
+<relationship type="uses" source="src/index.ts" target="main" weight="0.9"/>
+</relationships>`),
+ summarize: vi.fn(),
+};
+
+const testObs: CompressedObservation = {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T10:00:00Z",
+ type: "file_edit",
+ title: "Edit index file",
+ facts: ["Modified main function"],
+ narrative: "Updated index.ts with main function",
+ concepts: ["typescript", "entry-point"],
+ files: ["src/index.ts"],
+ importance: 7,
+};
+
+describe("Graph Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ kv = mockKV();
+ vi.clearAllMocks();
+ registerGraphFunction(sdk as never, kv as never, mockProvider as never);
+ });
+
+ it("graph-extract creates nodes and edges from XML response", async () => {
+ const result = (await sdk.trigger("mem::graph-extract", {
+ observations: [testObs],
+ })) as { success: boolean; nodesAdded: number; edgesAdded: number };
+
+ expect(result.success).toBe(true);
+ expect(result.nodesAdded).toBe(2);
+ expect(result.edgesAdded).toBe(1);
+
+ const nodes = await kv.list<GraphNode>("mem:graph:nodes");
+ expect(nodes.length).toBe(2);
+ expect(nodes.find((n) => n.name === "src/index.ts")).toBeDefined();
+ expect(nodes.find((n) => n.name === "main")).toBeDefined();
+
+ const edges = await kv.list<GraphEdge>("mem:graph:edges");
+ expect(edges.length).toBe(1);
+ expect(edges[0].type).toBe("uses");
+ });
+
+ it("graph-query with search returns matching nodes", async () => {
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+
+ const result = (await sdk.trigger("mem::graph-query", {
+ query: "index",
+ })) as GraphQueryResult;
+
+ expect(result.nodes.length).toBeGreaterThanOrEqual(1);
+ expect(result.nodes.some((n) => n.name.includes("index"))).toBe(true);
+ });
+
+ it("graph-query with startNodeId does BFS traversal", async () => {
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+
+ const nodes = await kv.list<GraphNode>("mem:graph:nodes");
+ const fileNode = nodes.find((n) => n.name === "src/index.ts")!;
+
+ const result = (await sdk.trigger("mem::graph-query", {
+ startNodeId: fileNode.id,
+ maxDepth: 2,
+ })) as GraphQueryResult;
+
+ expect(result.nodes.length).toBeGreaterThanOrEqual(1);
+ expect(result.edges.length).toBeGreaterThanOrEqual(1);
+ expect(result.depth).toBe(2);
+ });
+
+ it("graph-stats returns counts by type", async () => {
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+
+ const result = (await sdk.trigger("mem::graph-stats", {})) as {
+ totalNodes: number;
+ totalEdges: number;
+ nodesByType: Record<string, number>;
+ edgesByType: Record<string, number>;
+ };
+
+ expect(result.totalNodes).toBe(2);
+ expect(result.totalEdges).toBe(1);
+ expect(result.nodesByType.file).toBe(1);
+ expect(result.nodesByType.function).toBe(1);
+ expect(result.edgesByType.uses).toBe(1);
+ });
+
+ it("graph-extract returns error for empty observations", async () => {
+ const result = (await sdk.trigger("mem::graph-extract", {
+ observations: [],
+ })) as { success: boolean; error: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("No observations");
+ });
+});
diff --git a/test/mcp-resources.test.ts b/test/mcp-resources.test.ts
index c4e1183f..fc4a35b0 100644
--- a/test/mcp-resources.test.ts
+++ b/test/mcp-resources.test.ts
@@ -71,7 +71,7 @@ describe("MCP Resources", () => {
registerMcpEndpoints(sdk as never, kv as never);
});
- it("lists 4 resources", async () => {
+ it("lists 6 resources", async () => {
const fn = sdk.getFunction("mcp::resources::list")!;
const result = (await fn(makeReq())) as {
status_code: number;
@@ -79,7 +79,7 @@ describe("MCP Resources", () => {
};
expect(result.status_code).toBe(200);
- expect(result.body.resources).toHaveLength(4);
+ expect(result.body.resources).toHaveLength(6);
});
it("reads agentmemory://status", async () => {
diff --git a/test/mcp-standalone.test.ts b/test/mcp-standalone.test.ts
new file mode 100644
index 00000000..69752f3e
--- /dev/null
+++ b/test/mcp-standalone.test.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+vi.mock("node:fs", () => ({
+ existsSync: vi.fn().mockReturnValue(false),
+ readFileSync: vi.fn(),
+ writeFileSync: vi.fn(),
+ mkdirSync: vi.fn(),
+}));
+
+import {
+ getAllTools,
+ CORE_TOOLS,
+ V040_TOOLS,
+} from "../src/mcp/tools-registry.js";
+import { InMemoryKV } from "../src/mcp/in-memory-kv.js";
+import { writeFileSync } from "node:fs";
+
+describe("Tools Registry", () => {
+ it("getAllTools returns 18 tools", () => {
+ const tools = getAllTools();
+ expect(tools.length).toBe(18);
+ });
+
+ it("CORE_TOOLS has 10 items", () => {
+ expect(CORE_TOOLS.length).toBe(10);
+ });
+
+ it("V040_TOOLS has 8 items", () => {
+ expect(V040_TOOLS.length).toBe(8);
+ });
+
+ it("all tools have required name, description, inputSchema fields", () => {
+ const tools = getAllTools();
+ for (const tool of tools) {
+ expect(tool.name).toBeDefined();
+ expect(typeof tool.name).toBe("string");
+ expect(tool.name.length).toBeGreaterThan(0);
+ expect(tool.description).toBeDefined();
+ expect(typeof tool.description).toBe("string");
+ expect(tool.inputSchema).toBeDefined();
+ expect(tool.inputSchema.type).toBe("object");
+ expect(tool.inputSchema.properties).toBeDefined();
+ }
+ });
+});
+
+describe("InMemoryKV", () => {
+ let kv: InMemoryKV;
+
+ beforeEach(() => {
+ kv = new InMemoryKV();
+ });
+
+ it("get/set/list/delete operations work", async () => {
+ await kv.set("scope1", "key1", { value: "hello" });
+ const result = await kv.get<{ value: string }>("scope1", "key1");
+ expect(result).toEqual({ value: "hello" });
+
+ const list = await kv.list("scope1");
+ expect(list.length).toBe(1);
+
+ await kv.delete("scope1", "key1");
+ const afterDelete = await kv.get("scope1", "key1");
+ expect(afterDelete).toBeNull();
+ });
+
+ it("list returns empty array for unknown scope", async () => {
+ const result = await kv.list("nonexistent");
+ expect(result).toEqual([]);
+ });
+
+ it("persist writes JSON", async () => {
+ const kvWithPersist = new InMemoryKV("/tmp/test-kv.json");
+ await kvWithPersist.set("scope1", "key1", { data: "test" });
+ kvWithPersist.persist();
+
+ expect(writeFileSync).toHaveBeenCalledWith(
+ "/tmp/test-kv.json",
+ expect.any(String),
+ "utf-8",
+ );
+ const written = vi.mocked(writeFileSync).mock.calls[0][1] as string;
+ const parsed = JSON.parse(written);
+ expect(parsed.scope1.key1).toEqual({ data: "test" });
+ });
+
+ it("set overwrites existing values", async () => {
+ await kv.set("scope1", "key1", "first");
+ await kv.set("scope1", "key1", "second");
+ const result = await kv.get("scope1", "key1");
+ expect(result).toBe("second");
+ const list = await kv.list("scope1");
+ expect(list.length).toBe(1);
+ });
+});
diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts
new file mode 100644
index 00000000..f3a3a60b
--- /dev/null
+++ b/test/snapshot.test.ts
@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+vi.mock("node:child_process", () => ({
+ execFile: vi.fn(
+ (
+ _cmd: string,
+ _args: string[],
+ _opts: unknown,
+ cb: Function,
+ ) => {
+ cb(null, { stdout: "abc123\n", stderr: "" });
+ },
+ ),
+}));
+
+vi.mock("node:util", async () => {
+ const actual = (await vi.importActual("node:util")) as Record<
+ string,
+ unknown
+ >;
+ return {
+ ...actual,
+ promisify: () => async () => ({ stdout: "abc123\n", stderr: "" }),
+ };
+});
+
+vi.mock("node:fs", () => ({
+ existsSync: vi.fn().mockReturnValue(true),
+ mkdirSync: vi.fn(),
+ writeFileSync: vi.fn(),
+ readFileSync: vi
+ .fn()
+ .mockReturnValue(
+ '{"version":"0.4.0","sessions":[],"memories":[]}',
+ ),
+}));
+
+import { registerSnapshotFunction } from "../src/functions/snapshot.js";
+import type { Session, Memory, SnapshotMeta } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+describe("Snapshot Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+ const snapshotDir = "/tmp/agentmemory-snapshots";
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ vi.clearAllMocks();
+ registerSnapshotFunction(sdk as never, kv as never, snapshotDir);
+
+ const session: Session = {
+ id: "ses_1",
+ project: "test",
+ cwd: "/tmp",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "completed",
+ observationCount: 1,
+ };
+ await kv.set("mem:sessions", "ses_1", session);
+
+ const mem: Memory = {
+ id: "mem_1",
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type: "pattern",
+ title: "Test pattern",
+ content: "Always test",
+ concepts: [],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ };
+ await kv.set("mem:memories", "mem_1", mem);
+ });
+
+ it("snapshot-create serializes state and returns meta", async () => {
+ const result = (await sdk.trigger("mem::snapshot-create", {
+ message: "Test snapshot",
+ })) as { success: boolean; snapshot: SnapshotMeta };
+
+ expect(result.success).toBe(true);
+ expect(result.snapshot).toBeDefined();
+ expect(result.snapshot.commitHash).toBe("abc123");
+ expect(result.snapshot.message).toBe("Test snapshot");
+ expect(result.snapshot.stats.sessions).toBe(1);
+ expect(result.snapshot.stats.memories).toBe(1);
+ });
+
+ it("snapshot-list returns snapshots from git log", async () => {
+ const result = (await sdk.trigger("mem::snapshot-list", {})) as {
+ snapshots: Array<{ commitHash: string; createdAt: string; message: string }>;
+ };
+
+ expect(result.snapshots).toBeDefined();
+ expect(Array.isArray(result.snapshots)).toBe(true);
+ });
+
+ it("snapshot-restore requires commitHash", async () => {
+ const result = (await sdk.trigger("mem::snapshot-restore", {})) as {
+ success: boolean;
+ error: string;
+ };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("commitHash");
+ });
+
+ it("snapshot-restore loads state from commit", async () => {
+ const result = (await sdk.trigger("mem::snapshot-restore", {
+ commitHash: "abc123",
+ })) as { success: boolean; commitHash: string };
+
+ expect(result.success).toBe(true);
+ expect(result.commitHash).toBe("abc123");
+ });
+
+ it("snapshot-create records an audit entry", async () => {
+ await sdk.trigger("mem::snapshot-create", { message: "Audit test" });
+
+ const audits = await kv.list("mem:audit");
+ expect(audits.length).toBe(1);
+ });
+});
diff --git a/test/team.test.ts b/test/team.test.ts
new file mode 100644
index 00000000..4ab9493d
--- /dev/null
+++ b/test/team.test.ts
@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerTeamFunction } from "../src/functions/team.js";
+import type { Memory, TeamConfig, TeamSharedItem, TeamProfile } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+const teamConfig: TeamConfig = {
+ teamId: "test-team",
+ userId: "user-1",
+ mode: "shared" as const,
+};
+
+const testMemory: Memory = {
+ id: "mem_1",
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type: "pattern",
+ title: "Auth pattern",
+ content: "Always validate tokens",
+ concepts: ["auth", "security"],
+ files: ["src/auth.ts"],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+};
+
+describe("Team Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerTeamFunction(sdk as never, kv as never, teamConfig);
+ await kv.set("mem:memories", "mem_1", testMemory);
+ });
+
+ it("team-share stores item in team namespace", async () => {
+ const result = (await sdk.trigger("mem::team-share", {
+ itemId: "mem_1",
+ itemType: "memory",
+ })) as { success: boolean; sharedItem: TeamSharedItem };
+
+ expect(result.success).toBe(true);
+ expect(result.sharedItem.sharedBy).toBe("user-1");
+ expect(result.sharedItem.type).toBe("memory");
+ expect(result.sharedItem.visibility).toBe("shared");
+
+ const items = await kv.list<TeamSharedItem>("mem:team:test-team:shared");
+ expect(items.length).toBe(1);
+ });
+
+ it("team-share fails for missing itemId", async () => {
+ const result = (await sdk.trigger("mem::team-share", {
+ itemType: "memory",
+ })) as { success: boolean; error: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("required");
+ });
+
+ it("team-feed returns shared items sorted by date", async () => {
+ await sdk.trigger("mem::team-share", {
+ itemId: "mem_1",
+ itemType: "memory",
+ });
+
+ const mem2: Memory = { ...testMemory, id: "mem_2", title: "Second pattern" };
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ await new Promise((r) => setTimeout(r, 10));
+ await sdk.trigger("mem::team-share", {
+ itemId: "mem_2",
+ itemType: "memory",
+ });
+
+ const result = (await sdk.trigger("mem::team-feed", {})) as {
+ items: TeamSharedItem[];
+ total: number;
+ };
+
+ expect(result.items.length).toBe(2);
+ expect(result.total).toBe(2);
+ expect(
+ new Date(result.items[0].sharedAt).getTime(),
+ ).toBeGreaterThanOrEqual(new Date(result.items[1].sharedAt).getTime());
+ });
+
+ it("team-profile aggregates concepts and files", async () => {
+ await sdk.trigger("mem::team-share", {
+ itemId: "mem_1",
+ itemType: "pattern",
+ });
+
+ const result = (await sdk.trigger("mem::team-profile", {})) as TeamProfile;
+
+ expect(result.teamId).toBe("test-team");
+ expect(result.members).toContain("user-1");
+ expect(result.totalSharedItems).toBe(1);
+ expect(result.topConcepts.length).toBeGreaterThan(0);
+ expect(result.topConcepts.some((c) => c.concept === "auth")).toBe(true);
+ expect(result.topFiles.some((f) => f.file === "src/auth.ts")).toBe(true);
+ });
+
+ it("team-share fails when item not found in KV", async () => {
+ const result = (await sdk.trigger("mem::team-share", {
+ itemId: "nonexistent",
+ itemType: "memory",
+ })) as { success: boolean; error: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("not found");
+ });
+});
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 1dc56f61..9de854ee 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -26,6 +26,15 @@ export default defineConfig([
target: "node18",
banner: { js: "#!/usr/bin/env node" },
},
+ {
+ entry: ["src/mcp/standalone.ts"],
+ outDir: "dist",
+ format: ["esm"],
+ clean: false,
+ sourcemap: false,
+ target: "node18",
+ banner: { js: "#!/usr/bin/env node" },
+ },
{
entry: hookEntries,
outDir: "dist/hooks",