@waynesutton/agent-memory 0.0.1-alpha.1

package/dist/shared.d.ts

@@ -0,0 +1,126 @@
+export declare const MEMORY_TYPES: readonly ["instruction", "learning", "reference", "feedback", "journal"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export declare const memoryTypeValidator: import("convex/values").VUnion<"instruction" | "learning" | "reference" | "feedback" | "journal", [import("convex/values").VLiteral<"instruction", "required">, import("convex/values").VLiteral<"learning", "required">, import("convex/values").VLiteral<"reference", "required">, import("convex/values").VLiteral<"feedback", "required">, import("convex/values").VLiteral<"journal", "required">], "required", never>;
+export declare const SCOPES: readonly ["project", "user", "org"];
+export type Scope = (typeof SCOPES)[number];
+export declare const scopeValidator: import("convex/values").VUnion<"project" | "user" | "org", [import("convex/values").VLiteral<"project", "required">, import("convex/values").VLiteral<"user", "required">, import("convex/values").VLiteral<"org", "required">], "required", never>;
+export declare const syncDirectionValidator: import("convex/values").VUnion<"push" | "pull", [import("convex/values").VLiteral<"push", "required">, import("convex/values").VLiteral<"pull", "required">], "required", never>;
+export declare const TOOL_FORMATS: readonly ["claude-code", "cursor", "opencode", "codex", "conductor", "zed", "vscode-copilot", "pi", "raw"];
+export type ToolFormat = (typeof TOOL_FORMATS)[number];
+export declare const toolFormatValidator: import("convex/values").VUnion<"claude-code" | "cursor" | "opencode" | "codex" | "conductor" | "zed" | "vscode-copilot" | "pi" | "raw", [import("convex/values").VLiteral<"claude-code", "required">, import("convex/values").VLiteral<"cursor", "required">, import("convex/values").VLiteral<"opencode", "required">, import("convex/values").VLiteral<"codex", "required">, import("convex/values").VLiteral<"conductor", "required">, import("convex/values").VLiteral<"zed", "required">, import("convex/values").VLiteral<"vscode-copilot", "required">, import("convex/values").VLiteral<"pi", "required">, import("convex/values").VLiteral<"raw", "required">], "required", never>;
+export declare const HISTORY_EVENTS: readonly ["created", "updated", "archived", "restored", "merged"];
+export type HistoryEvent = (typeof HISTORY_EVENTS)[number];
+export declare const FEEDBACK_SENTIMENTS: readonly ["positive", "negative", "very_negative"];
+export type FeedbackSentiment = (typeof FEEDBACK_SENTIMENTS)[number];
+export declare const INGEST_EVENTS: readonly ["added", "updated", "deleted", "skipped"];
+export type IngestEvent = (typeof INGEST_EVENTS)[number];
+export interface Memory {
+    _id: string;
+    _creationTime: number;
+    projectId: string;
+    scope: Scope;
+    userId?: string;
+    agentId?: string;
+    sessionId?: string;
+    title: string;
+    content: string;
+    memoryType: MemoryType;
+    tags: string[];
+    paths?: string[];
+    priority?: number;
+    source?: string;
+    lastSyncedAt?: number;
+    checksum: string;
+    archived: boolean;
+    embeddingId?: string;
+    accessCount?: number;
+    lastAccessedAt?: number;
+    positiveCount?: number;
+    negativeCount?: number;
+}
+export interface ContextBundle {
+    pinned: Memory[];
+    relevant: Memory[];
+    available: Array<{
+        _id: string;
+        title: string;
+        memoryType: MemoryType;
+        priority: number;
+    }>;
+}
+export interface ExportedFile {
+    path: string;
+    content: string;
+    checksum: string;
+}
+export interface ImportResult {
+    created: number;
+    updated: number;
+    unchanged: number;
+}
+export interface MemoryHistoryEntry {
+    _id: string;
+    _creationTime: number;
+    memoryId: string;
+    projectId: string;
+    previousContent?: string;
+    newContent?: string;
+    previousTitle?: string;
+    newTitle?: string;
+    event: HistoryEvent;
+    actor: string;
+    timestamp: number;
+}
+export interface MemoryFeedbackEntry {
+    _id: string;
+    _creationTime: number;
+    memoryId: string;
+    projectId: string;
+    sentiment: FeedbackSentiment;
+    comment?: string;
+    actor: string;
+    timestamp: number;
+}
+export interface MemoryRelation {
+    _id: string;
+    _creationTime: number;
+    projectId: string;
+    fromMemoryId: string;
+    toMemoryId: string;
+    relationship: string;
+    metadata?: {
+        confidence?: number;
+        createdBy?: string;
+    };
+    timestamp: number;
+}
+export interface IngestResult {
+    results: Array<{
+        memoryId: string;
+        content: string;
+        event: IngestEvent;
+        previousContent?: string;
+    }>;
+    totalProcessed: number;
+}
+export interface ApiKeyInfo {
+    _id: string;
+    keyHash: string;
+    projectId: string;
+    name: string;
+    permissions: string[];
+    rateLimitOverride?: {
+        requestsPerWindow: number;
+        windowMs: number;
+    };
+    lastUsedAt?: number;
+    expiresAt?: number;
+    revoked: boolean;
+}
+export interface ApiKeyCreateResult {
+    key: string;
+    keyHash: string;
+}
+export declare const API_PERMISSIONS: readonly ["list", "get", "search", "context", "export", "history", "relations"];
+export type ApiPermission = (typeof API_PERMISSIONS)[number];
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"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"}

