yourmemory 1.0.1__py3-none-any.whl

memory_mcp.py

@@ -0,0 +1,464 @@
+"""
+YourMemory MCP Server
+
+Exposes three tools to Claude:
+  recall_memory  — retrieve relevant memories before answering
+  store_memory   — insert a new memory after learning something new
+  update_memory  — merge or replace an existing memory (by id from recall)
+"""
+
+import asyncio
+import json
+import os
+import sys
+import threading
+
+from dotenv import load_dotenv
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp import types
+
+# Add project root so src.services imports work
+sys.path.insert(0, os.path.dirname(__file__))
+load_dotenv(os.path.join(os.path.dirname(__file__), ".env"))
+
+# Heavy imports (spaCy model, DB drivers) are deferred to first tool call
+# so the MCP handshake completes instantly on startup.
+_services = {}
+
+def _load_services():
+    if _services:
+        return
+    from src.services.retrieve import retrieve as _retrieve
+    from src.services.embed import embed
+    from src.services.extract import is_question, categorize
+    from src.services.api_keys import validate_api_key
+    from src.services.resolve import resolve
+    from src.db.connection import get_backend, get_conn, emb_to_db
+    _services["retrieve"]         = _retrieve
+    _services["embed"]            = embed
+    _services["is_question"]      = is_question
+    _services["categorize"]       = categorize
+    _services["validate_api_key"] = validate_api_key
+    _services["resolve"]          = resolve
+    _services["get_backend"]      = get_backend
+    _services["get_conn"]         = get_conn
+    _services["emb_to_db"]        = emb_to_db
+
+DEFAULT_USER       = "sachit"
+DEFAULT_IMPORTANCE = 0.5
+
+
+# ── MCP Server ────────────────────────────────────────────────────────────────
+
+server = Server("yourmemory")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="recall_memory",
+            description=(
+                "Retrieve memories relevant to a query. "
+                "Call this at the start of every task to get context about the user's preferences, "
+                "past instructions, and known facts. Returns a list of memories with their IDs."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Keywords or sentence describing what to look for in memory.",
+                    },
+                    "user_id": {
+                        "type": "string",
+                        "description": f"User identifier (default: '{DEFAULT_USER}').",
+                    },
+                    "api_key": {
+                        "type": "string",
+                        "description": "Agent API key (starts with 'ym_'). If provided, also returns this agent's private memories. If omitted, returns shared memories only.",
+                    },
+                    "top_k": {
+                        "type": "integer",
+                        "description": "Max memories to return (default: 5).",
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+        types.Tool(
+            name="store_memory",
+            description=(
+                "Store a new memory about the user. "
+                "Use when you learn a new fact, preference, instruction, past failure, or successful strategy. "
+                "Does not conflict with any memory returned by recall_memory."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "description": "The fact, preference, failure, or strategy to remember.",
+                    },
+                    "importance": {
+                        "type": "number",
+                        "description": (
+                            "You MUST decide this. How important is this memory? (0.0–1.0)\n"
+                            "0.9–1.0 — core identity, permanent preferences (e.g. 'Sachit uses Python')\n"
+                            "0.7–0.8 — strong preferences, recurring patterns\n"
+                            "0.5     — regular facts, project decisions\n"
+                            "0.2–0.3 — transient context, one-off notes from this session"
+                        ),
+                    },
+                    "category": {
+                        "type": "string",
+                        "description": (
+                            "Memory category — controls decay rate:\n"
+                            "  'fact'       — user preferences, identity, stable knowledge (default, ~24 day survival)\n"
+                            "  'assumption' — inferred beliefs, uncertain context (~19 days)\n"
+                            "  'failure'    — what went wrong in a past task, environment-specific errors (~11 days, decays fast)\n"
+                            "  'strategy'   — what worked well in a past task, approach patterns (~38 days, decays slow)\n"
+                            "Use 'failure' when storing e.g. 'OAuth failed for client X due to wrong redirect URI'.\n"
+                            "Use 'strategy' when storing e.g. 'Using pagination fixed the timeout on large DB queries'."
+                        ),
+                    },
+                    "user_id": {
+                        "type": "string",
+                        "description": f"User identifier (default: '{DEFAULT_USER}').",
+                    },
+                    "api_key": {
+                        "type": "string",
+                        "description": "Agent API key (starts with 'ym_'). Required for agent-scoped memory. If omitted, stored as 'user' with shared visibility.",
+                    },
+                    "visibility": {
+                        "type": "string",
+                        "description": "Who can recall this memory: 'shared' (any agent, default) or 'private' (only this agent).",
+                    },
+                },
+                "required": ["content", "importance"],
+            },
+        ),
+        types.Tool(
+            name="update_memory",
+            description=(
+                "Merge or replace an existing memory by its ID. "
+                "Use when a recalled memory is outdated (replace) or when new info adds detail "
+                "to an existing memory (merge — write the combined sentence as new_content)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "memory_id": {
+                        "type": "integer",
+                        "description": "ID of the memory to update (from recall_memory results).",
+                    },
+                    "new_content": {
+                        "type": "string",
+                        "description": "The updated or merged memory text.",
+                    },
+                    "importance": {
+                        "type": "number",
+                        "description": (
+                            "You MUST decide this. Re-evaluate importance after the update. (0.0–1.0)\n"
+                            "0.9–1.0 — core identity, permanent preferences\n"
+                            "0.7–0.8 — strong preferences, recurring patterns\n"
+                            "0.5     — regular facts, project decisions\n"
+                            "0.2–0.3 — transient context, one-off notes"
+                        ),
+                    },
+                },
+                "required": ["memory_id", "new_content", "importance"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    _load_services()
+    retrieve         = _services["retrieve"]
+    embed            = _services["embed"]
+    is_question      = _services["is_question"]
+    categorize       = _services["categorize"]
+    validate_api_key = _services["validate_api_key"]
+    resolve          = _services["resolve"]
+    get_backend      = _services["get_backend"]
+    get_conn         = _services["get_conn"]
+    emb_to_db        = _services["emb_to_db"]
+
+    if name == "recall_memory":
+        user_id = arguments.get("user_id", DEFAULT_USER)
+        query   = arguments["query"]
+        top_k   = arguments.get("top_k", 5)
+        api_key = arguments.get("api_key")
+
+        agent = None
+        if api_key:
+            agent = validate_api_key(api_key)
+            if not agent:
+                return [types.TextContent(type="text", text=json.dumps(
+                    {"error": "Invalid or revoked API key."}))]
+
+        agent_id = agent["agent_id"] if agent else None
+        result   = retrieve(user_id, query, top_k=top_k, agent_id=agent_id)
+
+        if agent:
+            can_read = agent.get("can_read", [])
+            if can_read:
+                result["memories"] = [
+                    m for m in result["memories"]
+                    if m["agent_id"] in can_read
+                ]
+                result["memoriesFound"] = len(result["memories"])
+
+        return [types.TextContent(type="text", text=json.dumps(result, default=str))]
+
+    elif name == "store_memory":
+        user_id = arguments.get("user_id", DEFAULT_USER)
+        api_key = arguments.get("api_key")
+
+        if api_key:
+            agent = validate_api_key(api_key)
+            if not agent:
+                return [types.TextContent(type="text", text=json.dumps(
+                    {"error": "Invalid or revoked API key."}))]
+            agent_id  = agent["agent_id"]
+            can_write = agent.get("can_write", ["shared", "private"])
+        else:
+            agent_id  = "user"
+            can_write = ["shared", "private"]
+
+        visibility = arguments.get("visibility", "shared")
+        if visibility not in ("shared", "private"):
+            visibility = "shared"
+        if visibility not in can_write:
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": f"Agent '{agent_id}' is not permitted to write '{visibility}' memories."}))]
+
+        content = arguments["content"]
+
+        if is_question(content):
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": "Questions are not stored as memories."}))]
+
+        if "importance" not in arguments:
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": "importance is required (0.0–1.0). Decide based on how permanent this memory should be."}))]
+        importance = max(0.0, min(1.0, float(arguments["importance"])))
+        valid_categories = {"fact", "assumption", "failure", "strategy"}
+        raw_category = arguments.get("category", "").strip().lower()
+        category     = raw_category if raw_category in valid_categories else categorize(content)
+        embedding    = embed(content)
+
+        backend = get_backend()
+        conn    = get_conn()
+        cur     = conn.cursor()
+
+        resolution    = resolve(user_id, content, embedding, conn)
+        action        = resolution["action"]
+        final_content = resolution["content"]
+        existing      = resolution["existing"]
+
+        if action == "reinforce":
+            if backend == "postgres":
+                cur.execute("""
+                    UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = NOW()
+                    WHERE id = %s RETURNING id
+                """, (existing["id"],))
+            else:
+                cur.execute("""
+                    UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = datetime('now')
+                    WHERE id = ?
+                """, (existing["id"],))
+            memory_id = existing["id"]
+            category  = existing["category"]
+
+        elif action in ("replace", "merge"):
+            new_embedding = embed(final_content)
+            new_emb_str   = emb_to_db(new_embedding, backend)
+            new_category  = categorize(final_content)
+            try:
+                if backend == "postgres":
+                    cur.execute("""
+                        UPDATE memories
+                        SET content = %s, embedding = %s::vector, category = %s,
+                            recall_count = recall_count + 1, last_accessed_at = NOW()
+                        WHERE id = %s RETURNING id
+                    """, (final_content, new_emb_str, new_category, existing["id"]))
+                else:
+                    cur.execute("""
+                        UPDATE memories
+                        SET content = ?, embedding = ?, category = ?,
+                            recall_count = recall_count + 1, last_accessed_at = datetime('now')
+                        WHERE id = ?
+                    """, (final_content, new_emb_str, new_category, existing["id"]))
+                memory_id = existing["id"]
+                category  = new_category
+            except Exception:
+                conn.rollback()
+                if backend == "postgres":
+                    cur.execute("""
+                        UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = NOW()
+                        WHERE user_id = %s AND content = %s RETURNING id
+                    """, (user_id, final_content))
+                else:
+                    cur.execute("""
+                        UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = datetime('now')
+                        WHERE user_id = ? AND content = ?
+                    """, (user_id, final_content))
+                memory_id = existing["id"]
+                category  = existing["category"]
+
+        else:  # "new"
+            emb_str = emb_to_db(embedding, backend)
+            if backend == "postgres":
+                cur.execute("""
+                    INSERT INTO memories (user_id, content, category, importance, embedding, agent_id, visibility)
+                    VALUES (%s, %s, %s, %s, %s::vector, %s, %s)
+                    ON CONFLICT (user_id, content) DO UPDATE
+                        SET recall_count = memories.recall_count + 1, last_accessed_at = NOW()
+                    RETURNING id
+                """, (user_id, final_content, category, importance, emb_str, agent_id, visibility))
+                memory_id = cur.fetchone()[0]
+            else:
+                cur.execute("""
+                    INSERT INTO memories (user_id, content, category, importance, embedding, agent_id, visibility)
+                    VALUES (?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT (user_id, content) DO UPDATE
+                        SET recall_count = recall_count + 1, last_accessed_at = datetime('now')
+                """, (user_id, final_content, category, importance, emb_str, agent_id, visibility))
+                memory_id = cur.lastrowid
+
+        conn.commit()
+        cur.close()
+        conn.close()
+
+        return [types.TextContent(type="text", text=json.dumps(
+            {"stored": 1, "id": memory_id, "content": final_content, "category": category,
+             "importance": importance, "agent_id": agent_id, "visibility": visibility,
+             "action": action}))]
+
+    elif name == "update_memory":
+        memory_id   = arguments["memory_id"]
+        new_content = arguments["new_content"]
+        if "importance" not in arguments:
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": "importance is required (0.0–1.0). Re-evaluate after the update."}))]
+        importance = max(0.0, min(1.0, float(arguments["importance"])))
+
+        category  = _services["categorize"](new_content)
+        embedding = embed(new_content)
+        backend   = get_backend()
+        emb_str   = emb_to_db(embedding, backend)
+        conn      = get_conn()
+        cur       = conn.cursor()
+
+        # Fetch owner to scope the dedup query
+        if backend == "postgres":
+            cur.execute("SELECT user_id FROM memories WHERE id = %s", (memory_id,))
+        else:
+            cur.execute("SELECT user_id FROM memories WHERE id = ?", (memory_id,))
+        owner = cur.fetchone()
+        if owner is None:
+            cur.close()
+            conn.close()
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": f"Memory {memory_id} not found."}))]
+        user_id_owner = owner[0]
+
+        # Check if new content clashes with a *different* row
+        resolution = resolve(user_id_owner, new_content, embedding, conn)
+        if resolution["action"] != "new" and resolution["existing"]["id"] != memory_id:
+            existing = resolution["existing"]
+            if backend == "postgres":
+                cur.execute("""
+                    UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = NOW()
+                    WHERE id = %s RETURNING id, content, category, importance
+                """, (existing["id"],))
+                row = cur.fetchone()
+            else:
+                cur.execute("""
+                    UPDATE memories SET recall_count = recall_count + 1, last_accessed_at = datetime('now')
+                    WHERE id = ?
+                """, (existing["id"],))
+                cur.execute("SELECT id, content, category, importance FROM memories WHERE id = ?", (existing["id"],))
+                row = cur.fetchone()
+            conn.commit()
+            cur.close()
+            conn.close()
+            return [types.TextContent(type="text", text=json.dumps(
+                {"updated": 1, "id": row[0], "content": row[1], "category": row[2],
+                 "importance": row[3], "action": "reinforce_existing"}))]
+
+        if backend == "postgres":
+            cur.execute("""
+                UPDATE memories
+                SET content          = %s,
+                    embedding        = %s::vector,
+                    category         = %s,
+                    importance       = %s,
+                    recall_count     = recall_count + 1,
+                    last_accessed_at = NOW()
+                WHERE id = %s
+                RETURNING id, content, category, importance
+            """, (new_content, emb_str, category, importance, memory_id))
+            row = cur.fetchone()
+        else:
+            cur.execute("""
+                UPDATE memories
+                SET content          = ?,
+                    embedding        = ?,
+                    category         = ?,
+                    importance       = ?,
+                    recall_count     = recall_count + 1,
+                    last_accessed_at = datetime('now')
+                WHERE id = ?
+            """, (new_content, emb_str, category, importance, memory_id))
+            cur.execute("SELECT id, content, category, importance FROM memories WHERE id = ?", (memory_id,))
+            row = cur.fetchone()
+
+        conn.commit()
+        cur.close()
+        conn.close()
+
+        if row is None:
+            return [types.TextContent(type="text", text=json.dumps(
+                {"error": f"Memory {memory_id} not found."}))]
+
+        return [types.TextContent(type="text", text=json.dumps(
+            {"updated": 1, "id": row[0], "content": row[1], "category": row[2], "importance": row[3]}))]
+
+    else:
+        return [types.TextContent(type="text", text=json.dumps({"error": f"Unknown tool: {name}"}))]
+
+
+def _start_decay_scheduler():
+    """Run the decay job once immediately, then every 24 hours in a background thread."""
+    from src.jobs.decay_job import run as run_decay
+
+    def loop():
+        run_decay()
+        timer = threading.Event()
+        while not timer.wait(timeout=86400):
+            run_decay()
+
+    t = threading.Thread(target=loop, daemon=True, name="decay-scheduler")
+    t.start()
+
+
+async def main():
+    # Run DB migration on startup (creates tables on first run, safe to repeat)
+    from src.db.migrate import migrate
+    migrate()
+    _start_decay_scheduler()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def run():
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

src/app.py

@@ -0,0 +1,30 @@
+from contextlib import asynccontextmanager
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from fastapi import FastAPI
+from src.routes import memories, retrieve, agents
+from src.jobs.decay_job import run as run_decay
+from src.db.migrate import migrate
+
+
+scheduler = AsyncIOScheduler()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    migrate()
+    scheduler.add_job(run_decay, "interval", hours=24, id="decay_job")
+    scheduler.start()
+    yield
+    scheduler.shutdown()
+
+
+app = FastAPI(title="YourMemory", version="0.1.0", lifespan=lifespan)
+
+app.include_router(memories.router)
+app.include_router(retrieve.router)
+app.include_router(agents.router)
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}

