@hasna/mementos 0.3.9 → 0.4.2

package/dist/mcp/index.js

@@ -3989,6 +3989,13 @@ var coerce = {
 };
 var NEVER = INVALID;
 // src/types/index.ts
+class EntityNotFoundError extends Error {
+  constructor(id) {
+    super(`Entity not found: ${id}`);
+    this.name = "EntityNotFoundError";
+  }
+}
+
 class MemoryNotFoundError extends Error {
   constructor(id) {
     super(`Memory not found: ${id}`);
@@ -4164,6 +4171,113 @@ var MIGRATIONS = [
   );
 
   INSERT OR IGNORE INTO _migrations (id) VALUES (1);
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS memory_versions (
+    id TEXT PRIMARY KEY,
+    memory_id TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    value TEXT NOT NULL,
+    importance INTEGER NOT NULL,
+    scope TEXT NOT NULL,
+    category TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '[]',
+    summary TEXT,
+    pinned INTEGER NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'active',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(memory_id, version)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_memory_versions_memory ON memory_versions(memory_id);
+  CREATE INDEX IF NOT EXISTS idx_memory_versions_version ON memory_versions(memory_id, version);
+
+  INSERT OR IGNORE INTO _migrations (id) VALUES (2);
+  `,
+  `
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    key, value, summary,
+    content='memories',
+    content_rowid='rowid'
+  );
+
+  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, key, value, summary) VALUES (new.rowid, new.key, new.value, new.summary);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, key, value, summary) VALUES('delete', old.rowid, old.key, old.value, old.summary);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, key, value, summary) VALUES('delete', old.rowid, old.key, old.value, old.summary);
+    INSERT INTO memories_fts(rowid, key, value, summary) VALUES (new.rowid, new.key, new.value, new.summary);
+  END;
+
+  INSERT INTO memories_fts(memories_fts) VALUES('rebuild');
+
+  INSERT OR IGNORE INTO _migrations (id) VALUES (3);
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS search_history (
+    id TEXT PRIMARY KEY,
+    query TEXT NOT NULL,
+    result_count INTEGER NOT NULL DEFAULT 0,
+    agent_id TEXT,
+    project_id TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_search_history_query ON search_history(query);
+  CREATE INDEX IF NOT EXISTS idx_search_history_created ON search_history(created_at);
+
+  INSERT OR IGNORE INTO _migrations (id) VALUES (4);
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS entities (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    type TEXT NOT NULL CHECK (type IN ('person','project','tool','concept','file','api','pattern','organization')),
+    description TEXT,
+    metadata TEXT NOT NULL DEFAULT '{}',
+    project_id TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_unique_name_type_project
+    ON entities(name, type, COALESCE(project_id, ''));
+  CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+  CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+  CREATE INDEX IF NOT EXISTS idx_entities_project ON entities(project_id);
+
+  CREATE TABLE IF NOT EXISTS relations (
+    id TEXT PRIMARY KEY,
+    source_entity_id TEXT NOT NULL,
+    target_entity_id TEXT NOT NULL,
+    relation_type TEXT NOT NULL CHECK (relation_type IN ('uses','knows','depends_on','created_by','related_to','contradicts','part_of','implements')),
+    weight REAL NOT NULL DEFAULT 1.0,
+    metadata TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(source_entity_id, target_entity_id, relation_type),
+    FOREIGN KEY (source_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_entity_id) REFERENCES entities(id) ON DELETE CASCADE
+  );
+  CREATE INDEX IF NOT EXISTS idx_relations_source ON relations(source_entity_id);
+  CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target_entity_id);
+  CREATE INDEX IF NOT EXISTS idx_relations_type ON relations(relation_type);
+
+  CREATE TABLE IF NOT EXISTS entity_memories (
+    entity_id TEXT NOT NULL,
+    memory_id TEXT NOT NULL,
+    role TEXT NOT NULL DEFAULT 'context' CHECK (role IN ('subject','object','context')),
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (entity_id, memory_id),
+    FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+    FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+  );
+  CREATE INDEX IF NOT EXISTS idx_entity_memories_memory ON entity_memories(memory_id);
+
+  INSERT OR IGNORE INTO _migrations (id) VALUES (5);
   `
 ];
 var _db = null;
@@ -4245,7 +4359,650 @@ function redactSecrets(text) {
   return result;
 }
 
+// src/db/agents.ts
+function parseAgentRow(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    description: row["description"] || null,
+    role: row["role"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"],
+    last_seen_at: row["last_seen_at"]
+  };
+}
+function registerAgent(name, description, role, db) {
+  const d = db || getDatabase();
+  const timestamp = now();
+  const normalizedName = name.trim().toLowerCase();
+  const existing = d.query("SELECT * FROM agents WHERE LOWER(name) = ?").get(normalizedName);
+  if (existing) {
+    const existingId = existing["id"];
+    d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [
+      timestamp,
+      existingId
+    ]);
+    if (description) {
+      d.run("UPDATE agents SET description = ? WHERE id = ?", [
+        description,
+        existingId
+      ]);
+    }
+    if (role) {
+      d.run("UPDATE agents SET role = ? WHERE id = ?", [
+        role,
+        existingId
+      ]);
+    }
+    return getAgent(existingId, d);
+  }
+  const id = shortUuid();
+  d.run("INSERT INTO agents (id, name, description, role, created_at, last_seen_at) VALUES (?, ?, ?, ?, ?, ?)", [id, normalizedName, description || null, role || "agent", timestamp, timestamp]);
+  return getAgent(id, d);
+}
+function getAgent(idOrName, db) {
+  const d = db || getDatabase();
+  let row = d.query("SELECT * FROM agents WHERE id = ?").get(idOrName);
+  if (row)
+    return parseAgentRow(row);
+  row = d.query("SELECT * FROM agents WHERE LOWER(name) = ?").get(idOrName.trim().toLowerCase());
+  if (row)
+    return parseAgentRow(row);
+  const rows = d.query("SELECT * FROM agents WHERE id LIKE ?").all(`${idOrName}%`);
+  if (rows.length === 1)
+    return parseAgentRow(rows[0]);
+  return null;
+}
+function listAgents(db) {
+  const d = db || getDatabase();
+  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  return rows.map(parseAgentRow);
+}
+function updateAgent(id, updates, db) {
+  const d = db || getDatabase();
+  const agent = getAgent(id, d);
+  if (!agent)
+    return null;
+  const timestamp = now();
+  if (updates.name) {
+    const normalizedNewName = updates.name.trim().toLowerCase();
+    if (normalizedNewName !== agent.name) {
+      const existing = d.query("SELECT id FROM agents WHERE LOWER(name) = ? AND id != ?").get(normalizedNewName, agent.id);
+      if (existing) {
+        throw new Error(`Agent name already taken: ${normalizedNewName}`);
+      }
+      d.run("UPDATE agents SET name = ? WHERE id = ?", [normalizedNewName, agent.id]);
+    }
+  }
+  if (updates.description !== undefined) {
+    d.run("UPDATE agents SET description = ? WHERE id = ?", [updates.description, agent.id]);
+  }
+  if (updates.role !== undefined) {
+    d.run("UPDATE agents SET role = ? WHERE id = ?", [updates.role, agent.id]);
+  }
+  if (updates.metadata !== undefined) {
+    d.run("UPDATE agents SET metadata = ? WHERE id = ?", [JSON.stringify(updates.metadata), agent.id]);
+  }
+  d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [timestamp, agent.id]);
+  return getAgent(agent.id, d);
+}
+
+// src/db/projects.ts
+function parseProjectRow(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    path: row["path"],
+    description: row["description"] || null,
+    memory_prefix: row["memory_prefix"] || null,
+    created_at: row["created_at"],
+    updated_at: row["updated_at"]
+  };
+}
+function registerProject(name, path, description, memoryPrefix, db) {
+  const d = db || getDatabase();
+  const timestamp = now();
+  const existing = d.query("SELECT * FROM projects WHERE path = ?").get(path);
+  if (existing) {
+    const existingId = existing["id"];
+    d.run("UPDATE projects SET updated_at = ? WHERE id = ?", [
+      timestamp,
+      existingId
+    ]);
+    return parseProjectRow(existing);
+  }
+  const id = uuid();
+  d.run("INSERT INTO projects (id, name, path, description, memory_prefix, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)", [id, name, path, description || null, memoryPrefix || null, timestamp, timestamp]);
+  return getProject(id, d);
+}
+function getProject(idOrPath, db) {
+  const d = db || getDatabase();
+  let row = d.query("SELECT * FROM projects WHERE id = ?").get(idOrPath);
+  if (row)
+    return parseProjectRow(row);
+  row = d.query("SELECT * FROM projects WHERE path = ?").get(idOrPath);
+  if (row)
+    return parseProjectRow(row);
+  return null;
+}
+function listProjects(db) {
+  const d = db || getDatabase();
+  const rows = d.query("SELECT * FROM projects ORDER BY updated_at DESC").all();
+  return rows.map(parseProjectRow);
+}
+
+// src/lib/extractor.ts
+var TECH_KEYWORDS = new Set([
+  "typescript",
+  "javascript",
+  "python",
+  "rust",
+  "go",
+  "java",
+  "ruby",
+  "swift",
+  "kotlin",
+  "react",
+  "vue",
+  "angular",
+  "svelte",
+  "nextjs",
+  "bun",
+  "node",
+  "deno",
+  "sqlite",
+  "postgres",
+  "mysql",
+  "redis",
+  "docker",
+  "kubernetes",
+  "git",
+  "npm",
+  "yarn",
+  "pnpm",
+  "webpack",
+  "vite",
+  "tailwind",
+  "prisma",
+  "drizzle",
+  "zod",
+  "commander",
+  "express",
+  "fastify",
+  "hono"
+]);
+var FILE_PATH_RE = /(?:^|\s)((?:\/|\.\/|~\/)?(?:[\w.-]+\/)+[\w.-]+\.\w+)/g;
+var URL_RE = /https?:\/\/[^\s)]+/g;
+var NPM_PACKAGE_RE = /@[\w-]+\/[\w.-]+/g;
+var PASCAL_CASE_RE = /\b([A-Z][a-z]+(?:[A-Z][a-z]+)+)\b/g;
+function getSearchText(memory) {
+  const parts = [memory.key, memory.value];
+  if (memory.summary)
+    parts.push(memory.summary);
+  return parts.join(" ");
+}
+function extractEntities(memory, db) {
+  const text = getSearchText(memory);
+  const entityMap = new Map;
+  function add(name, type, confidence) {
+    const normalized = name.toLowerCase();
+    if (normalized.length < 3)
+      return;
+    const existing = entityMap.get(normalized);
+    if (!existing || existing.confidence < confidence) {
+      entityMap.set(normalized, { name: normalized, type, confidence });
+    }
+  }
+  for (const match of text.matchAll(FILE_PATH_RE)) {
+    add(match[1].trim(), "file", 0.9);
+  }
+  for (const match of text.matchAll(URL_RE)) {
+    add(match[0], "api", 0.8);
+  }
+  for (const match of text.matchAll(NPM_PACKAGE_RE)) {
+    add(match[0], "tool", 0.85);
+  }
+  try {
+    const d = db || getDatabase();
+    const agents = listAgents(d);
+    const textLower2 = text.toLowerCase();
+    for (const agent of agents) {
+      const nameLower = agent.name.toLowerCase();
+      if (nameLower.length >= 3 && textLower2.includes(nameLower)) {
+        add(agent.name, "person", 0.95);
+      }
+    }
+  } catch {}
+  try {
+    const d = db || getDatabase();
+    const projects = listProjects(d);
+    const textLower2 = text.toLowerCase();
+    for (const project of projects) {
+      const nameLower = project.name.toLowerCase();
+      if (nameLower.length >= 3 && textLower2.includes(nameLower)) {
+        add(project.name, "project", 0.95);
+      }
+    }
+  } catch {}
+  const textLower = text.toLowerCase();
+  for (const keyword of TECH_KEYWORDS) {
+    const re = new RegExp(`\\b${keyword}\\b`, "i");
+    if (re.test(textLower)) {
+      add(keyword, "tool", 0.7);
+    }
+  }
+  for (const match of text.matchAll(PASCAL_CASE_RE)) {
+    add(match[1], "concept", 0.5);
+  }
+  return Array.from(entityMap.values()).sort((a, b) => b.confidence - a.confidence);
+}
+
+// src/db/entities.ts
+function parseEntityRow(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    type: row["type"],
+    description: row["description"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    project_id: row["project_id"] || null,
+    created_at: row["created_at"],
+    updated_at: row["updated_at"]
+  };
+}
+function createEntity(input, db) {
+  const d = db || getDatabase();
+  const timestamp = now();
+  const metadataJson = JSON.stringify(input.metadata || {});
+  const existing = d.query(`SELECT * FROM entities
+       WHERE name = ? AND type = ? AND COALESCE(project_id, '') = ?`).get(input.name, input.type, input.project_id || "");
+  if (existing) {
+    const sets = ["updated_at = ?"];
+    const params = [timestamp];
+    if (input.description !== undefined) {
+      sets.push("description = ?");
+      params.push(input.description);
+    }
+    if (input.metadata !== undefined) {
+      sets.push("metadata = ?");
+      params.push(metadataJson);
+    }
+    const existingId = existing["id"];
+    params.push(existingId);
+    d.run(`UPDATE entities SET ${sets.join(", ")} WHERE id = ?`, params);
+    return getEntity(existingId, d);
+  }
+  const id = shortUuid();
+  d.run(`INSERT INTO entities (id, name, type, description, metadata, project_id, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+    id,
+    input.name,
+    input.type,
+    input.description || null,
+    metadataJson,
+    input.project_id || null,
+    timestamp,
+    timestamp
+  ]);
+  return getEntity(id, d);
+}
+function getEntity(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM entities WHERE id = ?").get(id);
+  if (!row)
+    throw new EntityNotFoundError(id);
+  return parseEntityRow(row);
+}
+function getEntityByName(name, type, projectId, db) {
+  const d = db || getDatabase();
+  let sql = "SELECT * FROM entities WHERE name = ?";
+  const params = [name];
+  if (type) {
+    sql += " AND type = ?";
+    params.push(type);
+  }
+  if (projectId !== undefined) {
+    sql += " AND project_id = ?";
+    params.push(projectId);
+  }
+  sql += " LIMIT 1";
+  const row = d.query(sql).get(...params);
+  if (!row)
+    return null;
+  return parseEntityRow(row);
+}
+function listEntities(filter = {}, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filter.type) {
+    conditions.push("type = ?");
+    params.push(filter.type);
+  }
+  if (filter.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filter.project_id);
+  }
+  if (filter.search) {
+    conditions.push("(name LIKE ? OR description LIKE ?)");
+    const term = `%${filter.search}%`;
+    params.push(term, term);
+  }
+  let sql = "SELECT * FROM entities";
+  if (conditions.length > 0) {
+    sql += ` WHERE ${conditions.join(" AND ")}`;
+  }
+  sql += " ORDER BY updated_at DESC";
+  if (filter.limit) {
+    sql += " LIMIT ?";
+    params.push(filter.limit);
+  }
+  if (filter.offset) {
+    sql += " OFFSET ?";
+    params.push(filter.offset);
+  }
+  const rows = d.query(sql).all(...params);
+  return rows.map(parseEntityRow);
+}
+function deleteEntity(id, db) {
+  const d = db || getDatabase();
+  const result = d.run("DELETE FROM entities WHERE id = ?", [id]);
+  if (result.changes === 0)
+    throw new EntityNotFoundError(id);
+}
+function mergeEntities(sourceId, targetId, db) {
+  const d = db || getDatabase();
+  getEntity(sourceId, d);
+  getEntity(targetId, d);
+  d.run(`UPDATE OR IGNORE relations SET source_entity_id = ? WHERE source_entity_id = ?`, [targetId, sourceId]);
+  d.run(`UPDATE OR IGNORE relations SET target_entity_id = ? WHERE target_entity_id = ?`, [targetId, sourceId]);
+  d.run("DELETE FROM relations WHERE source_entity_id = ? OR target_entity_id = ?", [
+    sourceId,
+    sourceId
+  ]);
+  d.run(`UPDATE OR IGNORE entity_memories SET entity_id = ? WHERE entity_id = ?`, [targetId, sourceId]);
+  d.run("DELETE FROM entity_memories WHERE entity_id = ?", [sourceId]);
+  d.run("DELETE FROM entities WHERE id = ?", [sourceId]);
+  d.run("UPDATE entities SET updated_at = ? WHERE id = ?", [now(), targetId]);
+  return getEntity(targetId, d);
+}
+
+// src/db/entity-memories.ts
+function parseEntityMemoryRow(row) {
+  return {
+    entity_id: row["entity_id"],
+    memory_id: row["memory_id"],
+    role: row["role"],
+    created_at: row["created_at"]
+  };
+}
+function linkEntityToMemory(entityId, memoryId, role = "context", db) {
+  const d = db || getDatabase();
+  const timestamp = now();
+  d.run(`INSERT OR IGNORE INTO entity_memories (entity_id, memory_id, role, created_at)
+     VALUES (?, ?, ?, ?)`, [entityId, memoryId, role, timestamp]);
+  const row = d.query("SELECT * FROM entity_memories WHERE entity_id = ? AND memory_id = ?").get(entityId, memoryId);
+  return parseEntityMemoryRow(row);
+}
+function unlinkEntityFromMemory(entityId, memoryId, db) {
+  const d = db || getDatabase();
+  d.run("DELETE FROM entity_memories WHERE entity_id = ? AND memory_id = ?", [entityId, memoryId]);
+}
+function getMemoriesForEntity(entityId, db) {
+  const d = db || getDatabase();
+  const rows = d.query(`SELECT m.* FROM memories m
+       INNER JOIN entity_memories em ON em.memory_id = m.id
+       WHERE em.entity_id = ?
+       ORDER BY m.importance DESC, m.created_at DESC`).all(entityId);
+  return rows.map(parseMemoryRow);
+}
+function getEntityMemoryLinks(entityId, memoryId, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (entityId) {
+    conditions.push("entity_id = ?");
+    params.push(entityId);
+  }
+  if (memoryId) {
+    conditions.push("memory_id = ?");
+    params.push(memoryId);
+  }
+  let sql = "SELECT * FROM entity_memories";
+  if (conditions.length > 0) {
+    sql += ` WHERE ${conditions.join(" AND ")}`;
+  }
+  sql += " ORDER BY created_at DESC";
+  const rows = d.query(sql).all(...params);
+  return rows.map(parseEntityMemoryRow);
+}
+
+// src/db/relations.ts
+function parseRelationRow(row) {
+  return {
+    id: row["id"],
+    source_entity_id: row["source_entity_id"],
+    target_entity_id: row["target_entity_id"],
+    relation_type: row["relation_type"],
+    weight: row["weight"],
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"]
+  };
+}
+function parseEntityRow2(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    type: row["type"],
+    description: row["description"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    project_id: row["project_id"] || null,
+    created_at: row["created_at"],
+    updated_at: row["updated_at"]
+  };
+}
+function createRelation(input, db) {
+  const d = db || getDatabase();
+  const id = shortUuid();
+  const timestamp = now();
+  const weight = input.weight ?? 1;
+  const metadata = JSON.stringify(input.metadata ?? {});
+  d.run(`INSERT INTO relations (id, source_entity_id, target_entity_id, relation_type, weight, metadata, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(source_entity_id, target_entity_id, relation_type)
+     DO UPDATE SET weight = excluded.weight, metadata = excluded.metadata`, [id, input.source_entity_id, input.target_entity_id, input.relation_type, weight, metadata, timestamp]);
+  const row = d.query(`SELECT * FROM relations
+       WHERE source_entity_id = ? AND target_entity_id = ? AND relation_type = ?`).get(input.source_entity_id, input.target_entity_id, input.relation_type);
+  return parseRelationRow(row);
+}
+function listRelations(filter, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filter.entity_id) {
+    const dir = filter.direction || "both";
+    if (dir === "outgoing") {
+      conditions.push("source_entity_id = ?");
+      params.push(filter.entity_id);
+    } else if (dir === "incoming") {
+      conditions.push("target_entity_id = ?");
+      params.push(filter.entity_id);
+    } else {
+      conditions.push("(source_entity_id = ? OR target_entity_id = ?)");
+      params.push(filter.entity_id, filter.entity_id);
+    }
+  }
+  if (filter.relation_type) {
+    conditions.push("relation_type = ?");
+    params.push(filter.relation_type);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = d.query(`SELECT * FROM relations ${where} ORDER BY created_at DESC`).all(...params);
+  return rows.map(parseRelationRow);
+}
+function deleteRelation(id, db) {
+  const d = db || getDatabase();
+  const result = d.run("DELETE FROM relations WHERE id = ?", [id]);
+  if (result.changes === 0)
+    throw new Error(`Relation not found: ${id}`);
+}
+function getEntityGraph(entityId, depth = 2, db) {
+  const d = db || getDatabase();
+  const entityRows = d.query(`WITH RECURSIVE graph(id, depth) AS (
+        VALUES(?, 0)
+        UNION
+        SELECT CASE WHEN r.source_entity_id = g.id THEN r.target_entity_id ELSE r.source_entity_id END, g.depth + 1
+        FROM relations r JOIN graph g ON (r.source_entity_id = g.id OR r.target_entity_id = g.id)
+        WHERE g.depth < ?
+      )
+      SELECT DISTINCT e.* FROM entities e JOIN graph g ON e.id = g.id`).all(entityId, depth);
+  const entities = entityRows.map(parseEntityRow2);
+  const entityIds = new Set(entities.map((e) => e.id));
+  if (entityIds.size === 0) {
+    return { entities: [], relations: [] };
+  }
+  const placeholders = Array.from(entityIds).map(() => "?").join(",");
+  const relationRows = d.query(`SELECT * FROM relations
+       WHERE source_entity_id IN (${placeholders})
+         AND target_entity_id IN (${placeholders})`).all(...Array.from(entityIds), ...Array.from(entityIds));
+  const relations = relationRows.map(parseRelationRow);
+  return { entities, relations };
+}
+function findPath(fromEntityId, toEntityId, maxDepth = 5, db) {
+  const d = db || getDatabase();
+  const rows = d.query(`WITH RECURSIVE path(id, trail, depth) AS (
+        SELECT ?, ?, 0
+        UNION
+        SELECT
+          CASE WHEN r.source_entity_id = p.id THEN r.target_entity_id ELSE r.source_entity_id END,
+          p.trail || ',' || CASE WHEN r.source_entity_id = p.id THEN r.target_entity_id ELSE r.source_entity_id END,
+          p.depth + 1
+        FROM relations r JOIN path p ON (r.source_entity_id = p.id OR r.target_entity_id = p.id)
+        WHERE p.depth < ?
+          AND INSTR(p.trail, CASE WHEN r.source_entity_id = p.id THEN r.target_entity_id ELSE r.source_entity_id END) = 0
+      )
+      SELECT trail FROM path WHERE id = ? ORDER BY depth ASC LIMIT 1`).get(fromEntityId, fromEntityId, maxDepth, toEntityId);
+  if (!rows)
+    return null;
+  const ids = rows.trail.split(",");
+  const entities = [];
+  for (const id of ids) {
+    const row = d.query("SELECT * FROM entities WHERE id = ?").get(id);
+    if (row)
+      entities.push(parseEntityRow2(row));
+  }
+  return entities.length > 0 ? entities : null;
+}
+
+// src/lib/config.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+var DEFAULT_CONFIG = {
+  default_scope: "private",
+  default_category: "knowledge",
+  default_importance: 5,
+  max_entries: 1000,
+  max_entries_per_scope: {
+    global: 500,
+    shared: 300,
+    private: 200
+  },
+  injection: {
+    max_tokens: 500,
+    min_importance: 5,
+    categories: ["preference", "fact"],
+    refresh_interval: 5
+  },
+  extraction: {
+    enabled: true,
+    min_confidence: 0.5
+  },
+  sync_agents: ["claude", "codex", "gemini"],
+  auto_cleanup: {
+    enabled: true,
+    expired_check_interval: 3600,
+    unused_archive_days: 7,
+    stale_deprioritize_days: 14
+  }
+};
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = result[key];
+    if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
+      result[key] = deepMerge(targetVal, sourceVal);
+    } else {
+      result[key] = sourceVal;
+    }
+  }
+  return result;
+}
+var VALID_SCOPES = ["global", "shared", "private"];
+var VALID_CATEGORIES = [
+  "preference",
+  "fact",
+  "knowledge",
+  "history"
+];
+function isValidScope(value) {
+  return VALID_SCOPES.includes(value);
+}
+function isValidCategory(value) {
+  return VALID_CATEGORIES.includes(value);
+}
+function loadConfig() {
+  const configPath = join2(homedir(), ".mementos", "config.json");
+  let fileConfig = {};
+  if (existsSync2(configPath)) {
+    try {
+      const raw = readFileSync(configPath, "utf-8");
+      fileConfig = JSON.parse(raw);
+    } catch {}
+  }
+  const merged = deepMerge(DEFAULT_CONFIG, fileConfig);
+  const envScope = process.env["MEMENTOS_DEFAULT_SCOPE"];
+  if (envScope && isValidScope(envScope)) {
+    merged.default_scope = envScope;
+  }
+  const envCategory = process.env["MEMENTOS_DEFAULT_CATEGORY"];
+  if (envCategory && isValidCategory(envCategory)) {
+    merged.default_category = envCategory;
+  }
+  const envImportance = process.env["MEMENTOS_DEFAULT_IMPORTANCE"];
+  if (envImportance) {
+    const parsed = parseInt(envImportance, 10);
+    if (!Number.isNaN(parsed) && parsed >= 1 && parsed <= 10) {
+      merged.default_importance = parsed;
+    }
+  }
+  return merged;
+}
+
 // src/db/memories.ts
