@hippocampusllms/cli 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1112 @@
+#!/usr/bin/env node
+
+// packages/adapters/src/index.ts
+import {
+  existsSync,
+  readFileSync,
+  copyFileSync,
+  writeFileSync,
+  mkdirSync
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+var capabilities = {
+  mcp: true,
+  cli: true,
+  taskStartHook: false,
+  taskEndHook: false,
+  eventCapture: false
+};
+var begin = "# BEGIN HIPPOCAMPUS MANAGED";
+var end = "# END HIPPOCAMPUS MANAGED";
+function connect(host, project, entry, scope, dryRun, remove = false) {
+  if (!["claude", "codex"].includes(host))
+    throw Error("Supported hosts: claude, codex");
+  if (!["project", "user"].includes(scope))
+    throw Error("Scope must be project or user");
+  if (host === "claude" && scope === "user")
+    return {
+      host,
+      manual: true,
+      command: [
+        "claude",
+        "mcp",
+        "add",
+        "--transport",
+        "stdio",
+        "--scope",
+        "user",
+        "hippocampus",
+        "--",
+        process.execPath,
+        entry,
+        "serve",
+        "--transport",
+        "stdio",
+        "--project",
+        project
+      ],
+      reason: "Claude user configuration is managed by the Claude CLI. Review this argument array before running it."
+    };
+  const path = host === "claude" ? join(project, ".mcp.json") : join(
+    scope === "user" ? join(homedir(), ".codex") : join(project, ".codex"),
+    "config.toml"
+  );
+  const old = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const launch = {
+    command: process.execPath,
+    args: [entry, "serve", "--transport", "stdio", "--project", project]
+  };
+  let next;
+  if (host === "claude") {
+    const document = old ? JSON.parse(old) : {};
+    document.mcpServers ??= {};
+    const existing = document.mcpServers.hippocampus;
+    const owner = join(project, ".hippocampus/claude-connection.json");
+    const owned = existsSync(owner) ? JSON.parse(readFileSync(owner, "utf8")) : void 0;
+    if (existing && JSON.stringify(existing) !== JSON.stringify(owned?.entry))
+      throw Error(
+        "Existing hippocampus server is not owned by this adapter; preserve it and choose manual setup"
+      );
+    if (remove) delete document.mcpServers.hippocampus;
+    else document.mcpServers.hippocampus = launch;
+    next = JSON.stringify(document, null, 2) + "\n";
+    if (!dryRun) {
+      mkdirSync(dirname(path), { recursive: true });
+      if (old && !existsSync(path + ".hippocampus.bak"))
+        copyFileSync(path, path + ".hippocampus.bak");
+      writeFileSync(path, next);
+      writeFileSync(owner, JSON.stringify({ entry: remove ? null : launch }));
+    }
+  } else {
+    const start = old.indexOf(begin);
+    const stop = old.indexOf(end);
+    if (start < 0 !== stop < 0)
+      throw Error("Incomplete managed configuration block; restore backup");
+    const unowned = start < 0 ? old : old.slice(0, start) + old.slice(stop + end.length);
+    if (/\[mcp_servers\.(?:"hippocampus"|hippocampus)\]/.test(unowned))
+      throw Error(
+        "Existing hippocampus configuration is not managed by this adapter"
+      );
+    const block = `${begin}
+[mcp_servers.hippocampus]
+command = ${JSON.stringify(launch.command)}
+args = ${JSON.stringify(launch.args)}
+${end}`;
+    next = remove ? unowned : unowned.trimEnd() + "\n\n" + block + "\n";
+    if (!dryRun) {
+      mkdirSync(dirname(path), { recursive: true });
+      if (old && !existsSync(path + ".hippocampus.bak"))
+        copyFileSync(path, path + ".hippocampus.bak");
+      writeFileSync(path, next);
+    }
+  }
+  return {
+    host,
+    scope,
+    path,
+    dryRun,
+    before: old,
+    after: next,
+    backup: path + ".hippocampus.bak",
+    capabilities,
+    trigger: "manual or agent-instructed"
+  };
+}
+
+// packages/cli/src/index.ts
+import { parseArgs } from "node:util";
+import {
+  existsSync as existsSync3,
+  readFileSync as readFileSync3,
+  appendFileSync,
+  realpathSync as realpathSync2
+} from "node:fs";
+import { resolve as resolve2, join as join3, isAbsolute } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+// packages/cli/src/config.ts
+import { homedir as homedir2 } from "node:os";
+import {
+  existsSync as existsSync2,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2,
+  renameSync,
+  mkdirSync as mkdirSync2,
+  realpathSync
+} from "node:fs";
+import { resolve, dirname as dirname2, join as join2 } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+var schema = z.object({
+  schemaVersion: z.literal(1),
+  projectId: z.string().uuid(),
+  storage: z.object({
+    provider: z.literal("sqlite"),
+    sqlite: z.object({ path: z.string().min(1) }).strict()
+  }).strict(),
+  retrieval: z.object({
+    mode: z.literal("lexical"),
+    maxContextTokens: z.number().int().min(100).max(1e4),
+    vector: z.object({ provider: z.literal("none") }).strict()
+  }).strict(),
+  embeddings: z.object({ provider: z.literal("none") }).strict(),
+  capture: z.object({ mode: z.literal("explicit") }).strict(),
+  privacy: z.object({ telemetry: z.literal(false) }).strict()
+}).strict();
+function defaults() {
+  return {
+    schemaVersion: 1,
+    projectId: randomUUID(),
+    storage: { provider: "sqlite", sqlite: { path: "./memory.sqlite" } },
+    retrieval: {
+      mode: "lexical",
+      maxContextTokens: 1500,
+      vector: { provider: "none" }
+    },
+    embeddings: { provider: "none" },
+    capture: { mode: "explicit" },
+    privacy: { telemetry: false }
+  };
+}
+function root(path) {
+  let p2 = realpathSync(resolve(path));
+  while (!existsSync2(join2(p2, ".hippocampus/config.json"))) {
+    const next = dirname2(p2);
+    if (next === p2)
+      throw Error("Project not initialized; run hippocampus init");
+    p2 = next;
+  }
+  return p2;
+}
+function configPath(p2) {
+  return join2(p2, ".hippocampus/config.json");
+}
+function load(p2) {
+  return schema.parse(JSON.parse(readFileSync2(configPath(p2), "utf8")));
+}
+function atomic(path, value) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  const temp = path + "." + randomUUID() + ".tmp";
+  writeFileSync2(temp, JSON.stringify(value, null, 2) + "\n", { mode: 384 });
+  renameSync(temp, path);
+}
+function database(p2, c) {
+  return resolve(dirname2(configPath(p2)), c.storage.sqlite.path);
+}
+function userConfigPath() {
+  return join2(
+    process.env.XDG_CONFIG_HOME ?? join2(homedir2(), ".config"),
+    "hippocampus",
+    "config.json"
+  );
+}
+function merge(a, b) {
+  const result = structuredClone(a);
+  for (const [key, value] of Object.entries(b)) {
+    result[key] = value && typeof value === "object" && !Array.isArray(value) ? merge(result[key] ?? {}, value) : value;
+  }
+  return result;
+}
+function userDefaults() {
+  const path = userConfigPath();
+  if (!existsSync2(path)) return {};
+  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  if ("projectId" in raw) throw Error("User defaults cannot contain projectId");
+  schema.parse(merge(defaults(), raw));
+  return raw;
+}
+function effective(p2) {
+  const raw = JSON.parse(readFileSync2(configPath(p2), "utf8"));
+  schema.parse(raw);
+  const result = merge(merge(defaults(), userDefaults()), raw);
+  if (process.env.HIPPOCAMPUS_MAX_CONTEXT_TOKENS)
+    result.retrieval.maxContextTokens = Number(
+      process.env.HIPPOCAMPUS_MAX_CONTEXT_TOKENS
+    );
+  return schema.parse(result);
+}
+function saveUser(raw) {
+  if ("projectId" in raw) throw Error("User defaults cannot contain projectId");
+  schema.parse(merge(defaults(), raw));
+  atomic(userConfigPath(), raw);
+}
+
+// packages/core/src/schema.ts
+import { z as z2 } from "zod";
+var evidenceSchema = z2.object({
+  type: z2.enum(["commit", "path", "test", "issue", "user", "other"]),
+  reference: z2.string().min(1).max(2e3),
+  observedAt: z2.string().datetime().optional(),
+  contentHash: z2.string().max(128).optional()
+}).strict();
+var relationSchema = z2.object({
+  type: z2.enum(["supports", "supersedes", "contradicts", "derived_from"]),
+  targetId: z2.string().uuid()
+}).strict();
+var recordSchema = z2.object({
+  id: z2.string().uuid(),
+  schemaVersion: z2.literal(1),
+  revision: z2.number().int().positive(),
+  projectId: z2.string().uuid(),
+  workspaceId: z2.string().max(200).optional(),
+  scope: z2.object({
+    level: z2.enum(["project", "component"]),
+    component: z2.string().max(200).optional()
+  }).strict(),
+  applicability: z2.object({
+    environments: z2.array(z2.string().max(200)).max(20).optional(),
+    workspaces: z2.array(z2.string().max(200)).max(20).optional()
+  }).strict(),
+  kind: z2.enum([
+    "decision",
+    "constraint",
+    "episode",
+    "procedure",
+    "correction",
+    "task"
+  ]),
+  content: z2.string().min(8).max(8e3),
+  rationale: z2.string().max(4e3).optional(),
+  cues: z2.array(z2.string().max(200)).max(30),
+  entities: z2.array(z2.string().max(200)).max(30),
+  evidence: z2.array(evidenceSchema).max(30),
+  verification: z2.enum(["hypothesis", "observed", "confirmed"]),
+  status: z2.enum(["active", "superseded", "archived", "expired"]),
+  createdAt: z2.string().datetime(),
+  updatedAt: z2.string().datetime(),
+  validFrom: z2.string().datetime().optional(),
+  validUntil: z2.string().datetime().optional(),
+  lastVerifiedAt: z2.string().datetime().optional(),
+  createdBy: z2.object({
+    client: z2.string().max(100),
+    agentId: z2.string().max(100).optional(),
+    sessionId: z2.string().max(100).optional()
+  }).strict(),
+  pinned: z2.boolean(),
+  expiresAt: z2.string().datetime().optional(),
+  lastRecalledAt: z2.string().datetime().optional(),
+  recallCount: z2.number().int().nonnegative(),
+  relations: z2.array(relationSchema).max(30),
+  idempotencyKey: z2.string().max(200).optional(),
+  utilityFeedback: z2.array(
+    z2.object({ useful: z2.boolean(), observedAt: z2.string().datetime() })
+  ).max(100).optional()
+}).strict().superRefine((m, ctx) => {
+  if (m.scope.level === "component" && !m.scope.component)
+    ctx.addIssue({
+      code: "custom",
+      message: "Component scope requires component"
+    });
+});
+var newMemorySchema = z2.object(recordSchema.shape).omit({
+  id: true,
+  schemaVersion: true,
+  revision: true,
+  projectId: true,
+  createdAt: true,
+  updatedAt: true,
+  recallCount: true,
+  lastRecalledAt: true,
+  utilityFeedback: true
+}).partial().required({ kind: true, content: true }).strict();
+
+// packages/storage-sqlite/src/index.ts
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync as mkdirSync3 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+
+// packages/core/src/model.ts
+import { randomUUID as randomUUID2, createHash } from "node:crypto";
+var AppError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+  code;
+  details;
+};
+function assert(condition, message) {
+  if (!condition) throw new AppError("INVALID_INPUT", message);
+}
+function validateText(text) {
+  assert(
+    typeof text === "string" && text.trim().length >= 8 && text.length <= 8e3,
+    "content must contain 8\u20138000 characters"
+  );
+  assert(
+    !/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\b(?:sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{20,})\b/i.test(
+      text
+    ),
+    "content appears to contain a credential"
+  );
+}
+function makeMemory(projectId, rawInput) {
+  const input = newMemorySchema.parse(rawInput);
+  validateText(input.content);
+  assert(
+    [
+      "decision",
+      "constraint",
+      "episode",
+      "procedure",
+      "correction",
+      "task"
+    ].includes(input.kind),
+    "invalid kind"
+  );
+  assert(
+    !/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\b(?:sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{20,})\b/i.test(
+      JSON.stringify(input)
+    ),
+    "memory metadata appears to contain a credential"
+  );
+  assert(
+    input.verification !== "confirmed" || Boolean(input.evidence?.length),
+    "confirmed memories require evidence"
+  );
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return recordSchema.parse({
+    id: randomUUID2(),
+    schemaVersion: 1,
+    revision: 1,
+    projectId,
+    scope: input.scope ?? { level: "project" },
+    applicability: input.applicability ?? {},
+    kind: input.kind,
+    content: input.content.trim(),
+    rationale: input.rationale,
+    cues: input.cues ?? [],
+    entities: input.entities ?? [],
+    evidence: input.evidence ?? [],
+    verification: input.verification ?? "hypothesis",
+    status: input.status ?? "active",
+    createdAt: now,
+    updatedAt: now,
+    createdBy: input.createdBy ?? { client: "cli" },
+    pinned: input.pinned ?? false,
+    expiresAt: input.expiresAt ?? ((input.verification ?? "hypothesis") === "hypothesis" ? new Date(Date.now() + 30 * 864e5).toISOString() : void 0),
+    validFrom: input.validFrom,
+    validUntil: input.validUntil,
+    workspaceId: input.workspaceId,
+    lastVerifiedAt: input.lastVerifiedAt,
+    recallCount: 0,
+    relations: input.relations ?? [],
+    idempotencyKey: input.idempotencyKey
+  });
+}
+function estimateTokens(value) {
+  return Math.ceil(Buffer.byteLength(JSON.stringify(value)) / 3);
+}
+
+// packages/storage-sqlite/src/index.ts
+var SqliteStore = class {
+  constructor(path) {
+    this.path = path;
+    mkdirSync3(dirname3(path), { recursive: true });
+    this.db = new DatabaseSync(path, { timeout: 2500 });
+    this.db.exec(
+      "PRAGMA foreign_keys=ON; PRAGMA journal_mode=WAL; PRAGMA busy_timeout=2500;"
+    );
+    this.migrate();
+  }
+  path;
+  name = "sqlite";
+  db;
+  migrate() {
+    const version = this.db.prepare("PRAGMA user_version").get().user_version;
+    if (version > 1)
+      throw new AppError(
+        "INVALID_CONFIG",
+        "Database schema is newer than this CLI"
+      );
+    if (version === 0) {
+      this.db.exec(`BEGIN IMMEDIATE;
+        CREATE TABLE IF NOT EXISTS memories (id TEXT PRIMARY KEY, project_id TEXT NOT NULL, revision INTEGER NOT NULL,
+          status TEXT NOT NULL, idempotency_key TEXT, body TEXT NOT NULL);
+        CREATE UNIQUE INDEX IF NOT EXISTS memories_idempotency ON memories(project_id,idempotency_key) WHERE idempotency_key IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS memories_project ON memories(project_id,status);
+        CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(id UNINDEXED, project_id UNINDEXED, content, cues, entities);
+        PRAGMA user_version=1; COMMIT;`);
+    }
+  }
+  transaction(fn) {
+    try {
+      this.db.exec("BEGIN IMMEDIATE");
+      const result = fn();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      if (String(error).includes("SQLITE_BUSY"))
+        throw new AppError("STORE_BUSY", "SQLite is busy; retry shortly");
+      throw error;
+    }
+  }
+  find(id) {
+    const row = this.db.prepare("SELECT body FROM memories WHERE id=?").get(id);
+    return row ? recordSchema.parse(JSON.parse(row.body)) : void 0;
+  }
+  get(projectId, id) {
+    const found = this.find(id);
+    if (found && found.projectId !== projectId)
+      throw new AppError(
+        "PROJECT_MISMATCH",
+        "Memory belongs to another project"
+      );
+    return found;
+  }
+  list(projectId) {
+    return this.db.prepare(
+      "SELECT body FROM memories WHERE project_id=? ORDER BY rowid DESC LIMIT 1000"
+    ).all(projectId).map((r) => recordSchema.parse(JSON.parse(r.body)));
+  }
+  create(memory) {
+    return this.transaction(() => {
+      if (memory.idempotencyKey) {
+        const row = this.db.prepare(
+          "SELECT body FROM memories WHERE project_id=? AND idempotency_key=?"
+        ).get(memory.projectId, memory.idempotencyKey);
+        if (row) {
+          const prior = recordSchema.parse(JSON.parse(row.body));
+          if (prior.kind !== memory.kind || prior.content !== memory.content || JSON.stringify(prior.evidence) !== JSON.stringify(memory.evidence) || JSON.stringify(prior.applicability) !== JSON.stringify(memory.applicability))
+            throw new AppError(
+              "IDEMPOTENCY_CONFLICT",
+              "Idempotency key was used for a different event"
+            );
+          return prior;
+        }
+      }
+      this.db.prepare(
+        "INSERT INTO memories(id,project_id,revision,status,idempotency_key,body) VALUES(?,?,?,?,?,?)"
+      ).run(
+        memory.id,
+        memory.projectId,
+        memory.revision,
+        memory.status,
+        memory.idempotencyKey ?? null,
+        JSON.stringify(memory)
+      );
+      this.index(memory);
+      return memory;
+    });
+  }
+  index(memory) {
+    this.db.prepare("DELETE FROM memory_fts WHERE id=?").run(memory.id);
+    this.db.prepare(
+      "INSERT INTO memory_fts(id,project_id,content,cues,entities) VALUES(?,?,?,?,?)"
+    ).run(
+      memory.id,
+      memory.projectId,
+      memory.content,
+      memory.cues.join(" "),
+      memory.entities.join(" ")
+    );
+  }
+  update(memory, expectedRevision) {
+    return this.transaction(() => {
+      const prior = this.get(memory.projectId, memory.id);
+      if (!prior) throw new AppError("NOT_FOUND", "Memory not found");
+      if (prior.revision !== expectedRevision)
+        throw new AppError(
+          "REVISION_CONFLICT",
+          "Memory changed since it was read",
+          { currentRevision: prior.revision }
+        );
+      memory.revision = expectedRevision + 1;
+      memory.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.db.prepare("UPDATE memories SET revision=?,status=?,body=? WHERE id=?").run(memory.revision, memory.status, JSON.stringify(memory), memory.id);
+      this.index(memory);
+      return memory;
+    });
+  }
+  delete(projectId, id) {
+    return this.transaction(() => {
+      const current = this.get(projectId, id);
+      if (!current) return false;
+      const all = this.db.prepare("SELECT body FROM memories WHERE project_id=?").all(projectId).map((row) => recordSchema.parse(JSON.parse(row.body)));
+      const removed = /* @__PURE__ */ new Set([id]);
+      let changed = true;
+      while (changed) {
+        changed = false;
+        for (const m of all)
+          if (!removed.has(m.id) && m.relations.some(
+            (r) => r.type === "derived_from" && removed.has(r.targetId)
+          )) {
+            removed.add(m.id);
+            changed = true;
+          }
+      }
+      const derived = all.filter((m) => removed.has(m.id) && m.id !== id);
+      for (const m of derived) {
+        this.db.prepare("DELETE FROM memory_fts WHERE id=?").run(m.id);
+        this.db.prepare("DELETE FROM memories WHERE id=?").run(m.id);
+      }
+      this.db.prepare("DELETE FROM memory_fts WHERE id=?").run(id);
+      this.db.prepare("DELETE FROM memories WHERE id=?").run(id);
+      for (const m of all.filter((record) => !removed.has(record.id))) {
+        const relations = m.relations.filter((r) => !removed.has(r.targetId));
+        if (relations.length !== m.relations.length) {
+          m.relations = relations;
+          m.revision++;
+          m.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+          this.db.prepare("UPDATE memories SET revision=?,body=? WHERE id=?").run(m.revision, JSON.stringify(m), m.id);
+        }
+      }
+      return true;
+    });
+  }
+  search(projectId, query, limit) {
+    const terms = [
+      ...new Set(query.toLowerCase().match(/[\p{L}\p{N}_]{3,}/gu) ?? [])
+    ].slice(0, 12);
+    if (!terms.length) return [];
+    const expression = terms.map((t) => `"${t.replaceAll('"', "")}"`).join(" OR ");
+    const rows = this.db.prepare(
+      `SELECT m.body FROM memory_fts f JOIN memories m ON m.id=f.id
+      WHERE memory_fts MATCH ? AND m.project_id=? ORDER BY bm25(memory_fts) LIMIT ?`
+    ).all(expression, projectId, Math.min(limit, 100));
+    return rows.map((r) => recordSchema.parse(JSON.parse(r.body)));
+  }
+  close() {
+    this.db.close();
+  }
+};
+
+// packages/core/src/service.ts
+var Service = class {
+  constructor(store, projectId) {
+    this.store = store;
+    this.projectId = projectId;
+  }
+  store;
+  projectId;
+  remember(input) {
+    for (const relation of input.relations ?? [])
+      this.inspect(relation.targetId);
+    return this.store.create(makeMemory(this.projectId, input));
+  }
+  inspect(id) {
+    const m = this.store.get(this.projectId, id);
+    if (!m) throw new AppError("NOT_FOUND", "Memory not found");
+    return m;
+  }
+  revise(id, content, revision, patch = {}) {
+    if (!Number.isInteger(revision) || revision < 1)
+      throw new AppError(
+        "INVALID_INPUT",
+        "expectedRevision must be a positive integer"
+      );
+    if (content !== void 0) validateText(content);
+    const m = this.inspect(id);
+    return this.store.update(
+      recordSchema.parse({
+        ...m,
+        ...patch,
+        ...content !== void 0 ? { content } : {}
+      }),
+      revision
+    );
+  }
+  recall(query, budget = 1500, environment, workspace, component) {
+    if (!Number.isInteger(budget) || budget < 1 || budget > 1e4)
+      throw new AppError(
+        "INVALID_INPUT",
+        "Budget must be an integer between 1 and 10000"
+      );
+    const result = {
+      schemaVersion: 1,
+      estimator: "UTF-8 bytes / 3, conservative estimate",
+      memories: []
+    };
+    if (budget < estimateTokens(result))
+      throw new AppError(
+        "BUDGET_TOO_SMALL",
+        "Budget cannot fit response metadata"
+      );
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const m of this.store.search(this.projectId, query, 100)) {
+      if (m.scope.level === "component" && m.scope.component !== component)
+        continue;
+      if (m.workspaceId && m.workspaceId !== workspace) continue;
+      if (m.status !== "active" || m.expiresAt && m.expiresAt < now || m.validUntil && m.validUntil < now || m.validFrom && m.validFrom > now)
+        continue;
+      if (m.applicability.environments?.length && !m.applicability.environments.includes(environment ?? ""))
+        continue;
+      if (m.applicability.workspaces?.length && !m.applicability.workspaces.includes(workspace ?? ""))
+        continue;
+      const capsule = {
+        id: m.id,
+        revision: m.revision,
+        content: m.content,
+        rationale: m.rationale,
+        verification: m.verification,
+        evidence: m.evidence,
+        relations: m.relations,
+        reason: "lexical term match; active and applicable"
+      };
+      result.memories.push(capsule);
+      if (estimateTokens(result) > budget) result.memories.pop();
+    }
+    return result;
+  }
+  feedback(id, useful) {
+    const m = this.inspect(id);
+    return this.store.update(
+      {
+        ...m,
+        utilityFeedback: [
+          ...m.utilityFeedback ?? [],
+          { useful, observedAt: (/* @__PURE__ */ new Date()).toISOString() }
+        ].slice(-100)
+      },
+      m.revision
+    );
+  }
+  forget(id) {
+    return { deleted: this.store.delete(this.projectId, id) };
+  }
+};
+
+// packages/mcp/src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z3 } from "zod";
+async function serve(service, check = () => {
+}) {
+  const server = new McpServer({ name: "hippocampus", version: "0.1.0" });
+  const register = (name, shape, fn) => server.registerTool(
+    "hippocampus_" + name,
+    { inputSchema: shape },
+    async (a) => {
+      try {
+        check();
+        const value = fn(a);
+        return {
+          content: [{ type: "text", text: JSON.stringify(value) }],
+          structuredContent: value
+        };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                code: e.code ?? "INVALID_INPUT",
+                message: String(e)
+              })
+            }
+          ]
+        };
+      }
+    }
+  );
+  register(
+    "recall",
+    {
+      query: z3.string().max(2e3),
+      budget: z3.number().int().min(100).max(1e4).optional(),
+      component: z3.string().optional(),
+      environment: z3.string().optional(),
+      workspace: z3.string().optional()
+    },
+    (a) => service.recall(
+      a.query,
+      a.budget,
+      a.environment,
+      a.workspace,
+      a.component
+    )
+  );
+  register(
+    "remember",
+    {
+      kind: z3.enum([
+        "decision",
+        "constraint",
+        "episode",
+        "procedure",
+        "correction",
+        "task"
+      ]),
+      content: z3.string().max(8e3),
+      rationale: z3.string().max(4e3).optional(),
+      verification: z3.enum(["hypothesis", "observed", "confirmed"]).optional(),
+      evidence: z3.array(evidenceSchema).max(30).optional(),
+      relations: z3.array(relationSchema).max(30).optional(),
+      applicability: z3.object({
+        environments: z3.array(z3.string()).max(20).optional(),
+        workspaces: z3.array(z3.string()).max(20).optional()
+      }).optional(),
+      idempotencyKey: z3.string().max(200).optional()
+    },
+    (a) => service.remember(a)
+  );
+  register("inspect", { id: z3.string().uuid() }, (a) => service.inspect(a.id));
+  register(
+    "revise",
+    {
+      id: z3.string().uuid(),
+      content: z3.string().max(8e3).optional(),
+      status: z3.enum(["active", "superseded", "archived", "expired"]).optional(),
+      pinned: z3.boolean().optional(),
+      expectedRevision: z3.number().int().positive()
+    },
+    (a) => service.revise(a.id, a.content, a.expectedRevision, {
+      ...a.status ? { status: a.status } : {},
+      ...a.pinned !== void 0 ? { pinned: a.pinned } : {}
+    })
+  );
+  register("forget", { id: z3.string().uuid() }, (a) => service.forget(a.id));
+  register(
+    "feedback",
+    { id: z3.string().uuid(), useful: z3.boolean() },
+    (a) => service.feedback(a.id, a.useful)
+  );
+  let closed = false;
+  const closeStore = () => {
+    if (!closed) {
+      closed = true;
+      service.store.close();
+    }
+  };
+  server.server.onclose = closeStore;
+  const close = async () => {
+    await server.close();
+    closeStore();
+  };
+  process.once("SIGINT", () => void close());
+  process.once("SIGTERM", () => void close());
+  await server.connect(new StdioServerTransport());
+}
+
+// packages/core/src/providers.ts
+var providerRegistry = {
+  stores: [
+    { name: "sqlite", implemented: true, canonical: true },
+    { name: "postgresql", implemented: false, canonical: true }
+  ],
+  vectors: [
+    { name: "none", implemented: true },
+    { name: "qdrant", implemented: false },
+    { name: "pgvector", implemented: false }
+  ],
+  embeddings: [{ name: "none", implemented: true }]
+};
+
+// packages/cli/src/index.ts
+var { positionals: p, values: v } = parseArgs({
+  allowPositionals: true,
+  options: {
+    component: { type: "string" },
+    status: { type: "string" },
+    pinned: { type: "string" },
+    "expires-at": { type: "string" },
+    input: { type: "string" },
+    environment: { type: "string" },
+    workspace: { type: "string" },
+    project: { type: "string" },
+    kind: { type: "string" },
+    content: { type: "string" },
+    source: { type: "string" },
+    budget: { type: "string" },
+    "expected-revision": { type: "string" },
+    transport: { type: "string" },
+    scope: { type: "string" },
+    json: { type: "boolean" },
+    "dry-run": { type: "boolean" }
+  }
+});
+var output = (x) => console.log(JSON.stringify(x, null, 2));
+async function main() {
+  const command = p[0];
+  let base = resolve2(String(v.project ?? process.cwd()));
+  if (command === "init") {
+    base = realpathSync2(base);
+    if (!existsSync3(configPath(base))) atomic(configPath(base), defaults());
+    const c2 = load(base);
+    new SqliteStore(database(base, c2)).close();
+    const ignore = join3(base, ".gitignore");
+    const old = existsSync3(ignore) ? readFileSync3(ignore, "utf8") : "";
+    for (const rule of [
+      ".hippocampus/*.sqlite",
+      ".hippocampus/*.sqlite-*",
+      ".hippocampus/local.json"
+    ])
+      if (!old.split("\n").includes(rule))
+        appendFileSync(ignore, "\n" + rule + "\n");
+    output({ project: base, projectId: c2.projectId });
+    return;
+  }
+  if (!command || command === "help") {
+    console.log(
+      "hippocampus init | config [show|get|set|validate|test] | remember | recall | memories | inspect | revise | forget | doctor | serve | connect"
+    );
+    return;
+  }
+  if (command === "config" && v.scope === "user") {
+    const user = userDefaults();
+    if (p[1] === "show") {
+      output(user);
+      return;
+    }
+    if (p[1] === "validate") {
+      output({ valid: true });
+      return;
+    }
+    if (p[1] === "set") {
+      const keys = (p[2] ?? "").split(".");
+      if (keys.includes("projectId") || keys.some((k) => ["__proto__", "constructor", "prototype"].includes(k)))
+        throw Error("Invalid user field");
+      let target = user;
+      for (const key of keys.slice(0, -1)) {
+        target[key] ??= {};
+        target = target[key];
+      }
+      let value = p[3];
+      try {
+        value = JSON.parse(value);
+      } catch {
+      }
+      target[keys.at(-1)] = value;
+      saveUser(user);
+      output(user);
+      return;
+    }
+    if (p[1] === "get") {
+      let value = user;
+      for (const key of (p[2] ?? "").split(".")) value = value?.[key];
+      if (value === void 0) throw Error("No user override for field");
+      output(value);
+      return;
+    }
+    if (!p[1]) {
+      if (!process.stdin.isTTY)
+        throw Error(
+          "Interactive config requires a TTY; use config show/get/set/validate --scope user"
+        );
+      const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      try {
+        console.log(
+          "User defaults apply before project configuration. SQLite remains the canonical store."
+        );
+        const budget = await rl.question("Default context budget [1500]: ");
+        const next = {
+          ...user,
+          retrieval: {
+            ...user.retrieval ?? {},
+            maxContextTokens: budget ? Number(budget) : 1500
+          }
+        };
+        output(next);
+        if ((await rl.question("Save? [y/N] ")).toLowerCase() === "y")
+          saveUser(next);
+      } finally {
+        rl.close();
+      }
+      return;
+    }
+    throw Error("Use config show/get/set/validate --scope user");
+  }
+  base = root(base);
+  const c = effective(base);
+  if (command === "config") {
+    if (v.scope && v.scope !== "project")
+      throw Error("Unsupported configuration scope");
+    if (p[1] === "show") {
+      output(c);
+      return;
+    }
+    if (p[1] === "validate") {
+      output({ valid: true });
+      return;
+    }
+    if (p[1] === "get") {
+      let x = c;
+      for (const key of (p[2] ?? "").split(".")) x = x?.[key];
+      if (x === void 0) throw Error("Unknown configuration field");
+      output(x);
+      return;
+    }
+    if (p[1] === "set") {
+      const candidate = load(base);
+      const keys = (p[2] ?? "").split(".");
+      if (keys.some((k) => ["__proto__", "constructor", "prototype"].includes(k)))
+        throw Error("Invalid field");
+      let target = candidate;
+      for (const key of keys.slice(0, -1)) {
+        if (!target[key]) throw Error("Unknown field");
+        target = target[key];
+      }
+      let value = p[3];
+      try {
+        value = JSON.parse(value);
+      } catch {
+      }
+      target[keys.at(-1)] = value;
+      const next = schema.parse(candidate);
+      if (next.projectId !== c.projectId)
+        throw Error("Project identity cannot be changed");
+      if (database(base, next) !== database(base, c)) {
+        const store2 = new SqliteStore(database(base, c));
+        const count = store2.list(c.projectId).length;
+        store2.close();
+        if (count)
+          throw Error(
+            "Cannot change a nonempty store path; store migration is not implemented"
+          );
+      }
+      atomic(configPath(base), next);
+      output(next);
+      return;
+    }
+    if (!p[1]) {
+      if (!process.stdin.isTTY)
+        throw Error(
+          "Interactive config requires a TTY; use config show/get/set/validate/test"
+        );
+      const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      try {
+        console.log(
+          "SQLite is the canonical store; FTS5 is the retrieval index. Vector providers are planned."
+        );
+        const budget = await rl.question("Context budget [1500]: ");
+        const next = schema.parse({
+          ...c,
+          retrieval: {
+            ...c.retrieval,
+            maxContextTokens: budget ? Number(budget) : 1500
+          }
+        });
+        output(next);
+        if ((await rl.question("Save? [y/N] ")).toLowerCase() === "y")
+          atomic(configPath(base), next);
+      } finally {
+        rl.close();
+      }
+      return;
+    }
+  }
+  if (command === "connect" || command === "disconnect") {
+    output(
+      connect(
+        p[1] ?? "",
+        base,
+        resolve2(process.argv[1]),
+        v.scope ?? "project",
+        v["dry-run"] ?? false,
+        command === "disconnect"
+      )
+    );
+    return;
+  }
+  const store = new SqliteStore(database(base, c));
+  const service = new Service(store, c.projectId);
+  if (command === "serve") {
+    if (typeof v.project !== "string" || !isAbsolute(v.project))
+      throw Error("serve requires an absolute --project path");
+    if (v.transport && v.transport !== "stdio")
+      throw Error("Only stdio is supported");
+    const snapshot = JSON.stringify(c);
+    await serve(service, () => {
+      if (JSON.stringify(effective(base)) !== snapshot)
+        throw Error("Configuration changed; restart MCP server");
+    });
+    return;
+  }
+  try {
+    switch (command) {
+      case "config":
+        if (p[1] !== "test") throw Error("Unknown config command");
+        output({ connected: true, provider: "sqlite" });
+        break;
+      case "remember":
+        if (v.input) {
+          const raw = readFileSync3(resolve2(v.input), "utf8");
+          if (Buffer.byteLength(raw) > 32e3)
+            throw Error("Input file exceeds 32KB");
+          output(service.remember(JSON.parse(raw)));
+          break;
+        }
+        output(
+          service.remember({
+            kind: v.kind,
+            content: String(v.content ?? ""),
+            evidence: v.source ? [{ type: "other", reference: String(v.source) }] : []
+          })
+        );
+        break;
+      case "recall":
+        output(
+          service.recall(
+            p[1] ?? "",
+            Number(v.budget ?? c.retrieval.maxContextTokens),
+            v.environment,
+            v.workspace,
+            v.component
+          )
+        );
+        break;
+      case "memories":
+        output(store.list(c.projectId));
+        break;
+      case "inspect":
+        output(service.inspect(p[1] ?? ""));
+        break;
+      case "revise":
+        output(
+          service.revise(
+            p[1] ?? "",
+            v.content,
+            Number(v["expected-revision"]),
+            {
+              ...v.status ? { status: v.status } : {},
+              ...v.pinned ? { pinned: v.pinned === "true" } : {},
+              ...v["expires-at"] ? { expiresAt: v["expires-at"] } : {}
+            }
+          )
+        );
+        break;
+      case "forget":
+        output(service.forget(p[1] ?? ""));
+        break;
+      case "doctor":
+        output({
+          projectId: c.projectId,
+          database: database(base, c),
+          providers: providerRegistry,
+          telemetry: false
+        });
+        break;
+      case "consolidate":
+        if (!v["dry-run"]) throw Error("Only review previews are supported");
+        output({
+          proposals: store.list(c.projectId).filter(
+            (m) => m.expiresAt && m.expiresAt < (/* @__PURE__ */ new Date()).toISOString()
+          ).map((m) => ({ id: m.id, action: "review expiry" }))
+        });
+        break;
+      default:
+        throw Error("Unknown command");
+    }
+  } finally {
+    store.close();
+  }
+}
+main().catch((e) => {
+  console.error(
+    JSON.stringify({ code: e.code ?? "INVALID_INPUT", message: e.message })
+  );
+  process.exitCode = e.code === "REVISION_CONFLICT" ? 3 : 1;
+});