src/db/connection.py

@@ -0,0 +1,62 @@
+"""
+Database connection factory.
+
+Auto-detects backend from DATABASE_URL:
+  postgresql:// or postgres://  → PostgreSQL + pgvector
+  sqlite:///path                → SQLite at given path
+  (unset / anything else)       → SQLite at ~/.yourmemory/memories.db  (default)
+
+Usage:
+    from src.db.connection import get_conn, get_backend
+
+    conn = get_conn()    # works for both backends
+    backend = get_backend()   # "sqlite" or "postgres"
+"""
+
+import os
+import sqlite3
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def get_backend() -> str:
+    """Return 'sqlite' or 'postgres' based on DATABASE_URL."""
+    url = os.getenv("DATABASE_URL", "")
+    if url.startswith("postgresql://") or url.startswith("postgres://"):
+        return "postgres"
+    return "sqlite"
+
+
+def _sqlite_path() -> str:
+    """Resolve the SQLite file path."""
+    url = os.getenv("DATABASE_URL", "")
+    if url.startswith("sqlite:///"):
+        return url[10:]
+    path = Path.home() / ".yourmemory" / "memories.db"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return str(path)
+
+
+def get_conn():
+    """Return an open database connection for the configured backend."""
+    if get_backend() == "postgres":
+        import psycopg2
+        return psycopg2.connect(os.getenv("DATABASE_URL"))
+    path = _sqlite_path()
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def emb_to_db(embedding: list, backend: str = None) -> str:
+    """
+    Serialize an embedding list for storage.
+      Postgres: '[0.1,0.2,...]'  (pgvector wire format)
+      SQLite:   JSON string      (stored as TEXT)
+    """
+    import json
+    if (backend or get_backend()) == "postgres":
+        return f"[{','.join(str(x) for x in embedding)}]"
+    return json.dumps(embedding)