+function runEntityExtraction(memory, projectId, d) {
+  const config = loadConfig();
+  if (config.extraction?.enabled === false)
+    return;
+  const extracted = extractEntities(memory, d);
+  const minConfidence = config.extraction?.min_confidence ?? 0.5;
+  const entityIds = [];
+  for (const ext of extracted) {
+    if (ext.confidence >= minConfidence) {
+      const entity = createEntity({ name: ext.name, type: ext.type, project_id: projectId }, d);
+      linkEntityToMemory(entity.id, memory.id, "context", d);
+      entityIds.push(entity.id);
+    }
+  }
+  for (let i = 0;i < entityIds.length; i++) {
+    for (let j = i + 1;j < entityIds.length; j++) {
+      try {
+        createRelation({ source_entity_id: entityIds[i], target_entity_id: entityIds[j], relation_type: "related_to" }, d);
+      } catch {}
+    }
+  }
+}
 function parseMemoryRow(row) {
   return {
     id: row["id"],
@@ -4312,7 +5069,15 @@ function createMemory(input, dedupeMode = "merge", db) {
       for (const tag of tags) {
         insertTag2.run(existing.id, tag);
       }
-      return getMemory(existing.id, d);
+      const merged = getMemory(existing.id, d);
+      try {
+        const oldLinks = getEntityMemoryLinks(undefined, merged.id, d);
+        for (const link of oldLinks) {
+          unlinkEntityFromMemory(link.entity_id, merged.id, d);
+        }
+        runEntityExtraction(merged, input.project_id, d);
+      } catch {}
+      return merged;
     }
   }
   d.run(`INSERT INTO memories (id, key, value, category, scope, summary, tags, importance, source, status, pinned, agent_id, project_id, session_id, metadata, access_count, version, expires_at, created_at, updated_at)
@@ -4338,7 +5103,11 @@ function createMemory(input, dedupeMode = "merge", db) {
   for (const tag of tags) {
     insertTag.run(id, tag);
   }
-  return getMemory(id, d);
+  const memory = getMemory(id, d);
+  try {
+    runEntityExtraction(memory, input.project_id, d);
+  } catch {}
+  return memory;
 }
 function getMemory(id, db) {
   const d = db || getDatabase();
@@ -4474,6 +5243,23 @@ function updateMemory(id, input, db) {
   if (existing.version !== input.version) {
     throw new VersionConflictError(id, input.version, existing.version);
   }
+  try {
+    d.run(`INSERT OR IGNORE INTO memory_versions (id, memory_id, version, value, importance, scope, category, tags, summary, pinned, status, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      uuid(),
+      existing.id,
+      existing.version,
+      existing.value,
+      existing.importance,
+      existing.scope,
+      existing.category,
+      JSON.stringify(existing.tags),
+      existing.summary,
+      existing.pinned ? 1 : 0,
+      existing.status,
+      existing.updated_at
+    ]);
+  } catch {}
   const sets = ["version = version + 1", "updated_at = ?"];
   const params = [now()];
   if (input.value !== undefined) {
@@ -4523,7 +5309,17 @@ function updateMemory(id, input, db) {
   }
   params.push(id);
   d.run(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`, params);
-  return getMemory(id, d);
+  const updated = getMemory(id, d);
+  try {
+    if (input.value !== undefined) {
+      const oldLinks = getEntityMemoryLinks(undefined, updated.id, d);
+      for (const link of oldLinks) {
+        unlinkEntityFromMemory(link.entity_id, updated.id, d);
+      }
+      runEntityExtraction(updated, existing.project_id || undefined, d);
+    }
+  } catch {}
+  return updated;
 }
 function deleteMemory(id, db) {
   const d = db || getDatabase();
@@ -4535,8 +5331,12 @@ function bulkDeleteMemories(ids, db) {
   if (ids.length === 0)
     return 0;
   const placeholders = ids.map(() => "?").join(",");
-  const result = d.run(`DELETE FROM memories WHERE id IN (${placeholders})`, ids);
-  return result.changes;
+  const countRow = d.query(`SELECT COUNT(*) as c FROM memories WHERE id IN (${placeholders})`).get(...ids);
+  const count = countRow.c;
+  if (count > 0) {
+    d.run(`DELETE FROM memories WHERE id IN (${placeholders})`, ids);
+  }
+  return count;
 }
 function touchMemory(id, db) {
   const d = db || getDatabase();
@@ -4545,136 +5345,12 @@ function touchMemory(id, db) {
 function cleanExpiredMemories(db) {
   const d = db || getDatabase();
   const timestamp = now();
-  const result = d.run("DELETE FROM memories WHERE expires_at IS NOT NULL AND expires_at < ?", [timestamp]);
-  return result.changes;
-}
-
-// src/db/agents.ts
-function parseAgentRow(row) {
-  return {
-    id: row["id"],
-    name: row["name"],
-    description: row["description"] || null,
-    role: row["role"] || null,
-    metadata: JSON.parse(row["metadata"] || "{}"),
-    created_at: row["created_at"],
-    last_seen_at: row["last_seen_at"]
-  };
-}
-function registerAgent(name, description, role, db) {
-  const d = db || getDatabase();
-  const timestamp = now();
-  const existing = d.query("SELECT * FROM agents WHERE name = ?").get(name);
-  if (existing) {
-    const existingId = existing["id"];
-    d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [
-      timestamp,
-      existingId
-    ]);
-    if (description) {
-      d.run("UPDATE agents SET description = ? WHERE id = ?", [
-        description,
-        existingId
-      ]);
-    }
-    if (role) {
-      d.run("UPDATE agents SET role = ? WHERE id = ?", [
-        role,
-        existingId
-      ]);
-    }
-    return getAgent(existingId, d);
-  }
-  const id = shortUuid();
-  d.run("INSERT INTO agents (id, name, description, role, created_at, last_seen_at) VALUES (?, ?, ?, ?, ?, ?)", [id, name, description || null, role || "agent", timestamp, timestamp]);
-  return getAgent(id, d);
-}
-function getAgent(idOrName, db) {
-  const d = db || getDatabase();
-  let row = d.query("SELECT * FROM agents WHERE id = ?").get(idOrName);
-  if (row)
-    return parseAgentRow(row);
-  row = d.query("SELECT * FROM agents WHERE name = ?").get(idOrName);
-  if (row)
-    return parseAgentRow(row);
-  const rows = d.query("SELECT * FROM agents WHERE id LIKE ?").all(`${idOrName}%`);
-  if (rows.length === 1)
-    return parseAgentRow(rows[0]);
-  return null;
-}
-function listAgents(db) {
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
-  return rows.map(parseAgentRow);
-}
-function updateAgent(id, updates, db) {
-  const d = db || getDatabase();
-  const agent = getAgent(id, d);
-  if (!agent)
-    return null;
-  const timestamp = now();
-  if (updates.name && updates.name !== agent.name) {
-    const existing = d.query("SELECT id FROM agents WHERE name = ? AND id != ?").get(updates.name, agent.id);
-    if (existing) {
-      throw new Error(`Agent name already taken: ${updates.name}`);
-    }
-    d.run("UPDATE agents SET name = ? WHERE id = ?", [updates.name, agent.id]);
+  const countRow = d.query("SELECT COUNT(*) as c FROM memories WHERE expires_at IS NOT NULL AND expires_at < ?").get(timestamp);
+  const count = countRow.c;
+  if (count > 0) {
+    d.run("DELETE FROM memories WHERE expires_at IS NOT NULL AND expires_at < ?", [timestamp]);
   }
-  if (updates.description !== undefined) {
-    d.run("UPDATE agents SET description = ? WHERE id = ?", [updates.description, agent.id]);
-  }
-  if (updates.role !== undefined) {
-    d.run("UPDATE agents SET role = ? WHERE id = ?", [updates.role, agent.id]);
-  }
-  if (updates.metadata !== undefined) {
-    d.run("UPDATE agents SET metadata = ? WHERE id = ?", [JSON.stringify(updates.metadata), agent.id]);
-  }
-  d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [timestamp, agent.id]);
-  return getAgent(agent.id, d);
-}
-
-// src/db/projects.ts
-function parseProjectRow(row) {
-  return {
-    id: row["id"],
-    name: row["name"],
-    path: row["path"],
-    description: row["description"] || null,
-    memory_prefix: row["memory_prefix"] || null,
-    created_at: row["created_at"],
-    updated_at: row["updated_at"]
-  };
-}
-function registerProject(name, path, description, memoryPrefix, db) {
-  const d = db || getDatabase();
-  const timestamp = now();
-  const existing = d.query("SELECT * FROM projects WHERE path = ?").get(path);
-  if (existing) {
-    const existingId = existing["id"];
-    d.run("UPDATE projects SET updated_at = ? WHERE id = ?", [
-      timestamp,
-      existingId
-    ]);
-    return parseProjectRow(existing);
-  }
-  const id = uuid();
-  d.run("INSERT INTO projects (id, name, path, description, memory_prefix, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)", [id, name, path, description || null, memoryPrefix || null, timestamp, timestamp]);
-  return getProject(id, d);
-}
-function getProject(idOrPath, db) {
-  const d = db || getDatabase();
-  let row = d.query("SELECT * FROM projects WHERE id = ?").get(idOrPath);
-  if (row)
-    return parseProjectRow(row);
-  row = d.query("SELECT * FROM projects WHERE path = ?").get(idOrPath);
-  if (row)
-    return parseProjectRow(row);
-  return null;
-}
-function listProjects(db) {
-  const d = db || getDatabase();
-  const rows = d.query("SELECT * FROM projects ORDER BY updated_at DESC").all();
-  return rows.map(parseProjectRow);
+  return count;
 }
 
 // src/lib/search.ts
@@ -4703,109 +5379,442 @@ function parseMemoryRow2(row) {
     accessed_at: row["accessed_at"] || null
   };
 }
+function preprocessQuery(query) {
+  let q = query.trim();
+  q = q.replace(/\s+/g, " ");
+  q = q.normalize("NFC");
+  return q;
+}
+function escapeLikePattern(s) {
+  return s.replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+var STOP_WORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "need",
+  "dare",
+  "ought",
+  "used",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "between",
+  "out",
+  "off",
+  "over",
+  "under",
+  "again",
+  "further",
+  "then",
+  "once",
+  "here",
+  "there",
+  "when",
+  "where",
+  "why",
+  "how",
+  "all",
+  "each",
+  "every",
+  "both",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "no",
+  "not",
+  "only",
+  "own",
+  "same",
+  "so",
+  "than",
+  "too",
+  "very",
+  "just",
+  "because",
+  "but",
+  "and",
+  "or",
+  "if",
+  "while",
+  "that",
+  "this",
+  "it"
+]);
+function removeStopWords(tokens) {
+  if (tokens.length <= 1)
+    return tokens;
+  const filtered = tokens.filter((t) => !STOP_WORDS.has(t.toLowerCase()));
+  return filtered.length > 0 ? filtered : tokens;
+}
+function extractHighlights(memory, queryLower) {
+  const highlights = [];
+  const tokens = queryLower.split(/\s+/).filter(Boolean);
+  for (const field of ["key", "value", "summary"]) {
+    const text = field === "summary" ? memory.summary : memory[field];
+    if (!text)
+      continue;
+    const textLower = text.toLowerCase();
+    const searchTerms = [queryLower, ...tokens].filter(Boolean);
+    for (const term of searchTerms) {
+      const idx = textLower.indexOf(term);
+      if (idx !== -1) {
+        const start = Math.max(0, idx - 30);
+        const end = Math.min(text.length, idx + term.length + 30);
+        const prefix = start > 0 ? "..." : "";
+        const suffix = end < text.length ? "..." : "";
+        highlights.push({
+          field,
+          snippet: prefix + text.slice(start, end) + suffix
+        });
+        break;
+      }
+    }
+  }
+  for (const tag of memory.tags) {
+    if (tag.toLowerCase().includes(queryLower) || tokens.some((t) => tag.toLowerCase().includes(t))) {
+      highlights.push({ field: "tag", snippet: tag });
+    }
+  }
+  return highlights;
+}
 function determineMatchType(memory, queryLower) {
   if (memory.key.toLowerCase() === queryLower)
     return "exact";
   if (memory.tags.some((t) => t.toLowerCase() === queryLower))
     return "tag";
+  if (memory.tags.some((t) => t.toLowerCase().includes(queryLower)))
+    return "tag";
   return "fuzzy";
 }
 function computeScore(memory, queryLower) {
-  let score = 0;
+  const fieldScores = [];
   const keyLower = memory.key.toLowerCase();
   if (keyLower === queryLower) {
-    score += 10;
+    fieldScores.push(10);
   } else if (keyLower.includes(queryLower)) {
-    score += 7;
+    fieldScores.push(7);
   }
   if (memory.tags.some((t) => t.toLowerCase() === queryLower)) {
-    score += 6;
+    fieldScores.push(6);
+  } else if (memory.tags.some((t) => t.toLowerCase().includes(queryLower))) {
+    fieldScores.push(3);
   }
   if (memory.summary && memory.summary.toLowerCase().includes(queryLower)) {
-    score += 4;
+    fieldScores.push(4);
   }
   if (memory.value.toLowerCase().includes(queryLower)) {
-    score += 3;
+    fieldScores.push(3);
+  }
+  const metadataStr = JSON.stringify(memory.metadata).toLowerCase();
+  if (metadataStr !== "{}" && metadataStr.includes(queryLower)) {
+    fieldScores.push(2);
+  }
+  fieldScores.sort((a, b) => b - a);
+  const diminishingMultipliers = [1, 0.5, 0.25, 0.15, 0.15];
+  let score = 0;
+  for (let i = 0;i < fieldScores.length; i++) {
+    score += fieldScores[i] * (diminishingMultipliers[i] ?? 0.15);
+  }
+  const { phrases } = extractQuotedPhrases(queryLower);
+  for (const phrase of phrases) {
+    if (keyLower.includes(phrase))
+      score += 8;
+    if (memory.value.toLowerCase().includes(phrase))
+      score += 5;
+    if (memory.summary && memory.summary.toLowerCase().includes(phrase))
+      score += 4;
+  }
+  const { remainder } = extractQuotedPhrases(queryLower);
+  const tokens = removeStopWords(remainder.split(/\s+/).filter(Boolean));
+  if (tokens.length > 1) {
+    let tokenScore = 0;
+    for (const token of tokens) {
+      if (keyLower === token) {
+        tokenScore += 10 / tokens.length;
+      } else if (keyLower.includes(token)) {
+        tokenScore += 7 / tokens.length;
+      }
+      if (memory.tags.some((t) => t.toLowerCase() === token)) {
+        tokenScore += 6 / tokens.length;
+      } else if (memory.tags.some((t) => t.toLowerCase().includes(token))) {
+        tokenScore += 3 / tokens.length;
+      }
+      if (memory.summary && memory.summary.toLowerCase().includes(token)) {
+        tokenScore += 4 / tokens.length;
+      }
+      if (memory.value.toLowerCase().includes(token)) {
+        tokenScore += 3 / tokens.length;
+      }
+      if (metadataStr !== "{}" && metadataStr.includes(token)) {
+        tokenScore += 2 / tokens.length;
+      }
+    }
+    if (score > 0) {
+      score += tokenScore * 0.3;
+    } else {
+      score += tokenScore;
+    }
   }
   return score;
 }
-function searchMemories(query, filter, db) {
-  const d = db || getDatabase();
-  const queryLower = query.toLowerCase();
-  const queryParam = `%${query}%`;
+function extractQuotedPhrases(query) {
+  const phrases = [];
+  const remainder = query.replace(/"([^"]+)"/g, (_match, phrase) => {
+    phrases.push(phrase);
+    return "";
+  });
+  return { phrases, remainder: remainder.trim() };
+}
+function escapeFts5Query(query) {
+  const { phrases, remainder } = extractQuotedPhrases(query);
+  const parts = [];
+  for (const phrase of phrases) {
+    parts.push(`"${phrase.replace(/"/g, '""')}"`);
+  }
+  const tokens = removeStopWords(remainder.split(/\s+/).filter(Boolean));
+  for (const t of tokens) {
+    parts.push(`"${t.replace(/"/g, '""')}"`);
+  }
+  return parts.join(" ");
+}
+function hasFts5Table(d) {
+  try {
+    const row = d.query("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+    return !!row;
+  } catch {
+    return false;
+  }
+}
+function buildFilterConditions(filter) {
   const conditions = [];
   const params = [];
   conditions.push("m.status = 'active'");
   conditions.push("(m.expires_at IS NULL OR m.expires_at >= datetime('now'))");
-  conditions.push(`(m.key LIKE ? OR m.value LIKE ? OR m.summary LIKE ? OR m.id IN (SELECT memory_id FROM memory_tags WHERE tag LIKE ?))`);
-  params.push(queryParam, queryParam, queryParam, queryParam);
-  if (filter) {
-    if (filter.scope) {
-      if (Array.isArray(filter.scope)) {
-        conditions.push(`m.scope IN (${filter.scope.map(() => "?").join(",")})`);
-        params.push(...filter.scope);
-      } else {
-        conditions.push("m.scope = ?");
-        params.push(filter.scope);
-      }
-    }
-    if (filter.category) {
-      if (Array.isArray(filter.category)) {
-        conditions.push(`m.category IN (${filter.category.map(() => "?").join(",")})`);
-        params.push(...filter.category);
-      } else {
-        conditions.push("m.category = ?");
-        params.push(filter.category);
-      }
+  if (!filter)
+    return { conditions, params };
+  if (filter.scope) {
+    if (Array.isArray(filter.scope)) {
+      conditions.push(`m.scope IN (${filter.scope.map(() => "?").join(",")})`);
+      params.push(...filter.scope);
+    } else {
+      conditions.push("m.scope = ?");
+      params.push(filter.scope);
     }
-    if (filter.source) {
-      if (Array.isArray(filter.source)) {
-        conditions.push(`m.source IN (${filter.source.map(() => "?").join(",")})`);
-        params.push(...filter.source);
-      } else {
-        conditions.push("m.source = ?");
-        params.push(filter.source);
-      }
+  }
+  if (filter.category) {
+    if (Array.isArray(filter.category)) {
+      conditions.push(`m.category IN (${filter.category.map(() => "?").join(",")})`);
+      params.push(...filter.category);
+    } else {
+      conditions.push("m.category = ?");
+      params.push(filter.category);
     }
-    if (filter.status) {
-      conditions.shift();
-      if (Array.isArray(filter.status)) {
-        conditions.push(`m.status IN (${filter.status.map(() => "?").join(",")})`);
-        params.push(...filter.status);
-      } else {
-        conditions.push("m.status = ?");
-        params.push(filter.status);
-      }
+  }
+  if (filter.source) {
+    if (Array.isArray(filter.source)) {
+      conditions.push(`m.source IN (${filter.source.map(() => "?").join(",")})`);
+      params.push(...filter.source);
+    } else {
+      conditions.push("m.source = ?");
+      params.push(filter.source);
     }
-    if (filter.project_id) {
-      conditions.push("m.project_id = ?");
-      params.push(filter.project_id);
+  }
+  if (filter.status) {
+    conditions.shift();
+    if (Array.isArray(filter.status)) {
+      conditions.push(`m.status IN (${filter.status.map(() => "?").join(",")})`);
+      params.push(...filter.status);
+    } else {
+      conditions.push("m.status = ?");
+      params.push(filter.status);
     }
-    if (filter.agent_id) {
-      conditions.push("m.agent_id = ?");
-      params.push(filter.agent_id);
+  }
+  if (filter.project_id) {
+    conditions.push("m.project_id = ?");
+    params.push(filter.project_id);
+  }
+  if (filter.agent_id) {
+    conditions.push("m.agent_id = ?");
+    params.push(filter.agent_id);
+  }
+  if (filter.session_id) {
+    conditions.push("m.session_id = ?");
+    params.push(filter.session_id);
+  }
+  if (filter.min_importance) {
+    conditions.push("m.importance >= ?");
+    params.push(filter.min_importance);
+  }
+  if (filter.pinned !== undefined) {
+    conditions.push("m.pinned = ?");
+    params.push(filter.pinned ? 1 : 0);
+  }
+  if (filter.tags && filter.tags.length > 0) {
+    for (const tag of filter.tags) {
+      conditions.push("m.id IN (SELECT memory_id FROM memory_tags WHERE tag = ?)");
+      params.push(tag);
     }
-    if (filter.session_id) {
-      conditions.push("m.session_id = ?");
-      params.push(filter.session_id);
+  }
+  return { conditions, params };
+}
+function searchWithFts5(d, query, queryLower, filter, graphBoostedIds) {
+  const ftsQuery = escapeFts5Query(query);
+  if (!ftsQuery)
+    return null;
+  try {
+    const { conditions, params } = buildFilterConditions(filter);
+    const queryParam = `%${query}%`;
+    const ftsCondition = `(m.rowid IN (SELECT f.rowid FROM memories_fts f WHERE memories_fts MATCH ?) ` + `OR m.id IN (SELECT memory_id FROM memory_tags WHERE tag LIKE ?) ` + `OR m.metadata LIKE ?)`;
+    const allConditions = [ftsCondition, ...conditions];
+    const allParams = [ftsQuery, queryParam, queryParam, ...params];
+    const candidateSql = `SELECT m.* FROM memories m WHERE ${allConditions.join(" AND ")}`;
+    const rows = d.query(candidateSql).all(...allParams);
+    return scoreResults(rows, queryLower, graphBoostedIds);
+  } catch {
+    return null;
+  }
+}
+function searchWithLike(d, query, queryLower, filter, graphBoostedIds) {
+  const { conditions, params } = buildFilterConditions(filter);
+  const rawTokens = query.trim().split(/\s+/).filter(Boolean);
+  const tokens = removeStopWords(rawTokens);
+  const escapedQuery = escapeLikePattern(query);
+  const likePatterns = [`%${escapedQuery}%`];
+  if (tokens.length > 1) {
+    for (const t of tokens)
+      likePatterns.push(`%${escapeLikePattern(t)}%`);
+  }
+  const fieldClauses = [];
+  for (const pattern of likePatterns) {
+    fieldClauses.push("m.key LIKE ? ESCAPE '\\'");
+    params.push(pattern);
+    fieldClauses.push("m.value LIKE ? ESCAPE '\\'");
+    params.push(pattern);
+    fieldClauses.push("m.summary LIKE ? ESCAPE '\\'");
+    params.push(pattern);
+    fieldClauses.push("m.metadata LIKE ? ESCAPE '\\'");
+    params.push(pattern);
+    fieldClauses.push("m.id IN (SELECT memory_id FROM memory_tags WHERE tag LIKE ? ESCAPE '\\')");
+    params.push(pattern);
+  }
+  conditions.push(`(${fieldClauses.join(" OR ")})`);
+  const sql = `SELECT DISTINCT m.* FROM memories m WHERE ${conditions.join(" AND ")}`;
+  const rows = d.query(sql).all(...params);
+  return scoreResults(rows, queryLower, graphBoostedIds);
+}
+function generateTrigrams(s) {
+  const lower = s.toLowerCase();
+  const trigrams = new Set;
+  for (let i = 0;i <= lower.length - 3; i++) {
+    trigrams.add(lower.slice(i, i + 3));
+  }
+  return trigrams;
+}
+function trigramSimilarity(a, b) {
+  const triA = generateTrigrams(a);
+  const triB = generateTrigrams(b);
+  if (triA.size === 0 || triB.size === 0)
+    return 0;
+  let intersection = 0;
+  for (const t of triA) {
+    if (triB.has(t))
+      intersection++;
+  }
+  const union = triA.size + triB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function searchWithFuzzy(d, query, filter, graphBoostedIds) {
+  const { conditions, params } = buildFilterConditions(filter);
+  const sql = `SELECT m.* FROM memories m WHERE ${conditions.join(" AND ")}`;
+  const rows = d.query(sql).all(...params);
+  const MIN_SIMILARITY = 0.3;
+  const results = [];
+  for (const row of rows) {
+    const memory = parseMemoryRow2(row);
+    let bestSimilarity = 0;
+    bestSimilarity = Math.max(bestSimilarity, trigramSimilarity(query, memory.key));
+    bestSimilarity = Math.max(bestSimilarity, trigramSimilarity(query, memory.value.slice(0, 200)));
+    if (memory.summary) {
+      bestSimilarity = Math.max(bestSimilarity, trigramSimilarity(query, memory.summary));
     }
-    if (filter.min_importance) {
-      conditions.push("m.importance >= ?");
-      params.push(filter.min_importance);
+    for (const tag of memory.tags) {
+      bestSimilarity = Math.max(bestSimilarity, trigramSimilarity(query, tag));
     }
-    if (filter.pinned !== undefined) {
-      conditions.push("m.pinned = ?");
-      params.push(filter.pinned ? 1 : 0);
+    if (bestSimilarity >= MIN_SIMILARITY) {
+      const graphBoost = graphBoostedIds?.has(memory.id) ? 2 : 0;
+      const score = bestSimilarity * 5 * memory.importance / 10 + graphBoost;
+      results.push({ memory, score, match_type: "fuzzy" });
     }
-    if (filter.tags && filter.tags.length > 0) {
-      for (const tag of filter.tags) {
-        conditions.push("m.id IN (SELECT memory_id FROM memory_tags WHERE tag = ?)");
-        params.push(tag);
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+function getGraphBoostedMemoryIds(query, d) {
+  const boostedIds = new Set;
+  try {
+    const matchingEntities = listEntities({ search: query, limit: 10 }, d);
+    const exactMatch = getEntityByName(query, undefined, undefined, d);
+    if (exactMatch && !matchingEntities.find((e) => e.id === exactMatch.id)) {
+      matchingEntities.push(exactMatch);
+    }
+    for (const entity of matchingEntities) {
+      const memories = getMemoriesForEntity(entity.id, d);
+      for (const mem of memories) {
+        boostedIds.add(mem.id);
       }
     }
-  }
-  const sql = `SELECT m.* FROM memories m WHERE ${conditions.join(" AND ")}`;
-  const rows = d.query(sql).all(...params);
+  } catch {}
+  return boostedIds;
+}
+function computeRecencyBoost(memory) {
+  if (memory.pinned)
+    return 1;
+  const mostRecent = memory.accessed_at || memory.updated_at;
+  if (!mostRecent)
+    return 0;
+  const daysSinceAccess = (Date.now() - Date.parse(mostRecent)) / (1000 * 60 * 60 * 24);
+  return Math.max(0, 1 - daysSinceAccess / 30);
+}
+function scoreResults(rows, queryLower, graphBoostedIds) {
   const scored = [];
   for (const row of rows) {
     const memory = parseMemoryRow2(row);
@@ -4813,11 +5822,16 @@ function searchMemories(query, filter, db) {
     if (rawScore === 0)
       continue;
     const weightedScore = rawScore * memory.importance / 10;
+    const recencyBoost = computeRecencyBoost(memory);
+    const accessBoost = Math.min(memory.access_count / 20, 0.2);
+    const graphBoost = graphBoostedIds?.has(memory.id) ? 2 : 0;
+    const finalScore = (weightedScore + graphBoost) * (1 + recencyBoost * 0.3) * (1 + accessBoost);
     const matchType = determineMatchType(memory, queryLower);
     scored.push({
       memory,
-      score: weightedScore,
-      match_type: matchType
+      score: finalScore,
+      match_type: matchType,
+      highlights: extractHighlights(memory, queryLower)
     });
   }
   scored.sort((a, b) => {
@@ -4825,20 +5839,64 @@ function searchMemories(query, filter, db) {
       return b.score - a.score;
     return b.memory.importance - a.memory.importance;
   });
+  return scored;
+}
+function searchMemories(query, filter, db) {
+  const d = db || getDatabase();
+  query = preprocessQuery(query);
+  if (!query)
+    return [];
+  const queryLower = query.toLowerCase();
+  const graphBoostedIds = getGraphBoostedMemoryIds(query, d);
+  let scored;
+  if (hasFts5Table(d)) {
+    const ftsResult = searchWithFts5(d, query, queryLower, filter, graphBoostedIds);
+    if (ftsResult !== null) {
+      scored = ftsResult;
+    } else {
+      scored = searchWithLike(d, query, queryLower, filter, graphBoostedIds);
+    }
+  } else {
+    scored = searchWithLike(d, query, queryLower, filter, graphBoostedIds);
+  }
+  if (scored.length < 3) {
+    const fuzzyResults = searchWithFuzzy(d, query, filter, graphBoostedIds);
+    const seenIds = new Set(scored.map((r) => r.memory.id));
+    for (const fr of fuzzyResults) {
+      if (!seenIds.has(fr.memory.id)) {
+        scored.push(fr);
+        seenIds.add(fr.memory.id);
+      }
+    }
+    scored.sort((a, b) => {
+      if (b.score !== a.score)
+        return b.score - a.score;
+      return b.memory.importance - a.memory.importance;
+    });
+  }
   const offset = filter?.offset ?? 0;
   const limit = filter?.limit ?? scored.length;
-  return scored.slice(offset, offset + limit);
+  const finalResults = scored.slice(offset, offset + limit);
+  logSearchQuery(query, scored.length, filter?.agent_id, filter?.project_id, d);
+  return finalResults;
+}
+function logSearchQuery(query, resultCount, agentId, projectId, db) {
+  try {
+    const d = db || getDatabase();
+    const id = crypto.randomUUID().slice(0, 8);
+    d.run("INSERT INTO search_history (id, query, result_count, agent_id, project_id) VALUES (?, ?, ?, ?, ?)", [id, query, resultCount, agentId || null, projectId || null]);
+  } catch {}
 }
 
 // src/lib/project-detect.ts
-import { existsSync as existsSync2 } from "fs";
-import { basename, dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { basename, dirname as dirname3, join as join3, resolve as resolve3 } from "path";
 function findGitRoot2(startDir) {
-  let dir = resolve2(startDir);
+  let dir = resolve3(startDir);
   while (true) {
-    if (existsSync2(join2(dir, ".git")))
+    if (existsSync3(join3(dir, ".git")))
       return dir;
-    const parent = dirname2(dir);
+    const parent = dirname3(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -4857,7 +5915,7 @@ function detectProject(db) {
     return null;
   }
   const repoName = basename(gitRoot);
-  const absPath = resolve2(gitRoot);
+  const absPath = resolve3(gitRoot);
   const existing = getProject(absPath, d);
   if (existing) {
     _cachedProject = existing;
@@ -4868,6 +5926,49 @@ function detectProject(db) {
   return project;
 }
 
+// src/lib/duration.ts
+var UNIT_MS = {
+  s: 1000,
+  m: 60000,
+  h: 3600000,
+  d: 86400000,
+  w: 604800000
+};
+var DURATION_RE = /^(\d+[smhdw])+$/;
+var SEGMENT_RE = /(\d+)([smhdw])/g;
+function parseDuration(input) {
+  if (typeof input === "number")
+    return input;
+  const trimmed = input.trim();
+  if (trimmed === "")
+    throw new Error("Invalid duration: empty string");
+  if (/^\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+  if (!DURATION_RE.test(trimmed)) {
+    throw new Error(`Invalid duration format: "${trimmed}". Use combinations of Ns, Nm, Nh, Nd, Nw (e.g. "1d12h", "30m") or plain milliseconds.`);
+  }
+  let total = 0;
+  let match;
+  SEGMENT_RE.lastIndex = 0;
+  while ((match = SEGMENT_RE.exec(trimmed)) !== null) {
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    total += value * UNIT_MS[unit];
+  }
+  if (total === 0) {
+    throw new Error(`Invalid duration: "${trimmed}" resolves to 0ms`);
+  }
+  return total;
+}
+var FORMAT_UNITS = [
+  ["w", UNIT_MS["w"]],
+  ["d", UNIT_MS["d"]],
+  ["h", UNIT_MS["h"]],
+  ["m", UNIT_MS["m"]],
+  ["s", UNIT_MS["s"]]
+];
+
 // src/mcp/index.ts
 var server = new McpServer({
   name: "mementos",
@@ -4947,13 +6048,17 @@ server.tool("memory_save", "Save/upsert a memory. scope: global=all agents, shar
   agent_id: exports_external.string().optional(),
   project_id: exports_external.string().optional(),
   session_id: exports_external.string().optional(),
-  ttl_ms: exports_external.coerce.number().optional(),
+  ttl_ms: exports_external.union([exports_external.string(), exports_external.number()]).optional(),
   source: exports_external.enum(["user", "agent", "system", "auto", "imported"]).optional(),
   metadata: exports_external.record(exports_external.unknown()).optional()
 }, async (args) => {
   try {
     ensureAutoProject();
-    const memory = createMemory(args);
+    const input = { ...args };
+    if (args.ttl_ms !== undefined) {
+      input.ttl_ms = parseDuration(args.ttl_ms);
+    }
+    const memory = createMemory(input);
     return { content: [{ type: "text", text: `Saved: ${memory.key} (${memory.id.slice(0, 8)})` }] };
   } catch (e) {
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
@@ -5484,49 +6589,646 @@ server.tool("memory_context", "Get memories relevant to current context, filtere
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
-var TOOL_REGISTRY = [
-  { name: "memory_save", description: "Save/upsert a memory. scope: global=all agents, shared=project, private=single agent.", category: "memory" },
-  { name: "memory_recall", description: "Recall a memory by key. Returns the best matching active memory.", category: "memory" },
-  { name: "memory_list", description: "List memories. Default: compact lines. full=true for complete JSON objects.", category: "memory" },
-  { name: "memory_update", description: "Update a memory's metadata (value, importance, tags, etc.)", category: "memory" },
-  { name: "memory_forget", description: "Delete a memory by ID or key", category: "memory" },
-  { name: "memory_search", description: "Search memories by keyword across key, value, summary, and tags", category: "memory" },
-  { name: "memory_stats", description: "Get aggregate statistics about stored memories", category: "memory" },
-  { name: "memory_export", description: "Export memories as JSON", category: "memory" },
-  { name: "memory_import", description: "Import memories from JSON array", category: "memory" },
-  { name: "memory_inject", description: "Get memory context for system prompt injection. Selects by scope, importance, recency.", category: "memory" },
-  { name: "memory_context", description: "Get memories relevant to current context, filtered by scope/importance/recency.", category: "memory" },
-  { name: "register_agent", description: "Register an agent. Idempotent \u2014 same name returns existing agent.", category: "agent" },
-  { name: "list_agents", description: "List all registered agents", category: "agent" },
-  { name: "get_agent", description: "Get agent details by ID or name", category: "agent" },
-  { name: "update_agent", description: "Update agent name, description, role, or metadata.", category: "agent" },
-  { name: "register_project", description: "Register a project for memory scoping", category: "project" },
-  { name: "list_projects", description: "List all registered projects", category: "project" },
-  { name: "bulk_forget", description: "Delete multiple memories by IDs", category: "bulk" },
-  { name: "bulk_update", description: "Update multiple memories with the same changes", category: "bulk" },
-  { name: "clean_expired", description: "Remove expired memories from the database", category: "utility" },
-  { name: "search_tools", description: "Search available tools by name or keyword. Returns names only.", category: "meta" },
-  { name: "describe_tools", description: "Get full schemas for specific tools by name.", category: "meta" }
-];
+function resolveEntityParam(nameOrId, type) {
+  const byName = getEntityByName(nameOrId, type);
+  if (byName)
+    return byName;
+  try {
+    return getEntity(nameOrId);
+  } catch {}
+  const db = getDatabase();
+  const id = resolvePartialId(db, "entities", nameOrId);
+  if (id)
+    return getEntity(id);
+  throw new Error(`Entity not found: ${nameOrId}`);
+}
+server.tool("entity_create", "Create a knowledge graph entity (person, project, tool, concept, file, api, pattern, organization).", {
+  name: exports_external.string(),
+  type: exports_external.enum(["person", "project", "tool", "concept", "file", "api", "pattern", "organization"]),
+  description: exports_external.string().optional(),
+  project_id: exports_external.string().optional()
+}, async (args) => {
+  try {
+    const entity = createEntity(args);
+    return { content: [{ type: "text", text: `Entity: ${entity.name} [${entity.type}] (${entity.id.slice(0, 8)})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_get", "Get entity details by name or ID, including relations summary and memory count.", {
+  name_or_id: exports_external.string(),
+  type: exports_external.enum(["person", "project", "tool", "concept", "file", "api", "pattern", "organization"]).optional()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.name_or_id, args.type);
+    const relations = listRelations({ entity_id: entity.id });
+    const memories = getMemoriesForEntity(entity.id);
+    const lines = [
+      `ID: ${entity.id}`,
+      `Name: ${entity.name}`,
+      `Type: ${entity.type}`
+    ];
+    if (entity.description)
+      lines.push(`Description: ${entity.description}`);
+    if (entity.project_id)
+      lines.push(`Project: ${entity.project_id}`);
+    lines.push(`Relations: ${relations.length}`);
+    lines.push(`Memories: ${memories.length}`);
+    lines.push(`Created: ${entity.created_at}`);
+    lines.push(`Updated: ${entity.updated_at}`);
+    return { content: [{ type: "text", text: lines.join(`
+`) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_list", "List entities. Optional filters: type, project_id, search, limit.", {
+  type: exports_external.enum(["person", "project", "tool", "concept", "file", "api", "pattern", "organization"]).optional(),
+  project_id: exports_external.string().optional(),
+  search: exports_external.string().optional(),
+  limit: exports_external.coerce.number().optional()
+}, async (args) => {
+  try {
+    const entities = listEntities({ ...args, limit: args.limit || 50 });
+    if (entities.length === 0) {
+      return { content: [{ type: "text", text: "No entities found." }] };
+    }
+    const lines = entities.map((e) => `${e.id.slice(0, 8)} | ${e.type} | ${e.name}`);
+    return { content: [{ type: "text", text: `${entities.length} entit${entities.length === 1 ? "y" : "ies"}:
+${lines.join(`
+`)}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_delete", "Delete an entity by name or ID.", {
+  name_or_id: exports_external.string()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.name_or_id);
+    deleteEntity(entity.id);
+    return { content: [{ type: "text", text: `Deleted: ${entity.name} [${entity.type}] (${entity.id.slice(0, 8)})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_merge", "Merge source entity into target. Moves all relations and memory links.", {
+  source: exports_external.string(),
+  target: exports_external.string()
+}, async (args) => {
+  try {
+    const sourceEntity = resolveEntityParam(args.source);
+    const targetEntity = resolveEntityParam(args.target);
+    const merged = mergeEntities(sourceEntity.id, targetEntity.id);
+    return { content: [{ type: "text", text: `Merged: ${sourceEntity.name} \u2192 ${merged.name} [${merged.type}] (${merged.id.slice(0, 8)})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_link", "Link an entity to a memory with a role (subject, object, or context).", {
+  entity_name_or_id: exports_external.string(),
+  memory_id: exports_external.string(),
+  role: exports_external.enum(["subject", "object", "context"]).optional()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.entity_name_or_id);
+    const memoryId = resolveId(args.memory_id);
+    const link = linkEntityToMemory(entity.id, memoryId, args.role || "context");
+    return { content: [{ type: "text", text: `Linked: ${entity.name} \u2192 memory ${memoryId.slice(0, 8)} [${link.role}]` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("relation_create", "Create a relation between two entities (uses, knows, depends_on, created_by, related_to, contradicts, part_of, implements).", {
+  source_entity: exports_external.string(),
+  target_entity: exports_external.string(),
+  relation_type: exports_external.enum(["uses", "knows", "depends_on", "created_by", "related_to", "contradicts", "part_of", "implements"]),
+  weight: exports_external.coerce.number().optional()
+}, async (args) => {
+  try {
+    const source = resolveEntityParam(args.source_entity);
+    const target = resolveEntityParam(args.target_entity);
+    const relation = createRelation({
+      source_entity_id: source.id,
+      target_entity_id: target.id,
+      relation_type: args.relation_type,
+      weight: args.weight
+    });
+    return { content: [{ type: "text", text: `Relation: ${source.name} \u2014[${relation.relation_type}]\u2192 ${target.name} (${relation.id.slice(0, 8)})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("relation_list", "List relations for an entity. Filter by type and direction (outgoing, incoming, both).", {
+  entity_name_or_id: exports_external.string(),
+  relation_type: exports_external.enum(["uses", "knows", "depends_on", "created_by", "related_to", "contradicts", "part_of", "implements"]).optional(),
+  direction: exports_external.enum(["outgoing", "incoming", "both"]).optional()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.entity_name_or_id);
+    const relations = listRelations({
+      entity_id: entity.id,
+      relation_type: args.relation_type,
+      direction: args.direction || "both"
+    });
+    if (relations.length === 0) {
+      return { content: [{ type: "text", text: `No relations found for: ${entity.name}` }] };
+    }
+    const lines = relations.map((r) => `${r.id.slice(0, 8)} | ${r.source_entity_id.slice(0, 8)} \u2014[${r.relation_type}]\u2192 ${r.target_entity_id.slice(0, 8)} (w:${r.weight})`);
+    return { content: [{ type: "text", text: `${relations.length} relation(s) for ${entity.name}:
+${lines.join(`
+`)}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("relation_delete", "Delete a relation by ID.", {
+  id: exports_external.string()
+}, async (args) => {
+  try {
+    const id = resolveId(args.id, "relations");
+    deleteRelation(id);
+    return { content: [{ type: "text", text: `Relation ${id.slice(0, 8)} deleted.` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("graph_query", "Traverse the knowledge graph from an entity up to N hops. Returns entities and relations.", {
+  entity_name_or_id: exports_external.string(),
+  depth: exports_external.coerce.number().optional()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.entity_name_or_id);
+    const depth = args.depth ?? 2;
+    const graph = getEntityGraph(entity.id, depth);
+    if (graph.entities.length === 0) {
+      return { content: [{ type: "text", text: `No graph found for: ${entity.name}` }] };
+    }
+    const entityLines = graph.entities.map((e) => `  ${e.id.slice(0, 8)} | ${e.type} | ${e.name}`);
+    const relationLines = graph.relations.map((r) => `  ${r.source_entity_id.slice(0, 8)} \u2014[${r.relation_type}]\u2192 ${r.target_entity_id.slice(0, 8)}`);
+    const lines = [
+      `Graph for ${entity.name} (depth ${depth}):`,
+      `Entities (${graph.entities.length}):`,
+      ...entityLines
+    ];
+    if (relationLines.length > 0) {
+      lines.push(`Relations (${graph.relations.length}):`, ...relationLines);
+    }
+    return { content: [{ type: "text", text: lines.join(`
+`) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("graph_path", "Find shortest path between two entities in the knowledge graph.", {
+  from_entity: exports_external.string(),
+  to_entity: exports_external.string(),
+  max_depth: exports_external.coerce.number().optional()
+}, async (args) => {
+  try {
+    const from = resolveEntityParam(args.from_entity);
+    const to = resolveEntityParam(args.to_entity);
+    const maxDepth = args.max_depth ?? 5;
+    const path = findPath(from.id, to.id, maxDepth);
+    if (!path || path.length === 0) {
+      return { content: [{ type: "text", text: `No path found: ${from.name} \u2192 ${to.name} (max depth ${maxDepth})` }] };
+    }
+    const pathStr = path.map((e) => e.name).join(" \u2192 ");
+    return { content: [{ type: "text", text: `Path: ${pathStr}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("graph_stats", "Get entity and relation counts by type.", {}, async () => {
+  try {
+    const db = getDatabase();
+    const entityTotal = db.query("SELECT COUNT(*) as c FROM entities").get().c;
+    const byType = db.query("SELECT type, COUNT(*) as c FROM entities GROUP BY type").all();
+    const relationTotal = db.query("SELECT COUNT(*) as c FROM relations").get().c;
+    const byRelType = db.query("SELECT relation_type, COUNT(*) as c FROM relations GROUP BY relation_type").all();
+    const linkTotal = db.query("SELECT COUNT(*) as c FROM entity_memories").get().c;
+    const lines = [
+      `Entities: ${entityTotal}`
+    ];
+    if (byType.length > 0) {
+      lines.push(`  By type: ${byType.map((r) => `${r.type}=${r.c}`).join(", ")}`);
+    }
+    lines.push(`Relations: ${relationTotal}`);
+    if (byRelType.length > 0) {
+      lines.push(`  By type: ${byRelType.map((r) => `${r.relation_type}=${r.c}`).join(", ")}`);
+    }
+    lines.push(`Entity-memory links: ${linkTotal}`);
+    return { content: [{ type: "text", text: lines.join(`
+`) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+var FULL_SCHEMAS = {
+  memory_save: {
+    description: "Save/upsert a memory. Creates new or merges with existing key.",
+    category: "memory",
+    params: {
+      key: { type: "string", description: "Unique key for the memory (kebab-case recommended)", required: true },
+      value: { type: "string", description: "The memory content", required: true },
+      scope: { type: "string", description: "Visibility: global=all agents, shared=project, private=single agent", enum: ["global", "shared", "private"] },
+      category: { type: "string", description: "Memory type", enum: ["preference", "fact", "knowledge", "history"] },
+      importance: { type: "number", description: "Priority 1-10 (10=critical)" },
+      tags: { type: "array", description: "Searchable tags", items: { type: "string" } },
+      summary: { type: "string", description: "Short summary for display" },
+      agent_id: { type: "string", description: "Agent UUID to scope this memory to" },
+      project_id: { type: "string", description: "Project UUID to scope this memory to" },
+      session_id: { type: "string", description: "Session UUID" },
+      ttl_ms: { type: "string|number", description: "Time-to-live e.g. '7d', '2h', or ms integer" },
+      source: { type: "string", description: "Origin of the memory", enum: ["user", "agent", "system", "auto", "imported"] },
+      metadata: { type: "object", description: "Arbitrary JSON metadata" }
+    },
+    example: '{"key":"preferred-language","value":"TypeScript","scope":"global","importance":8,"tags":["language","preference"]}'
+  },
+  memory_recall: {
+    description: "Recall a memory by exact key. Falls back to fuzzy search if no exact match.",
+    category: "memory",
+    params: {
+      key: { type: "string", description: "Key to look up", required: true },
+      scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private"] },
+      agent_id: { type: "string", description: "Agent UUID filter" },
+      project_id: { type: "string", description: "Project UUID filter" },
+      session_id: { type: "string", description: "Session UUID filter" }
+    },
+    example: '{"key":"preferred-language","scope":"global"}'
+  },
+  memory_list: {
+    description: "List memories with optional filters. Returns compact lines by default.",
+    category: "memory",
+    params: {
+      scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private"] },
+      category: { type: "string", description: "Category filter", enum: ["preference", "fact", "knowledge", "history"] },
+      tags: { type: "array", description: "Filter by tags (AND logic)", items: { type: "string" } },
+      min_importance: { type: "number", description: "Minimum importance threshold" },
+      pinned: { type: "boolean", description: "Filter to pinned memories only" },
+      agent_id: { type: "string", description: "Agent UUID filter" },
+      project_id: { type: "string", description: "Project UUID filter" },
+      session_id: { type: "string", description: "Session UUID filter" },
+      status: { type: "string", description: "Memory status filter", enum: ["active", "archived", "expired"] },
+      limit: { type: "number", description: "Max results (default 50)" },
+      offset: { type: "number", description: "Pagination offset" },
+      full: { type: "boolean", description: "Return full JSON objects instead of compact lines" },
+      fields: { type: "array", description: "Fields to include in full mode", items: { type: "string" } }
+    },
+    example: '{"scope":"global","min_importance":7,"limit":20}'
+  },
+  memory_update: {
+    description: "Update a memory's fields. Requires current version for optimistic concurrency.",
+    category: "memory",
+    params: {
+      id: { type: "string", description: "Memory ID (partial OK)", required: true },
+      version: { type: "number", description: "Current version (for conflict detection)", required: true },
+      value: { type: "string", description: "New value" },
+      category: { type: "string", description: "New category", enum: ["preference", "fact", "knowledge", "history"] },
+      scope: { type: "string", description: "New scope", enum: ["global", "shared", "private"] },
+      importance: { type: "number", description: "New importance 1-10" },
+      tags: { type: "array", description: "New tags (replaces all)", items: { type: "string" } },
+      summary: { type: "string", description: "New summary (null to clear)" },
+      pinned: { type: "boolean", description: "Pin/unpin the memory" },
+      status: { type: "string", description: "New status", enum: ["active", "archived", "expired"] },
+      metadata: { type: "object", description: "New metadata (replaces existing)" },
+      expires_at: { type: "string", description: "New expiry ISO timestamp (null to clear)" }
+    },
+    example: '{"id":"abc123","version":1,"importance":9,"tags":["correction","important"]}'
+  },
+  memory_forget: {
+    description: "Delete a memory by ID or key.",
+    category: "memory",
+    params: {
+      id: { type: "string", description: "Memory ID (partial OK)" },
+      key: { type: "string", description: "Memory key" },
+      scope: { type: "string", description: "Scope for key lookup", enum: ["global", "shared", "private"] },
+      agent_id: { type: "string", description: "Agent UUID for key lookup" },
+      project_id: { type: "string", description: "Project UUID for key lookup" }
+    },
+    example: '{"key":"old-preference","scope":"global"}'
+  },
+  memory_search: {
+    description: "Full-text search across key, value, summary, and tags.",
+    category: "memory",
+    params: {
+      query: { type: "string", description: "Search query", required: true },
+      scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private"] },
+      category: { type: "string", description: "Category filter", enum: ["preference", "fact", "knowledge", "history"] },
+      tags: { type: "array", description: "Tag filter", items: { type: "string" } },
+      agent_id: { type: "string", description: "Agent UUID filter" },
+      project_id: { type: "string", description: "Project UUID filter" },
+      limit: { type: "number", description: "Max results (default 20)" }
+    },
+    example: '{"query":"typescript","scope":"global","limit":10}'
+  },
+  memory_stats: {
+    description: "Aggregate statistics: total, by scope, by category, pinned, expired counts.",
+    category: "memory",
+    params: {},
+    example: "{}"
+  },
+  memory_export: {
+    description: "Export memories as a JSON array.",
+    category: "memory",
+    params: {
+      scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private"] },
+      category: { type: "string", description: "Category filter", enum: ["preference", "fact", "knowledge", "history"] },
+      agent_id: { type: "string", description: "Agent UUID filter" },
+      project_id: { type: "string", description: "Project UUID filter" }
+    },
+    example: '{"scope":"global"}'
+  },
+  memory_import: {
+    description: "Import memories from a JSON array. Merges by key by default.",
+    category: "memory",
+    params: {
+      memories: { type: "array", description: "Array of memory objects with key+value (required), plus optional fields", required: true, items: { type: "object" } },
+      overwrite: { type: "boolean", description: "false=create-only (skip existing keys), default=merge" }
+    },
+    example: '{"memories":[{"key":"foo","value":"bar","scope":"global","importance":7}]}'
+  },
+  memory_inject: {
+    description: "Get formatted memory context for system prompt injection. Respects token budget.",
+    category: "memory",
+    params: {
+      agent_id: { type: "string", description: "Agent UUID to include private memories" },
+      project_id: { type: "string", description: "Project UUID to include shared memories" },
+      session_id: { type: "string", description: "Session UUID" },
+      max_tokens: { type: "number", description: "Approximate token budget (default 500)" },
+      categories: { type: "array", description: "Categories to include (default: preference, fact, knowledge)", items: { type: "string", enum: ["preference", "fact", "knowledge", "history"] } },
+      min_importance: { type: "number", description: "Minimum importance (default 3)" },
+      raw: { type: "boolean", description: "true=plain lines only, false=wrapped in <agent-memories> tags" }
+    },
+    example: '{"project_id":"proj-uuid","max_tokens":300,"min_importance":5}'
+  },
+  memory_context: {
+    description: "Get active memories for the current context (agent/project/scope).",
+    category: "memory",
+    params: {
+      agent_id: { type: "string", description: "Agent UUID filter" },
+      project_id: { type: "string", description: "Project UUID filter" },
+      scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private"] },
+      limit: { type: "number", description: "Max results (default 30)" }
+    },
+    example: '{"project_id":"proj-uuid","scope":"shared","limit":20}'
+  },
+  register_agent: {
+    description: "Register an agent. Idempotent \u2014 same name returns existing agent.",
+    category: "agent",
+    params: {
+      name: { type: "string", description: "Agent name (e.g. 'maximus', 'cassius')", required: true },
+      description: { type: "string", description: "Agent description" },
+      role: { type: "string", description: "Agent role (default: 'agent')" }
+    },
+    example: '{"name":"maximus","role":"developer"}'
+  },
+  list_agents: {
+    description: "List all registered agents with IDs, names, roles, and last-seen timestamps.",
+    category: "agent",
+    params: {},
+    example: "{}"
+  },
+  get_agent: {
+    description: "Get agent details by UUID or name.",
+    category: "agent",
+    params: {
+      id: { type: "string", description: "Agent UUID or name", required: true }
+    },
+    example: '{"id":"maximus"}'
+  },
+  update_agent: {
+    description: "Update agent name, description, role, or metadata.",
+    category: "agent",
+    params: {
+      id: { type: "string", description: "Agent UUID", required: true },
+      name: { type: "string", description: "New name" },
+      description: { type: "string", description: "New description" },
+      role: { type: "string", description: "New role" },
+      metadata: { type: "object", description: "New metadata" }
+    },
+    example: '{"id":"agent-uuid","role":"senior-developer"}'
+  },
+  register_project: {
+    description: "Register a project for memory scoping. Idempotent by name.",
+    category: "project",
+    params: {
+      name: { type: "string", description: "Project name (use git repo name)", required: true },
+      path: { type: "string", description: "Absolute path to project root", required: true },
+      description: { type: "string", description: "Project description" },
+      memory_prefix: { type: "string", description: "Key prefix for project memories" }
+    },
+    example: '{"name":"open-mementos","path":"/Users/hasna/Workspace/hasna/opensource/opensourcedev/open-mementos"}'
+  },
+  list_projects: {
+    description: "List all registered projects with IDs, names, and paths.",
+    category: "project",
+    params: {},
+    example: "{}"
+  },
+  bulk_forget: {
+    description: "Delete multiple memories by IDs in one call.",
+    category: "bulk",
+    params: {
+      ids: { type: "array", description: "Array of memory IDs (partials OK)", required: true, items: { type: "string" } }
+    },
+    example: '{"ids":["abc123","def456"]}'
+  },
+  bulk_update: {
+    description: "Apply the same field updates to multiple memories.",
+    category: "bulk",
+    params: {
+      ids: { type: "array", description: "Array of memory IDs (partials OK)", required: true, items: { type: "string" } },
+      importance: { type: "number", description: "New importance 1-10" },
+      tags: { type: "array", description: "New tags (replaces all)", items: { type: "string" } },
+      pinned: { type: "boolean", description: "Pin/unpin" },
+      category: { type: "string", description: "New category", enum: ["preference", "fact", "knowledge", "history"] },
+      status: { type: "string", description: "New status", enum: ["active", "archived", "expired"] }
+    },
+    example: '{"ids":["abc123","def456"],"importance":9,"tags":["important"]}'
+  },
+  clean_expired: {
+    description: "Remove expired memories from the database. Returns count of removed entries.",
+    category: "utility",
+    params: {},
+    example: "{}"
+  },
+  entity_create: {
+    description: "Create a knowledge graph entity.",
+    category: "graph",
+    params: {
+      name: { type: "string", description: "Entity name", required: true },
+      type: { type: "string", description: "Entity type", required: true, enum: ["person", "project", "tool", "concept", "file", "api", "pattern", "organization"] },
+      description: { type: "string", description: "Entity description" },
+      project_id: { type: "string", description: "Project UUID to scope this entity" }
+    },
+    example: '{"name":"TypeScript","type":"tool","description":"Typed superset of JavaScript"}'
+  },
+  entity_get: {
+    description: "Get entity details including relations summary and linked memory count.",
+    category: "graph",
+    params: {
+      name_or_id: { type: "string", description: "Entity name or ID (partial OK)", required: true },
+      type: { type: "string", description: "Type hint for name disambiguation", enum: ["person", "project", "tool", "concept", "file", "api", "pattern", "organization"] }
+    },
+    example: '{"name_or_id":"TypeScript"}'
+  },
+  entity_list: {
+    description: "List entities with optional type, project, and search filters.",
+    category: "graph",
+    params: {
+      type: { type: "string", description: "Type filter", enum: ["person", "project", "tool", "concept", "file", "api", "pattern", "organization"] },
+      project_id: { type: "string", description: "Project UUID filter" },
+      search: { type: "string", description: "Name search string" },
+      limit: { type: "number", description: "Max results (default 50)" }
+    },
+    example: '{"type":"tool","limit":20}'
+  },
+  entity_delete: {
+    description: "Delete an entity and all its relations.",
+    category: "graph",
+    params: {
+      name_or_id: { type: "string", description: "Entity name or ID (partial OK)", required: true }
+    },
+    example: '{"name_or_id":"OldEntity"}'
+  },
+  entity_merge: {
+    description: "Merge source entity into target \u2014 moves all relations and memory links.",
+    category: "graph",
+    params: {
+      source: { type: "string", description: "Source entity name or ID (will be deleted)", required: true },
+      target: { type: "string", description: "Target entity name or ID (will be kept)", required: true }
+    },
+    example: '{"source":"OldName","target":"NewName"}'
+  },
+  entity_link: {
+    description: "Link an entity to a memory with a semantic role.",
+    category: "graph",
+    params: {
+      entity_name_or_id: { type: "string", description: "Entity name or ID", required: true },
+      memory_id: { type: "string", description: "Memory ID (partial OK)", required: true },
+      role: { type: "string", description: "Semantic role (default: context)", enum: ["subject", "object", "context"] }
+    },
+    example: '{"entity_name_or_id":"TypeScript","memory_id":"abc123","role":"subject"}'
+  },
+  relation_create: {
+    description: "Create a typed relation between two entities.",
+    category: "graph",
+    params: {
+      source_entity: { type: "string", description: "Source entity name or ID", required: true },
+      target_entity: { type: "string", description: "Target entity name or ID", required: true },
+      relation_type: { type: "string", description: "Relation type", required: true, enum: ["uses", "knows", "depends_on", "created_by", "related_to", "contradicts", "part_of", "implements"] },
+      weight: { type: "number", description: "Relation weight 0-1 (default 1.0)" }
+    },
+    example: '{"source_entity":"MyApp","target_entity":"TypeScript","relation_type":"uses"}'
+  },
+  relation_list: {
+    description: "List relations for an entity, with optional type and direction filters.",
+    category: "graph",
+    params: {
+      entity_name_or_id: { type: "string", description: "Entity name or ID", required: true },
+      relation_type: { type: "string", description: "Type filter", enum: ["uses", "knows", "depends_on", "created_by", "related_to", "contradicts", "part_of", "implements"] },
+      direction: { type: "string", description: "Direction filter (default: both)", enum: ["outgoing", "incoming", "both"] }
+    },
+    example: '{"entity_name_or_id":"MyApp","direction":"outgoing"}'
+  },
+  relation_delete: {
+    description: "Delete a relation by ID.",
+    category: "graph",
+    params: {
+      id: { type: "string", description: "Relation ID (partial OK)", required: true }
+    },
+    example: '{"id":"rel-abc123"}'
+  },
+  graph_query: {
+    description: "Traverse the knowledge graph from an entity up to N hops. Returns entities and relations.",
+    category: "graph",
+    params: {
+      entity_name_or_id: { type: "string", description: "Starting entity name or ID", required: true },
+      depth: { type: "number", description: "Max traversal depth (default 2)" }
+    },
+    example: '{"entity_name_or_id":"MyApp","depth":3}'
+  },
+  graph_path: {
+    description: "Find the shortest path between two entities in the knowledge graph.",
+    category: "graph",
+    params: {
+      from_entity: { type: "string", description: "Starting entity name or ID", required: true },
+      to_entity: { type: "string", description: "Target entity name or ID", required: true },
+      max_depth: { type: "number", description: "Max search depth (default 5)" }
+    },
+    example: '{"from_entity":"Agent","to_entity":"Database","max_depth":4}'
+  },
+  graph_stats: {
+    description: "Get entity and relation counts broken down by type.",
+    category: "graph",
+    params: {},
+    example: "{}"
+  },
+  search_tools: {
+    description: "Search available tools by name or keyword. Returns matching tool names and categories.",
+    category: "meta",
+    params: {
+      query: { type: "string", description: "Search keyword (matches tool name or description)", required: true },
+      category: { type: "string", description: "Category filter", enum: ["memory", "agent", "project", "bulk", "utility", "graph", "meta"] }
+    },
+    example: '{"query":"memory","category":"memory"}'
+  },
+  describe_tools: {
+    description: "Get full parameter schemas and examples for specific tools. Omit names to list all tools.",
+    category: "meta",
+    params: {
+      names: { type: "array", description: "Tool names to describe (omit for all tools)", items: { type: "string" } }
+    },
+    example: '{"names":["memory_save","memory_recall"]}'
+  }
+};
+var TOOL_REGISTRY = Object.entries(FULL_SCHEMAS).map(([name, schema]) => ({
+  name,
+  description: schema.description,
+  category: schema.category
+}));
 server.tool("search_tools", "Search available tools by name or keyword. Returns names only.", {
   query: exports_external.string(),
-  category: exports_external.enum(["memory", "agent", "project", "bulk", "utility", "meta"]).optional()
+  category: exports_external.enum(["memory", "agent", "project", "bulk", "utility", "graph", "meta"]).optional()
 }, async (args) => {
   const q = args.query.toLowerCase();
   const results = TOOL_REGISTRY.filter((t) => (!args.category || t.category === args.category) && (t.name.includes(q) || t.description.toLowerCase().includes(q)));
   if (results.length === 0)
     return { content: [{ type: "text", text: "No tools found." }] };
-  return { content: [{ type: "text", text: results.map((t) => `${t.name} [${t.category}]`).join(`
+  return { content: [{ type: "text", text: results.map((t) => `${t.name} [${t.category}]: ${t.description}`).join(`
 `) }] };
 });
-server.tool("describe_tools", "Get full schemas for specific tools by name.", {
-  names: exports_external.array(exports_external.string())
+server.tool("describe_tools", "Get full parameter schemas and examples for tools. Omit names to list all tools.", {
+  names: exports_external.array(exports_external.string()).optional()
 }, async (args) => {
-  const found = TOOL_REGISTRY.filter((t) => args.names.includes(t.name));
-  if (found.length === 0)
+  const targets = args.names && args.names.length > 0 ? args.names : Object.keys(FULL_SCHEMAS);
+  const results = targets.filter((name) => (name in FULL_SCHEMAS)).map((name) => {
+    const schema = FULL_SCHEMAS[name];
+    const paramLines = Object.entries(schema.params).map(([pname, p]) => {
+      const req = p.required ? " [required]" : "";
+      const enumStr = p.enum ? ` (${p.enum.join("|")})` : "";
+      return `  ${pname}${req}: ${p.type}${enumStr} \u2014 ${p.description}`;
+    });
+    const lines = [
+      `### ${name} [${schema.category}]`,
+      schema.description
+    ];
+    if (paramLines.length > 0) {
+      lines.push("Params:", ...paramLines);
+    } else {
+      lines.push("Params: none");
+    }
+    if (schema.example)
+      lines.push(`Example: ${schema.example}`);
+    return lines.join(`
+`);
+  });
+  if (results.length === 0) {
     return { content: [{ type: "text", text: "No matching tools." }] };
-  const lines = found.map((t) => `**${t.name}** [${t.category}]: ${t.description}`);
-  return { content: [{ type: "text", text: lines.join(`
+  }
+  return { content: [{ type: "text", text: results.join(`
+
 `) }] };
 });
 server.resource("memories", "mementos://memories", { description: "All active memories", mimeType: "application/json" }, async () => {