package/dist/shared.js

@@ -0,0 +1,67 @@
+import { v } from "convex/values";
+// ── Memory types ────────────────────────────────────────────────────
+// instruction: maps to CLAUDE.md / .cursor/rules / AGENTS.md
+// learning:    auto-discovered patterns (auto-memory)
+// reference:   architecture docs, API specs
+// feedback:    corrections, preferences
+// journal:     session logs (OpenCode-style)
+export const MEMORY_TYPES = [
+    "instruction",
+    "learning",
+    "reference",
+    "feedback",
+    "journal",
+];
+export const memoryTypeValidator = v.union(v.literal("instruction"), v.literal("learning"), v.literal("reference"), v.literal("feedback"), v.literal("journal"));
+// ── Scope types ─────────────────────────────────────────────────────
+// project: shared across team via Convex
+// user:    personal to one user
+// org:     organization-wide policies
+export const SCOPES = ["project", "user", "org"];
+export const scopeValidator = v.union(v.literal("project"), v.literal("user"), v.literal("org"));
+// ── Sync direction ──────────────────────────────────────────────────
+export const syncDirectionValidator = v.union(v.literal("push"), v.literal("pull"));
+// ── Tool formats ────────────────────────────────────────────────────
+export const TOOL_FORMATS = [
+    "claude-code",
+    "cursor",
+    "opencode",
+    "codex",
+    "conductor",
+    "zed",
+    "vscode-copilot",
+    "pi",
+    "raw",
+];
+export const toolFormatValidator = v.union(v.literal("claude-code"), v.literal("cursor"), v.literal("opencode"), v.literal("codex"), v.literal("conductor"), v.literal("zed"), v.literal("vscode-copilot"), v.literal("pi"), v.literal("raw"));
+// ── History events ──────────────────────────────────────────────────
+export const HISTORY_EVENTS = [
+    "created",
+    "updated",
+    "archived",
+    "restored",
+    "merged",
+];
+// ── Feedback sentiments ─────────────────────────────────────────────
+export const FEEDBACK_SENTIMENTS = [
+    "positive",
+    "negative",
+    "very_negative",
+];
+// ── Ingest events ───────────────────────────────────────────────────
+export const INGEST_EVENTS = [
+    "added",
+    "updated",
+    "deleted",
+    "skipped",
+];
+export const API_PERMISSIONS = [
+    "list",
+    "get",
+    "search",
+    "context",
+    "export",
+    "history",
+    "relations",
+];
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,uEAAuE;AACvE,6DAA6D;AAC7D,sDAAsD;AACtD,4CAA4C;AAC5C,wCAAwC;AACxC,6CAA6C;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,UAAU;IACV,WAAW;IACX,UAAU;IACV,SAAS;CACD,CAAC;AAIX,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CACxC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EACxB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EACrB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EACrB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CACrB,CAAC;AAEF,uEAAuE;AACvE,yCAAyC;AACzC,gCAAgC;AAChC,sCAAsC;AAEtC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAG1D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CACnC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CACjB,CAAC;AAEF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC3C,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAClB,CAAC;AAEF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,QAAQ;IACR,UAAU;IACV,OAAO;IACP,WAAW;IACX,KAAK;IACL,gBAAgB;IAChB,IAAI;IACJ,KAAK;CACG,CAAC;AAIX,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CACxC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EACxB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EACrB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAClB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EACtB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAChB,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAC3B,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EACf,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CACjB,CAAC;AAEF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS;IACT,SAAS;IACT,UAAU;IACV,UAAU;IACV,QAAQ;CACA,CAAC;AAIX,uEAAuE;AAEvE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,UAAU;IACV,eAAe;CACP,CAAC;AAIX,uEAAuE;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO;IACP,SAAS;IACT,SAAS;IACT,SAAS;CACD,CAAC;AAuIX,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM;IACN,KAAK;IACL,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,SAAS;IACT,WAAW;CACH,CAAC"}