src/db/migrate.py

@@ -0,0 +1,32 @@
+import os
+from dotenv import load_dotenv
+from src.db.connection import get_backend, get_conn
+
+load_dotenv()
+
+
+def migrate():
+    backend = get_backend()
+    schema_file = "schema.sql" if backend == "postgres" else "sqlite_schema.sql"
+    schema_path = os.path.join(os.path.dirname(__file__), schema_file)
+
+    with open(schema_path, "r") as f:
+        schema = f.read()
+
+    conn = get_conn()
+    cur = conn.cursor()
+
+    if backend == "sqlite":
+        # executescript handles multiple statements and comments correctly
+        conn.executescript(schema)
+    else:
+        cur.execute(schema)
+        conn.commit()
+
+    cur.close()
+    conn.close()
+    print(f"Migration complete ({backend}).")
+
+
+if __name__ == "__main__":
+    migrate()

src/db/schema.sql

@@ -0,0 +1,53 @@
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS memories (
+    id               SERIAL PRIMARY KEY,
+    user_id          TEXT NOT NULL,
+    content          TEXT NOT NULL,
+    memory_type      TEXT NOT NULL DEFAULT 'trivial',
+    importance       FLOAT NOT NULL DEFAULT 0.5,
+    recall_count     INTEGER NOT NULL DEFAULT 0,
+    last_accessed_at TIMESTAMP DEFAULT NOW(),
+    created_at       TIMESTAMP DEFAULT NOW(),
+    category         TEXT NOT NULL DEFAULT 'fact',
+    agent_id         TEXT NOT NULL DEFAULT 'user',
+    visibility       TEXT NOT NULL DEFAULT 'shared',
+    embedding        vector(768),
+    UNIQUE (user_id, content)
+);
+
+-- Add agent_id and visibility to existing tables (safe to run multiple times)
+DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='memories' AND column_name='agent_id') THEN
+        ALTER TABLE memories ADD COLUMN agent_id TEXT NOT NULL DEFAULT 'user';
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='memories' AND column_name='visibility') THEN
+        ALTER TABLE memories ADD COLUMN visibility TEXT NOT NULL DEFAULT 'shared';
+    END IF;
+END $$;
+
+-- ivfflat index is only useful at scale (10k+ rows).
+-- For small datasets, PostgreSQL does an exact scan automatically.
+-- Uncomment when you have enough data:
+-- CREATE INDEX IF NOT EXISTS memories_embedding_idx
+--     ON memories USING ivfflat (embedding vector_cosine_ops)
+--     WITH (lists = 100);
+
+CREATE INDEX IF NOT EXISTS memories_user_id_idx ON memories (user_id);
+CREATE INDEX IF NOT EXISTS memories_agent_id_idx ON memories (agent_id);
+
+-- Agent registrations — API key auth for multi-agent systems
+CREATE TABLE IF NOT EXISTS agent_registrations (
+    id          SERIAL PRIMARY KEY,
+    agent_id    TEXT UNIQUE NOT NULL,
+    user_id     TEXT NOT NULL,
+    api_key_hash TEXT UNIQUE NOT NULL,   -- SHA-256 hash, never store plaintext
+    can_read    TEXT[] DEFAULT '{}',     -- agent_ids this agent can read from (empty = all shared)
+    can_write   TEXT[] DEFAULT ARRAY['shared', 'private'],
+    description TEXT DEFAULT '',
+    created_at  TIMESTAMP DEFAULT NOW(),
+    revoked_at  TIMESTAMP               -- NULL = active
+);
+
+CREATE INDEX IF NOT EXISTS agent_reg_user_id_idx ON agent_registrations (user_id);
+CREATE INDEX IF NOT EXISTS agent_reg_api_key_idx ON agent_registrations (api_key_hash);

