@memstack/mcp 0.7.3 → 0.8.1

package/dist/cli.js

@@ -1,63 +1,213 @@
 #!/usr/bin/env node
 import { parseArgs } from 'util';
 import { createServer as createServer$1 } from 'http';
-import { MemStack, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter, InMemoryStorageAdapter } from '@memstack/core';
-import { readFileSync } from 'fs';
+import { MemStack, InMemoryStorageAdapter, HarnessMemory, defaultRecallNamespaces, projectNamespace, GLOBAL_NAMESPACE, MemStackError, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter } from '@memstack/core';
+import { readFileSync, realpathSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { resolve, join, dirname } from 'path';
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
-function buildLLMAdapter() {
-  if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY) {
+var STORAGE_TYPES = ["memory", "markdown", "disk", "postgres", "sqlite", "redis"];
+function memstackHome() {
+  return process.env.MEMSTACK_HOME ?? join(homedir(), ".memstack");
+}
+function configFilePath(home = memstackHome()) {
+  return join(home, "config.json");
+}
+function readConfigFile(path = configFilePath()) {
+  if (!existsSync(path)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+  return validateConfigFile(parsed, path);
+}
+function validateConfigFile(value, path) {
+  const fail = (message) => {
+    throw new Error(`Invalid ${path}: ${message}`);
+  };
+  if (!isObject(value)) fail("expected a JSON object");
+  const config = value;
+  if (config.version !== 1) fail(`unsupported version ${JSON.stringify(config.version)}, expected 1`);
+  if (config.llm !== void 0) {
+    if (!isObject(config.llm)) fail("llm must be an object");
+    const llm = config.llm;
+    if (llm.provider !== "openai-compatible" && llm.provider !== "anthropic") {
+      fail('llm.provider must be "openai-compatible" or "anthropic"');
+    }
+    if (typeof llm.apiKey !== "string" || !llm.apiKey) fail("llm.apiKey must be a non-empty string");
+    for (const key of ["baseURL", "model"]) {
+      if (llm[key] !== void 0 && typeof llm[key] !== "string") fail(`llm.${key} must be a string`);
+    }
+  }
+  if (config.storage !== void 0) {
+    if (!isObject(config.storage)) fail("storage must be an object");
+    const storage = config.storage;
+    if (!STORAGE_TYPES.includes(storage.type)) {
+      fail(`storage.type must be one of ${STORAGE_TYPES.join(", ")}`);
+    }
+    for (const key of ["path", "url"]) {
+      if (storage[key] !== void 0 && typeof storage[key] !== "string") fail(`storage.${key} must be a string`);
+    }
+  }
+  return config;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var PIN_FILE = ".memstack.json";
+var PIN_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+function resolveProject(cwd = process.cwd()) {
+  const dir = realpathSync(resolve(cwd));
+  const root = git(dir, ["rev-parse", "--show-toplevel"]);
+  const base = root ?? dir;
+  const pinned = readPin(base);
+  const fallbacks = transitionalIds(dir, root);
+  if (pinned) return { id: pinned, source: "pin", key: pinned, root: base, previousIds: [] };
+  if (!root) return { ...identity("directory", dir), root: dir, previousIds: [] };
+  const shallow = git(root, ["rev-parse", "--is-shallow-repository"]) === "true";
+  const rootCommit = shallow ? null : firstCommit(root);
+  if (rootCommit) return { ...identity("root-commit", rootCommit), root, previousIds: fallbacks };
+  const remote = git(root, ["config", "--get", "remote.origin.url"]);
+  const normalized = shallow && remote ? normalizeRemote(remote) : null;
+  if (normalized) return { ...identity("remote", normalized), root, previousIds: fallbacks };
+  const gitId = identity("git", gitRepoKey(root));
+  return { ...gitId, root, previousIds: fallbacks.filter((id) => id !== gitId.id) };
+}
+function normalizeRemote(url) {
+  const value = url.trim();
+  if (!value) return null;
+  let host;
+  let path;
+  const scp = value.match(/^(?:[^@/]+@)?([^:/]+):(?!\/)(.+)$/);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+    let parsed;
+    try {
+      parsed = new URL(value);
+    } catch {
+      return null;
+    }
+    if (parsed.protocol === "file:" || !parsed.hostname) return null;
+    host = parsed.hostname;
+    path = decodeURIComponent(parsed.pathname);
+  } else if (scp) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    return null;
+  }
+  path = path.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "");
+  if (!path) return null;
+  return `${host.toLowerCase()}/${path}`;
+}
+function readPin(base) {
+  const path = join(base, PIN_FILE);
+  if (!existsSync(path)) return null;
+  let project;
+  try {
+    project = JSON.parse(readFileSync(path, "utf8")).project;
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+  if (project === void 0) return null;
+  if (typeof project !== "string" || !PIN_PATTERN.test(project)) {
+    throw new Error(`${path}: "project" must use letters, digits, '.', '_', or '-' and be at most 64 characters.`);
+  }
+  return project;
+}
+function firstCommit(root) {
+  const out = git(root, ["rev-list", "--max-parents=0", "--first-parent", "HEAD"]);
+  return out ? out.split("\n").pop().trim() : null;
+}
+function gitRepoKey(root) {
+  const commonDir = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  return commonDir ? dirname(realpathSync(commonDir)) : root;
+}
+function transitionalIds(dir, root) {
+  const ids = /* @__PURE__ */ new Set();
+  if (root) ids.add(identity("git", gitRepoKey(root)).id);
+  ids.add(identity("directory", dir).id);
+  return [...ids];
+}
+function identity(source, key) {
+  const id = createHash("sha256").update(`${source}:${key}`).digest("hex").slice(0, 16);
+  return { id, source, key };
+}
+function git(cwd, args) {
+  try {
+    const out = execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+function isMissingModule(error) {
+  const code = error?.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+function buildLLMAdapter(env) {
+  if (!env.ANTHROPIC_API_KEY && !env.OPENAI_API_KEY) {
     throw new Error("At least one of OPENAI_API_KEY or ANTHROPIC_API_KEY must be set");
   }
-  if (process.env.ANTHROPIC_API_KEY) {
-    return new AnthropicLLMAdapter({ apiKey: process.env.ANTHROPIC_API_KEY });
+  if (env.ANTHROPIC_API_KEY) {
+    return new AnthropicLLMAdapter({ apiKey: env.ANTHROPIC_API_KEY, defaultModel: env.MEMSTACK_LLM_MODEL });
   }
   return new OpenAILLMAdapter({
-    apiKey: process.env.OPENAI_API_KEY ?? "",
-    baseURL: process.env.MEMSTACK_OPENAI_BASE_URL,
-    defaultModel: process.env.MEMSTACK_LLM_MODEL
+    apiKey: env.OPENAI_API_KEY ?? "",
+    baseURL: env.MEMSTACK_OPENAI_BASE_URL,
+    defaultModel: env.MEMSTACK_LLM_MODEL
   });
 }
-function buildEmbeddingAdapter() {
-  if (process.env.MEMSTACK_OPENAI_BASE_URL) return void 0;
-  if (process.env.OPENAI_API_KEY) {
-    return new OpenAIEmbeddingAdapter({ apiKey: process.env.OPENAI_API_KEY });
+function buildEmbeddingAdapter(env) {
+  if (env.MEMSTACK_OPENAI_BASE_URL) return void 0;
+  if (env.OPENAI_API_KEY) {
+    return new OpenAIEmbeddingAdapter({ apiKey: env.OPENAI_API_KEY });
   }
   return void 0;
 }
-async function buildStorageAdapter() {
-  const storage = process.env.MEMSTACK_STORAGE ?? "memory";
+async function buildStorageAdapter(env) {
+  const storage = env.MEMSTACK_STORAGE ?? "memory";
   switch (storage) {
     case "memory":
       return new InMemoryStorageAdapter();
     case "markdown":
       return new MarkdownStorageAdapter({
-        dir: process.env.MEMSTACK_DIR ?? "./memories"
+        dir: env.MEMSTACK_DIR ?? "./memories"
       });
     case "disk":
       return new DiskStorageAdapter({
-        storageDir: process.env.MEMSTACK_DIR ?? "./memstack-data"
+        storageDir: env.MEMSTACK_DIR ?? "./memstack-data"
       });
     case "postgres":
-      if (!process.env.DATABASE_URL) {
+      if (!env.DATABASE_URL) {
         throw new Error("postgres storage requires DATABASE_URL");
       }
       return new PostgresStorageAdapter({
-        connectionString: process.env.DATABASE_URL
+        connectionString: env.DATABASE_URL
       });
     case "sqlite": {
       try {
         const BetterSqlite3 = await import('better-sqlite3');
         const db = new BetterSqlite3.default(
-          process.env.SQLITE_PATH ?? "./memstack.db"
+          env.SQLITE_PATH ?? "./memstack.db"
         );
         return new SQLiteStorageAdapter({ db });
-      } catch {
+      } catch (error) {
+        if (!isMissingModule(error)) throw error;
         throw new Error(
-          "SQLite requires better-sqlite3. Install: npm install better-sqlite3"
+          "SQLite requires better-sqlite3. Install: npm install better-sqlite3@^11.10.0"
         );
       }
     }
@@ -65,12 +215,13 @@ async function buildStorageAdapter() {
       try {
         const Redis = await import('ioredis');
         const client = new Redis.default(
-          process.env.REDIS_URL ?? "redis://localhost:6379"
+          env.REDIS_URL ?? "redis://localhost:6379"
         );
         return new RedisStorageAdapter({ redis: client });
-      } catch {
+      } catch (error) {
+        if (!isMissingModule(error)) throw error;
         throw new Error(
-          "Redis requires ioredis. Install: npm install ioredis"
+          "Redis requires ioredis. Install: npm install ioredis@^5.11.1"
         );
       }
     }
@@ -79,11 +230,39 @@ async function buildStorageAdapter() {
   }
 }
 async function loadConfigFromEnv() {
-  const llm = buildLLMAdapter();
-  const embedding = buildEmbeddingAdapter();
-  const storage = await buildStorageAdapter();
-  const embedOnStore = process.env.MEMSTACK_EMBED_ON_STORE !== "false";
-  const defaultActorId = process.env.MEMSTACK_ACTOR ?? "default";
+  return buildConfig(process.env);
+}
+async function loadConfig(options = {}) {
+  return buildConfig(mergeConfigFile(readConfigFile(options.configPath), process.env));
+}
+function mergeConfigFile(file, env) {
+  const merged = { ...env };
+  const envHasLLM = LLM_ENV.some((key) => env[key] !== void 0);
+  if (file?.llm && !envHasLLM) {
+    if (file.llm.provider === "anthropic") merged.ANTHROPIC_API_KEY = file.llm.apiKey;
+    else {
+      merged.OPENAI_API_KEY = file.llm.apiKey;
+      merged.MEMSTACK_OPENAI_BASE_URL = file.llm.baseURL;
+    }
+    merged.MEMSTACK_LLM_MODEL = file.llm.model;
+  }
+  if (file?.storage && env.MEMSTACK_STORAGE === void 0) {
+    const { type, path, url } = file.storage;
+    merged.MEMSTACK_STORAGE = type;
+    if (type === "sqlite") merged.SQLITE_PATH = path;
+    if (type === "disk" || type === "markdown") merged.MEMSTACK_DIR = path;
+    if (type === "postgres") merged.DATABASE_URL = url;
+    if (type === "redis") merged.REDIS_URL = url;
+  }
+  return merged;
+}
+var LLM_ENV = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "MEMSTACK_OPENAI_BASE_URL", "MEMSTACK_LLM_MODEL"];
+async function buildConfig(env) {
+  const llm = buildLLMAdapter(env);
+  const embedding = buildEmbeddingAdapter(env);
+  const storage = await buildStorageAdapter(env);
+  const embedOnStore = env.MEMSTACK_EMBED_ON_STORE !== "false";
+  const defaultActorId = env.MEMSTACK_ACTOR ?? "default";
   return {
     config: { llm, embedding, storage, defaults: { embedOnStore } },
     defaultActorId
@@ -91,9 +270,12 @@ async function loadConfigFromEnv() {
 }
 
 // src/config.ts
-async function loadConfig() {
+async function loadConfig2() {
   return loadConfigFromEnv();
 }
+async function loadHarnessConfig() {
+  return loadConfig();
+}
 var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 var TOOLS = [
   {
@@ -106,7 +288,7 @@ var TOOLS = [
         actorId: { type: "string", description: "Actor ID. Defaults to the current session actor." },
         importance: { type: "number", description: "Importance score (0.0-1.0). Auto-scored if omitted." },
         tags: { type: "array", items: { type: "string" }, description: "Tags for categorization. Auto-extracted if omitted." },
-        memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection). Default: interaction." },
+        memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection, preference, decision, instruction). Default: interaction." },
         metadata: { type: "object", description: "Additional metadata key-value pairs" }
       },
       required: ["content"]
@@ -122,7 +304,7 @@ var TOOLS = [
         actorId: { type: "string", description: "Actor ID. Defaults to the current session actor." },
         importance: { type: "number", description: "Importance score 0.0-1.0. Default: 0.5." },
         tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" },
-        memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection). Default: interaction." },
+        memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection, preference, decision, instruction). Default: interaction." },
         metadata: { type: "object", description: "Additional metadata key-value pairs" }
       },
       required: ["content"]
@@ -144,7 +326,7 @@ var TOOLS = [
               actorId: { type: "string", description: "Actor ID. Defaults to the current session actor." },
               importance: { type: "number", description: "Importance score 0.0-1.0. Default: 0.5." },
               tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" },
-              memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection). Default: interaction." },
+              memoryType: { type: "string", description: "Memory type (interaction, summary, observation, fact, reflection, preference, decision, instruction). Default: interaction." },
               metadata: { type: "object", description: "Additional metadata key-value pairs" }
             },
             required: ["content"]
@@ -714,21 +896,293 @@ function createServer({
   });
   return server;
 }
+var pkg2 = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+var KINDS = [
+  "fact",
+  "preference",
+  "decision",
+  "instruction",
+  "observation",
+  "interaction",
+  "summary",
+  "reflection"
+];
+var HARNESS_INSTRUCTIONS = [
+  "MemStack is this project's persistent memory, shared with other coding agents.",
+  "When the user asks you to remember something, call memory_store. Do not write it into README, AGENTS.md, or other project files unless the user asks for a file change.",
+  "Also call memory_store when you learn a durable fact, decision, preference, or rule.",
+  "Call memory_retrieve at the start of a task and before decisions that depend on project history, conventions, or preferences.",
+  "Never store secrets, credentials, or personal data.",
+  "",
+  'Store one self-contained statement per memory, e.g. "This project uses Hono for the API". Memories are project-scoped; use scope "global" only for preferences that apply to every project. memory_retrieve takes natural-language questions. Cite memory IDs when you rely on them, and delete memories that turn out to be wrong with memory_delete.'
+].join("\n");
+var StoreArgs = z.object({
+  content: z.string().trim().min(1).max(8e3).describe("One self-contained statement to remember."),
+  kind: z.enum(KINDS).default("fact").describe("What kind of memory this is."),
+  importance: z.number().min(0).max(1).optional().describe("0 to 1. Default 0.5; use 0.8+ for rules that must not be missed."),
+  tags: z.array(z.string().trim().min(1).max(40)).max(10).optional().describe("Optional topic tags. MemStack adds its own."),
+  scope: z.enum(["project", "global"]).default("project").describe('"global" only for preferences that apply to every project.')
+}).strict();
+var RetrieveArgs = z.object({
+  query: z.string().max(1e3).optional().describe("Natural-language question or keywords. Omit to get the most important memories."),
+  limit: z.number().int().min(1).max(25).default(10).describe("Maximum memories to return."),
+  kinds: z.array(z.enum(KINDS)).optional().describe("Only return these kinds.")
+}).strict();
+var IdArgs = z.object({ id: z.string().min(1).max(200) }).strict();
+var NoArgs = z.object({}).strict();
+var TOOLS2 = [
+  {
+    name: "memory_store",
+    description: "Save to project memory. Use this whenever the user asks you to remember something, instead of editing project files, and for durable facts, decisions, preferences, or rules. Later sessions and other agents can recall it.",
+    schema: StoreArgs
+  },
+  {
+    name: "memory_retrieve",
+    description: "Recall memories for this project (and global preferences) relevant to a question. Fast and local; call it freely.",
+    schema: RetrieveArgs
+  },
+  { name: "memory_get", description: "Get one memory by ID.", schema: IdArgs },
+  { name: "memory_delete", description: "Delete a memory that is wrong or outdated, by ID.", schema: IdArgs },
+  { name: "memory_stats", description: "Show the current project and how many memories it has.", schema: NoArgs }
+];
+var RECALL_MAX_CHARS = 8e3;
+function createHarnessServer({ memory, projectId, harness, cwd }) {
+  const server = new Server(
+    { name: "memstack", version: pkg2.version },
+    { capabilities: { tools: {} }, instructions: HARNESS_INSTRUCTIONS }
+  );
+  const project = projectNamespace(projectId);
+  const namespaces = defaultRecallNamespaces(projectId);
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS2.map(({ name, description, schema }) => ({
+      name,
+      description,
+      inputSchema: z.toJSONSchema(schema, { io: "input" })
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = TOOLS2.find((t) => t.name === request.params.name);
+    if (!tool) return failure(`Unknown tool: ${request.params.name}`);
+    const parsed = tool.schema.safeParse(request.params.arguments ?? {});
+    if (!parsed.success) {
+      return failure(`Invalid arguments for ${tool.name}: ${z.prettifyError(parsed.error)}`);
+    }
+    try {
+      switch (tool.name) {
+        case "memory_store": {
+          const args = parsed.data;
+          const stored = await memory.remember({
+            namespace: args.scope === "global" ? GLOBAL_NAMESPACE : project,
+            content: args.content,
+            kind: args.kind,
+            importance: args.importance,
+            tags: args.tags,
+            source: {
+              harness: harness ?? server.getClientVersion()?.name ?? "unknown",
+              project: projectId,
+              cwd
+            }
+          });
+          return text(`Stored ${stored.id} (${args.scope}, ${stored.memoryType}). Tags: ${stored.tags.join(", ") || "none"}.`);
+        }
+        case "memory_retrieve": {
+          const args = parsed.data;
+          const { hits, fallback } = await memory.recall({
+            namespaces,
+            query: args.query,
+            kinds: args.kinds,
+            limit: args.limit,
+            maxChars: RECALL_MAX_CHARS
+          });
+          if (hits.length === 0) return text("No memories yet for this project.");
+          const header = fallback && args.query ? `Nothing matched "${args.query}". The most important memories instead:` : `${hits.length} ${hits.length === 1 ? "memory" : "memories"}:`;
+          return text([header, ...hits.map(({ memory: m }) => formatMemory(m, projectId))].join("\n"));
+        }
+        case "memory_get": {
+          const { id } = parsed.data;
+          const found = await memory.get(id, namespaces);
+          return found ? text(formatMemory(found, projectId, true)) : failure(`Memory not found in this project: ${id}`);
+        }
+        case "memory_delete": {
+          const { id } = parsed.data;
+          await memory.forget(id, namespaces);
+          return text(`Deleted ${id}.`);
+        }
+        case "memory_stats": {
+          const counts = await memory.stats(namespaces);
+          return text(
+            `Project ${projectId}${cwd ? ` (${cwd})` : ""}: ${counts[project] ?? 0} memories. Global: ${counts[GLOBAL_NAMESPACE] ?? 0}.`
+          );
+        }
+      }
+    } catch (error) {
+      if (error instanceof MemStackError && error.code === "NOT_FOUND") {
+        return failure(`Memory not found in this project: ${parsed.data.id ?? ""}`);
+      }
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+  });
+  return server;
+}
+function formatMemory(m, projectId, detailed = false) {
+  const scope = m.actorId === GLOBAL_NAMESPACE ? "global" : "project";
+  const source = m.metadata?.source?.harness;
+  const meta = [m.memoryType, scope, source && `from ${source}`, m.createdAt.toISOString().slice(0, 10)].filter(Boolean);
+  const line = `- [${m.id}] ${m.content} (${meta.join(", ")})`;
+  if (!detailed) return line;
+  return `${line}
+importance: ${m.importance}
+tags: ${m.tags.join(", ") || "none"}
+project: ${scope === "project" ? projectId : "all"}`;
+}
+function text(message) {
+  return { content: [{ type: "text", text: message }] };
+}
+function failure(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+var HOOK_MAX_CHARS = 6e3;
+var HOOK_LIMIT = 15;
+async function sessionStartContext(input, env = process.env) {
+  const cwd = env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
+  const project = resolveProject(cwd);
+  const { config } = await loadConfig();
+  const storage = config.storage ?? new InMemoryStorageAdapter();
+  try {
+    const memory = new HarnessMemory({ storage, llm: config.llm, autoTags: false });
+    await memory.adoptProjects(project.previousIds, project.id);
+    const { hits } = await memory.recall({
+      namespaces: defaultRecallNamespaces(project.id),
+      limit: HOOK_LIMIT,
+      maxChars: HOOK_MAX_CHARS
+    });
+    if (hits.length === 0) return "";
+    return [
+      `MemStack project memory (project ${project.id}), most important first. Follow these unless the user says otherwise; use memory_retrieve for more and memory_store to save new facts.`,
+      ...hits.map(({ memory: m }) => formatLine(m))
+    ].join("\n");
+  } finally {
+    await storage.close();
+  }
+}
+async function runSessionStartHook() {
+  try {
+    const input = parseInput(await readStdin());
+    const context = await sessionStartContext(input);
+    if (context) process.stdout.write(`${context}
+`);
+  } catch (error) {
+    process.stderr.write(`memstack hook: ${error instanceof Error ? error.message : String(error)}
+`);
+  }
+}
+function formatLine(m) {
+  const scope = m.actorId === GLOBAL_NAMESPACE ? "global" : "project";
+  return `- [${m.id}] ${m.content} (${m.memoryType}, ${scope})`;
+}
+function parseInput(raw) {
+  if (!raw.trim()) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function readStdin(timeoutMs = 2e3) {
+  if (process.stdin.isTTY) return Promise.resolve("");
+  return new Promise((resolve2) => {
+    let data = "";
+    const timer = setTimeout(() => resolve2(data), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => data += chunk);
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve2(data);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve2(data);
+    });
+  });
+}
 async function main() {
+  if (process.argv[2] === "hook") {
+    if (process.argv[3] !== "session-start") {
+      console.error(`Unknown hook "${process.argv[3] ?? ""}". Supported: session-start`);
+      return;
+    }
+    await runSessionStartHook();
+    process.exit(0);
+  }
   const { values } = parseArgs({
     options: {
       http: { type: "boolean", default: false },
-      port: { type: "string", default: "3939" }
+      port: { type: "string", default: "3939" },
+      profile: { type: "string", default: "default" },
+      harness: { type: "string" }
     }
   });
-  const { config, defaultActorId } = await loadConfig();
+  if (values.profile === "harness") {
+    if (values.http) throw new Error("--profile harness supports stdio only: the project comes from the harness's working directory");
+    await runHarness(values.harness);
+    return;
+  }
+  if (values.profile !== "default") throw new Error(`Unknown --profile "${values.profile}". Use "default" or "harness".`);
+  const { config, defaultActorId } = await loadConfig2();
   if (values.http) {
     await runHttp({ config, defaultActorId, port: Number(values.port) });
     return;
   }
-  const server = createServer({ config, defaultActorId });
+  const ms = new MemStack(config);
+  const server = createServer({ config, defaultActorId, ms });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  exitWhenStdinCloses(transport, () => ms.close());
+}
+async function runHarness(harness) {
+  const cwd = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const project = resolveProject(cwd);
+  const { config } = await loadHarnessConfig();
+  const storage = config.storage ?? new InMemoryStorageAdapter();
+  if (storage instanceof InMemoryStorageAdapter) {
+    console.error("memstack-mcp: storage is in-memory, so memories are lost when this session ends. Run `memstack init` to choose a store.");
+  }
+  const memory = new HarnessMemory({
+    storage,
+    llm: config.llm,
+    onError: (error, context) => console.error(`memstack-mcp: ${context}: ${error.message}`)
+  });
+  const adopted = await memory.adoptProjects(project.previousIds, project.id);
+  if (adopted > 0) console.error(`memstack-mcp: moved ${adopted} memories from this project's previous ID to ${project.id}.`);
+  const server = createHarnessServer({ memory, projectId: project.id, harness, cwd: project.root });
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  exitWhenStdinCloses(transport, () => storage.close());
+}
+function exitWhenStdinCloses(transport, close) {
+  let pending = 0;
+  let ended = false;
+  const finish = () => {
+    if (ended && pending === 0) void close().finally(() => process.exit(0));
+  };
+  const onmessage = transport.onmessage;
+  transport.onmessage = (message) => {
+    if ("method" in message && "id" in message) pending++;
+    onmessage?.(message);
+  };
+  const send = transport.send.bind(transport);
+  transport.send = async (message) => {
+    await send(message);
+    if (!("method" in message) && "id" in message) {
+      pending--;
+      finish();
+    }
+  };
+  process.stdin.once("end", () => {
+    ended = true;
+    finish();
+  });
 }
 async function runHttp({ config, defaultActorId, port }) {
   const ms = new MemStack(config);