package/dist/test.d.ts

@@ -0,0 +1,23 @@
+declare global {
+    interface ImportMeta {
+        glob(pattern: string): Record<string, () => Promise<unknown>>;
+    }
+}
+/**
+ * Register the agentMemory component in a convex-test instance.
+ *
+ * @example
+ * ```ts
+ * import agentMemoryTest from "@waynesutton/agent-memory/test";
+ * import { convexTest } from "convex-test";
+ *
+ * const t = convexTest();
+ * agentMemoryTest.register(t);
+ * ```
+ */
+export declare function register(t: any, name?: string): void;
+declare const _default: {
+    register: typeof register;
+};
+export default _default;
+//# sourceMappingURL=test.d.ts.map

package/dist/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAGA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;KAC/D;CACF;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAEtB,CAAC,EAAE,GAAG,EACN,IAAI,GAAE,MAAsB,QAG7B;;;;AAED,wBAA4B"}

package/dist/test.js

@@ -0,0 +1,21 @@
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+/**
+ * Register the agentMemory component in a convex-test instance.
+ *
+ * @example
+ * ```ts
+ * import agentMemoryTest from "@waynesutton/agent-memory/test";
+ * import { convexTest } from "convex-test";
+ *
+ * const t = convexTest();
+ * agentMemoryTest.register(t);
+ * ```
+ */
+export function register(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+t, name = "agentMemory") {
+    t.registerComponent(name, schema, modules);
+}
+export default { register };
+//# sourceMappingURL=test.js.map

package/dist/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,uBAAuB,CAAC;AAS3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ;AACtB,8DAA8D;AAC9D,CAAM,EACN,OAAe,aAAa;IAE5B,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,eAAe,EAAE,QAAQ,EAAE,CAAC"}

package/eslint.config.js

@@ -0,0 +1,15 @@
+import convexPlugin from "@convex-dev/eslint-plugin";
+
+export default [
+  {
+    plugins: {
+      "@convex-dev": convexPlugin,
+    },
+    files: ["src/component/**/*.ts"],
+    rules: {
+      "@convex-dev/no-old-registered-function-syntax": "error",
+      "@convex-dev/require-argument-validators": "error",
+      "@convex-dev/no-collect-in-query": "error",
+    },
+  },
+];

package/example/convex/convex.config.ts

@@ -0,0 +1,7 @@
+import { defineApp } from "convex/server";
+import agentMemory from "../../src/component/convex.config.js";
+
+const app = defineApp();
+app.use(agentMemory);
+
+export default app;

package/example/convex/memory.ts