src/db/sqlite_schema.sql

@@ -0,0 +1,38 @@
+-- YourMemory SQLite schema (zero-setup default backend)
+-- Embeddings stored as JSON TEXT; cosine similarity computed in Python.
+
+CREATE TABLE IF NOT EXISTS memories (
+    id               INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id          TEXT NOT NULL,
+    content          TEXT NOT NULL,
+    memory_type      TEXT NOT NULL DEFAULT 'trivial',
+    importance       REAL NOT NULL DEFAULT 0.5,
+    recall_count     INTEGER NOT NULL DEFAULT 0,
+    last_accessed_at TEXT DEFAULT (datetime('now')),
+    created_at       TEXT DEFAULT (datetime('now')),
+    category         TEXT NOT NULL DEFAULT 'fact',
+    agent_id         TEXT NOT NULL DEFAULT 'user',
+    visibility       TEXT NOT NULL DEFAULT 'shared',
+    embedding        TEXT,    -- JSON array of floats (768 dims)
+    UNIQUE (user_id, content)
+);
+
+CREATE INDEX IF NOT EXISTS memories_user_id_idx ON memories (user_id);
+CREATE INDEX IF NOT EXISTS memories_agent_id_idx ON memories (agent_id);
+
+-- Agent registrations — API key auth for multi-agent systems
+-- can_read / can_write stored as JSON arrays (TEXT) instead of Postgres TEXT[]
+CREATE TABLE IF NOT EXISTS agent_registrations (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    agent_id     TEXT UNIQUE NOT NULL,
+    user_id      TEXT NOT NULL,
+    api_key_hash TEXT UNIQUE NOT NULL,
+    can_read     TEXT DEFAULT '[]',
+    can_write    TEXT DEFAULT '["shared", "private"]',
+    description  TEXT DEFAULT '',
+    created_at   TEXT DEFAULT (datetime('now')),
+    revoked_at   TEXT    -- NULL = active
+);
+
+CREATE INDEX IF NOT EXISTS agent_reg_user_id_idx ON agent_registrations (user_id);
+CREATE INDEX IF NOT EXISTS agent_reg_api_key_idx ON agent_registrations (api_key_hash);