@@ -0,0 +1,129 @@
+import { v } from "convex/values";
+import { query, mutation, action } from "./_generated/server.js";
+import { components } from "./_generated/api.js";
+import { AgentMemory } from "../../src/client/index.js";
+
+const memory = new AgentMemory(components.agentMemory, {
+  projectId: "example-app",
+  defaultScope: "project",
+});
+
+// ── Public mutations ────────────────────────────────────────────────
+
+export const remember = mutation({
+  args: {
+    title: v.string(),
+    content: v.string(),
+    memoryType: v.union(
+      v.literal("instruction"),
+      v.literal("learning"),
+      v.literal("reference"),
+      v.literal("feedback"),
+      v.literal("journal"),
+    ),
+    tags: v.optional(v.array(v.string())),
+    paths: v.optional(v.array(v.string())),
+    priority: v.optional(v.float64()),
+  },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    return await memory.remember(ctx, {
+      title: args.title,
+      content: args.content,
+      memoryType: args.memoryType,
+      tags: args.tags,
+      paths: args.paths,
+      priority: args.priority,
+      source: "example-app",
+    });
+  },
+});
+
+export const forget = mutation({
+  args: { memoryId: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await memory.forget(ctx, args.memoryId);
+    return null;
+  },
+});
+
+// ── Public queries ──────────────────────────────────────────────────
+
+export const listMemories = query({
+  args: {
+    memoryType: v.optional(
+      v.union(
+        v.literal("instruction"),
+        v.literal("learning"),
+        v.literal("reference"),
+        v.literal("feedback"),
+        v.literal("journal"),
+      ),
+    ),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await memory.list(ctx, {
+      memoryType: args.memoryType,
+    });
+  },
+});
+
+export const recall = query({
+  args: { q: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await memory.search(ctx, args.q);
+  },
+});
+
+export const getContext = query({
+  args: {
+    activePaths: v.optional(v.array(v.string())),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await memory.getContextBundle(ctx, {
+      activePaths: args.activePaths,
+    });
+  },
+});
+
+// ── Type ingestion ──────────────────────────────────────────────────
+
+export const ingestTypes = mutation({
+  args: {
+    types: v.array(
+      v.object({
+        title: v.string(),
+        content: v.string(),
+        tags: v.optional(v.array(v.string())),
+        paths: v.optional(v.array(v.string())),
+        priority: v.optional(v.float64()),
+      }),
+    ),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await memory.ingestTypes(ctx, args.types);
+  },
+});
+
+// ── Actions (for vector search) ─────────────────────────────────────
+
+export const semanticRecall = action({
+  args: {
+    q: v.string(),
+    embeddingApiKey: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    // Create a memory instance with the API key for this request
+    const memWithKey = new AgentMemory(components.agentMemory, {
+      ...memory.config,
+      embeddingApiKey: args.embeddingApiKey,
+    });
+    return await memWithKey.semanticSearch(ctx, args.q);
+  },
+});

package/llms.md

@@ -0,0 +1,175 @@
+# @waynesutton/agent-memory — Agent Reference
+
+A Convex Component for persistent, cloud-synced agent memory. Markdown-first memory backend for AI coding agents across CLIs and IDEs.
+
+## For AI Agents Using This Library
+
+You are working with `@waynesutton/agent-memory`, a Convex component that gives you persistent memory across sessions, tools, and machines. This document tells you how to use it effectively.
+
+## The Architecture
+
+```
+Your App (Convex)
+├── convex/convex.config.ts    ← registers the component with app.use(agentMemory)
+├── convex/memory.ts           ← your wrapper functions calling AgentMemory class
+├── convex/http.ts             ← optional: mounts MemoryHttpApi for REST access
+└── node_modules/@waynesutton/agent-memory/
+    ├── src/component/         ← Convex backend (9 tables, isolated)
+    ├── src/client/index.ts    ← AgentMemory class (main API)
+    ├── src/client/http.ts     ← MemoryHttpApi class (HTTP endpoints)
+    ├── src/mcp/server.ts      ← MCP server (14 tools)
+    └── src/cli/               ← CLI for push/pull/sync
+```
+
+## How to Use
+
+### 1. Setup (in consuming app)
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import agentMemory from "@waynesutton/agent-memory/convex.config.js";
+const app = defineApp();
+app.use(agentMemory);
+export default app;
+```
+
+```typescript
+// convex/memory.ts
+import { AgentMemory } from "@waynesutton/agent-memory";
+import { components } from "./_generated/api.js";
+
+const memory = new AgentMemory(components.agentMemory, {
+  projectId: "my-project",
+  agentId: "my-agent",           // identifies you
+  llmApiKey: process.env.OPENAI_API_KEY,  // for intelligent ingest
+});
+```
+
+### 2. Saving Memories
+
+```typescript
+const id = await memory.remember(ctx, {
+  title: "api-conventions",
+  content: "# API Conventions\n\n- Use camelCase\n- Return JSON",
+  memoryType: "instruction",     // instruction | learning | reference | feedback | journal
+  tags: ["api", "style"],
+  paths: ["src/api/**"],         // file patterns for relevance matching
+  priority: 0.9,                 // >= 0.8 = pinned (always included in context)
+});
+```
+
+### 3. Retrieving Memories
+
+```typescript
+// Full-text search
+const results = await memory.search(ctx, "API authentication");
+
+// List with filters
+const mems = await memory.list(ctx, {
+  memoryType: "instruction",
+  tags: ["api"],
+  agentId: "claude-code",
+});
+
+// Progressive context bundle (best for agent sessions)
+const bundle = await memory.getContextBundle(ctx, {
+  activePaths: ["src/api/routes.ts"],
+});
+// bundle.pinned    — high-priority memories (always include)
+// bundle.relevant  — path-matched memories
+// bundle.available — everything else (summaries only)
+```
+
+### 4. Intelligent Ingest
+
+Feed raw text and the LLM pipeline extracts facts, deduplicates against existing memories, and decides ADD/UPDATE/DELETE/SKIP per fact:
+
+```typescript
+const result = await memory.ingest(ctx, rawConversationText);
+// result.results: [{ event: "added"|"updated"|"deleted"|"skipped", content, memoryId }]
+```
+
+### 5. Feedback Loop
+
+Rate memories to influence priority scoring in future context bundles:
+
+```typescript
+await memory.addFeedback(ctx, memoryId, "positive", { comment: "Very helpful" });
+await memory.addFeedback(ctx, memoryId, "negative", { comment: "Outdated" });
+```
+
+### 6. Memory Relations
+
+Build a knowledge graph between memories:
+
+```typescript
+await memory.addRelation(ctx, memoryA, memoryB, "extends");
+await memory.addRelation(ctx, memoryC, memoryA, "contradicts", { confidence: 0.9 });
+```
+
+### 7. HTTP API
+
+Expose memories as REST endpoints:
+
+```typescript
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { MemoryHttpApi } from "@waynesutton/agent-memory/http";
+import { components } from "./_generated/api";
+
+const http = httpRouter();
+new MemoryHttpApi(components.agentMemory).mount(http, "/api/memory");
+export default http;
+```
+
+Create API keys: `await memory.createApiKey(ctx, { name: "...", permissions: ["list", "search"] })`
+
+## Key Types
+
+```typescript
+type MemoryType = "instruction" | "learning" | "reference" | "feedback" | "journal";
+type Scope = "project" | "user" | "org";
+type FeedbackSentiment = "positive" | "negative" | "very_negative";
+type ToolFormat = "claude-code" | "cursor" | "opencode" | "codex" | "conductor" | "zed" | "vscode-copilot" | "pi" | "raw";
+```
+
+## Convex Component Constraints
+
+When working with this component, be aware of:
+
+- **No `ctx.auth`** — components don't have access to the app's auth. Pass `userId`/`agentId` explicitly in config.
+- **No `process.env`** — components can't read environment variables. API keys are passed as function arguments.
+- **IDs become strings** — Convex document IDs cross the component boundary as strings, not typed `Id<"table">`.
+- **Isolated tables** — the component's 9 tables are namespaced under `agentMemory:` and isolated from your app's tables.
+
+## MCP Server Tools (14)
+
+When using via MCP, these tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `memory_remember` | Save a new memory |
+| `memory_recall` | Full-text search |
+| `memory_semantic_recall` | Vector similarity search |
+| `memory_list` | List with filters |
+| `memory_context` | Get context bundle |
+| `memory_forget` | Archive a memory |
+| `memory_restore` | Restore archived memory |
+| `memory_update` | Update existing memory |
+| `memory_history` | View audit trail |
+| `memory_feedback` | Rate as helpful/unhelpful |
+| `memory_relate` | Create relationship |
+| `memory_relations` | View graph connections |
+| `memory_batch_archive` | Archive multiple |
+| `memory_ingest` | LLM-powered fact extraction |
+
+## File References
+
+- Component schema: `src/component/schema.ts`
+- Client API: `src/client/index.ts`
+- HTTP API: `src/client/http.ts`
+- MCP server: `src/mcp/server.ts`
+- Shared types: `src/shared.ts`
+- Full API reference: `prds/API-REFERENCE.md`
+- Setup guide: `prds/SETUP.md`