sessionmem 1.0.6 → 1.1.1

package/dist/cli/context.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "url";
 import { mkdirSync } from "fs";
 import { openDb } from "../core/storage/db.js";
 import { createMemoryCoreService } from "../core/api/memoryCoreService.js";
+import { deriveProjectId } from "./projectId.js";
 /**
  * Resolve the local OS username once per invocation and sanitize it to a
  * filename-safe token so it can be embedded in exports/filenames without path
@@ -28,29 +29,27 @@ function safeUserInfoName() {
         return "";
     }
 }
-function deriveProjectId() {
-    // Env override is a test-injection seam (mirrors Plan 01's override pattern):
-    // it lets a spawned binary target a deterministic projectId without touching
-    // the real ~/.sessionmem. No privilege boundary is crossed — the CLI runs as
-    // the invoking user and the env var is operator-controlled.
-    const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
-    if (envProjectId && envProjectId.trim() !== "")
-        return envProjectId;
-    const cwd = process.cwd();
-    const parts = cwd.replace(/\\/g, "/").split("/");
-    const raw = parts[parts.length - 1] || "default";
-    // Sanitize to a filename-safe token (mirrors localUsername) so it can be
-    // embedded in shared-path join()s without path traversal.
-    const sanitized = raw.replace(/[^A-Za-z0-9._-]/g, "_");
-    return sanitized === "" || sanitized === "." || sanitized === ".."
-        ? "default"
-        : sanitized;
+/**
+ * Expand a leading `~/` (or bare `~`) to the user's home directory. Shells do
+ * this before a value reaches the process, but env vars set programmatically or
+ * in config files are passed through verbatim, so we expand here too.
+ */
+export function expandTilde(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+        // `homedir()` is the fixed base; `p` is SESSIONMEM_DB_PATH, a local CLI
+        // config the operator sets for their own filesystem — not external user input.
+        return join(homedir(), p.slice(2));
+    }
+    return p;
 }
 function defaultDbPath(dir) {
     // Env override seam (see deriveProjectId). Defaults to ~/.sessionmem/memories.db.
     const envDbPath = process.env.SESSIONMEM_DB_PATH;
     if (envDbPath && envDbPath.trim() !== "")
-        return envDbPath;
+        return expandTilde(envDbPath);
     // `dir` is the fixed ~/.sessionmem dir computed above, not user input.
     // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
     return join(dir, "memories.db");

package/dist/cli/index.js

@@ -2,6 +2,8 @@
 import { Command } from "commander";
 import { createRequire } from "node:module";
 import { runMcpServer } from "./commands/run.js";
+import { sessionStartCommand } from "./commands/sessionStart.js";
+import { sessionEndCommand } from "./commands/sessionEnd.js";
 import { installCommand } from "./commands/install.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { pingCommand } from "./commands/ping.js";
@@ -30,19 +32,29 @@ program
     .command("run")
     .description("Start the sessionmem MCP server")
     .action(runMcpServer);
+program
+    .command("session-start")
+    .description("Print prior memory context for the current project as Claude Code SessionStart hook output (invoked automatically by the hook installed during `sessionmem install`)")
+    .action(() => sessionStartCommand());
+program
+    .command("session-end")
+    .description("Run the session-end pipeline (auto-summarize ingested session events + light retention prune) for the current project (invoked automatically by the SessionEnd hook installed during `sessionmem install`)")
+    .action(() => sessionEndCommand());
 program
     .command("install")
     .description("Install sessionmem into the current MCP host")
-    .action(installCommand);
+    .option("--adapter <name>", "Force a host adapter instead of auto-detecting (claude-code, cursor, windsurf, cline, codex, antigravity, qcoder, generic)")
+    .action((options) => installCommand(options));
 program
     .command("uninstall")
     .description("Remove sessionmem from the current MCP host")
     .option("--purge", "Also delete the local memories database")
-    .action(uninstallCommand);
+    .option("--adapter <name>", "Force a host adapter instead of auto-detecting (claude-code, cursor, windsurf, cline, codex, antigravity, qcoder, generic)")
+    .action((options) => uninstallCommand(options));
 program
     .command("ping")
-    .description("Check sessionmem server connectivity")
-    .action(pingCommand);
+    .description("Check sessionmem version and local database reachability")
+    .action(() => pingCommand());
 // NOTE: commander always appends its own Command instance as the final
 // argument to .action() callbacks. The search/list/show/forget/export/import/
 // stats commands all declare a trailing `ctx?: CliContext` parameter (the

package/dist/cli/projectId.js

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+/**
+ * Sanitize a raw token to the filename-safe character set used across
+ * sessionmem (mirrors localUsername). Any character outside [A-Za-z0-9._-]
+ * becomes "_".
+ */
+function sanitizeToken(raw) {
+    return raw.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+/**
+ * Derive a stable, collision-resistant project id from an absolute working
+ * directory.
+ *
+ * Format: `<basename>-<hash8>` where `hash8` is the first 8 hex chars of the
+ * SHA-256 of the FULL absolute path. The human-readable basename keeps the id
+ * debuggable; the path hash guarantees two different projects that happen to
+ * share a basename (e.g. `~/a/api` and `~/b/api`) get distinct memory buckets
+ * instead of silently colliding.
+ *
+ * The basename-only scheme this replaces partitioned memory purely by the last
+ * path segment, so same-named projects in different directories shared one
+ * bucket with zero warning.
+ */
+export function projectIdFromCwd(cwd) {
+    // On Windows the same directory can surface with either a lowercase or
+    // uppercase drive letter (e.g. `c:\proj` vs `C:\proj`). Lowercase the drive
+    // letter before normalizing slashes so both spellings hash to the same id.
+    let normalized = process.platform === "win32"
+        ? cwd.replace(/^[A-Za-z]:[\\/]/, (m) => m.toLowerCase()).replace(/\\/g, "/")
+        : cwd.replace(/\\/g, "/");
+    // Normalize UNC path host and share (//server/share/...) case-insensitively
+    // so `\\Server\Share\proj` and `\\server\share\proj` hash to the same id.
+    normalized = normalized.replace(/^(\/\/[^/]+\/[^/]+)/, (m) => m.toLowerCase());
+    const parts = normalized.split("/");
+    const rawBase = parts[parts.length - 1] || "default";
+    const sanitizedBase = sanitizeToken(rawBase);
+    const base = sanitizedBase === "" || sanitizedBase === "." || sanitizedBase === ".."
+        ? "default"
+        : sanitizedBase;
+    // Hash the normalized absolute path so the id is stable across runs from the
+    // same directory but unique per directory.
+    const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 8);
+    return `${base}-${hash}`;
+}
+/**
+ * Resolve the effective project id: the `SESSIONMEM_PROJECT_ID` env override
+ * (operator-controlled test/migration seam; also lets a user pin a legacy
+ * basename-only id) wins, otherwise derive from `process.cwd()`.
+ */
+export function deriveProjectId() {
+    const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
+    if (envProjectId && envProjectId.trim() !== "") {
+        // Sanitize the operator-supplied id to prevent path traversal: the id is
+        // later joined into filesystem paths (e.g. sync.ts `join(sharedPath,
+        // projectId)`), so strip path separators and `..` traversal sequences and
+        // bound the length. Fall through to the derived id only if nothing usable
+        // remains.
+        const sanitized = envProjectId
+            .replace(/[/\\]/g, "")
+            .replace(/\.\./g, "")
+            .slice(0, 128);
+        // Guard against empty or "." (current-dir) values, which would be unsafe or
+        // meaningless when joined into filesystem paths; fall through to derived id.
+        if (sanitized && sanitized !== ".") {
+            return sanitized;
+        }
+    }
+    return projectIdFromCwd(process.cwd());
+}

package/dist/core/api/contracts.js

@@ -1,8 +1,52 @@
 import { z } from "zod";
+/**
+ * Canonical memory-kind taxonomy. This is the single source of truth — the
+ * storeMemory tool description, CLAUDE.md guidance block, and
+ * formatStartupInjection's KIND_ORDER all use exactly this set. The legacy
+ * `architecture` kind is mapped onto `decision` (it was never recognized by the
+ * formatter and scored at the bottom).
+ */
+export const MEMORY_KINDS = [
+    "decision",
+    "fact",
+    "warning",
+    "preference",
+    "summary",
+];
+/**
+ * Validate `kind` against {@link MEMORY_KINDS}, transparently mapping the legacy
+ * `architecture` value to `decision` so older callers/exports keep working.
+ */
+const memoryKindSchema = z.preprocess((value) => (value === "architecture" ? "decision" : value), z.enum(MEMORY_KINDS));
+/** Upper bound on stored memory content length (characters). */
+export const MAX_CONTENT_LENGTH = 10000;
+/** Maximum number of items accepted in a single batchStoreMemory call. */
+export const MAX_BATCH_SIZE = 100;
+/** Maximum number of records accepted in a single import/pull call. */
+export const MAX_IMPORT_SIZE = 1000;
+/**
+ * Maximum number of session events accepted in a single ingestSessionEvents
+ * call. Each event's payloadJson is capped at 50000 chars, so this bounds a
+ * single ingest request at ~25MB worst-case (500 × 50KB) rather than leaving
+ * the array unbounded — an agent looping ingestion could otherwise build a
+ * multi-MB JSON-RPC message that OOMs or times out the MCP stdio transport.
+ * Callers that need to ingest more than this should chunk across calls (the
+ * (project_id, session_id, event_index) UNIQUE index makes re-ingestion a
+ * no-op, so chunks never double-count).
+ */
+export const MAX_INGEST_EVENTS = 500;
+/**
+ * Default cap on the number of memories returned by listMemories when the caller
+ * omits an explicit `limit`. Bounds the MCP stdio response size for large
+ * projects; `total` still reports the full row count. Exported so the service
+ * layer and tests share a single source of truth — a change here is caught by
+ * the list-memories limit test rather than silently drifting.
+ */
+export const LIST_MEMORIES_DEFAULT_LIMIT = 200;
 export const memorySchema = z.object({
     id: z.string().min(1),
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
+    sessionId: z.string().min(1).max(200),
     sourceAdapter: z.string().min(1),
     kind: z.string().min(1),
     content: z.string().min(1),
@@ -18,23 +62,40 @@ export const memorySchema = z.object({
     updatedAt: z.string().min(1),
 });
 export const ingestSessionEventSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().min(1).max(200),
     eventIndex: z.number().int().nonnegative(),
-    eventType: z.string().min(1),
-    payloadJson: z.string().min(1),
+    eventType: z.string().min(1).max(100),
+    payloadJson: z
+        .string()
+        .min(1)
+        .max(50000)
+        .refine((v) => {
+        try {
+            JSON.parse(v);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "must be valid JSON" }),
     createdAt: z.string().min(1).optional(),
 });
 export const ingestSessionEventsRequestSchema = z.object({
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
-    events: z.array(ingestSessionEventSchema).min(1),
+    sessionId: z.string().min(1).max(200),
+    events: z.array(ingestSessionEventSchema).min(1).max(MAX_INGEST_EVENTS),
 });
 export const summarizeSessionToMemoryRequestSchema = z.object({
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
-    sourceAdapter: z.string().min(1),
-    summary: z.string().min(1),
+    sessionId: z.string().min(1).max(200),
+    sourceAdapter: z
+        .string()
+        .min(1)
+        .max(100)
+        // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+        .regex(/^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "sourceAdapter must not contain control characters"),
+    summary: z.string().min(1).max(50000),
     importance: z.number().int().min(1).max(10),
 });
 export const factModeSchema = z.enum([
@@ -45,7 +106,7 @@ export const factModeSchema = z.enum([
 export const handleSessionEndConfigSchema = z.object({
     autoSummarize: z.boolean().default(true),
     minimumEventThreshold: z.number().int().min(1).max(100).default(3),
-    summaryTokenCap: z.number().int().min(1).default(300),
+    summaryTokenCap: z.number().int().min(1).max(200000).default(300),
     // No `.default()`: omission must be distinguishable from an explicit value so
     // the service layer can fall back to the policy-config redactionEnabled
     // setting (override > config.json > default precedence).
@@ -56,18 +117,28 @@ export const handleSessionEndConfigSchema = z.object({
 });
 export const handleSessionEndRequestSchema = z.object({
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
-    sourceAdapter: z.string().min(1),
-    memoryId: z.string().min(1).optional(),
+    sessionId: z.string().min(1).max(200),
+    sourceAdapter: z
+        .string()
+        .min(1)
+        .max(100)
+        // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+        .regex(/^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "sourceAdapter must not contain control characters"),
+    memoryId: z.string().min(1).max(200).optional(),
     config: handleSessionEndConfigSchema.default(() => handleSessionEndConfigSchema.parse({})),
 });
 export const storeMemoryRequestSchema = z.object({
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
-    sourceAdapter: z.string().min(1),
-    kind: z.string().min(1),
-    content: z.string().min(1),
+    sessionId: z.string().min(1).max(200),
+    sourceAdapter: z
+        .string()
+        .min(1)
+        .max(100)
+        // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+        .regex(/^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "sourceAdapter must not contain control characters"),
+    kind: memoryKindSchema,
+    content: z.string().min(1).max(MAX_CONTENT_LENGTH),
     importance: z.number().int().min(1).max(10),
     // No `.default()`: omission must be distinguishable from an explicit value so
     // the service layer can fall back to the policy-config redactionEnabled
@@ -76,32 +147,43 @@ export const storeMemoryRequestSchema = z.object({
 });
 export const retrieveMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
-    query: z.string().min(1),
+    query: z.string().min(1).max(1000),
     limit: z.number().int().min(1).max(100).default(20),
     mode: z.enum(["auto", "on-demand"]).default("auto"),
     depth: z.enum(["default", "deep"]).default("default"),
 });
 export const listMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
+    // Maximum number of memories to return. Bounds the response size so a large
+    // project (10k+ memories) cannot produce a multi-MB payload that OOMs or
+    // times out the MCP stdio client. `total` always reports the full count, so a
+    // returned array shorter than `total` signals truncation. Defaults to 200 in
+    // the service layer when omitted.
+    limit: z.number().int().positive().max(1000).optional(),
 });
 export const getMemoryRequestSchema = z.object({
     projectId: z.string().min(1),
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
 });
 export const forgetMemoryRequestSchema = z.object({
     projectId: z.string().min(1),
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
 });
 export const exportMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
 });
 export const importMemoryRecordSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().min(1).max(200),
     projectId: z.string().min(1),
-    sessionId: z.string().min(1),
-    sourceAdapter: z.string().min(1),
-    kind: z.string().min(1),
-    content: z.string().min(1),
+    sessionId: z.string().min(1).max(200),
+    sourceAdapter: z
+        .string()
+        .min(1)
+        .max(100)
+        // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+        .regex(/^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "sourceAdapter must not contain control characters"),
+    kind: memoryKindSchema,
+    content: z.string().min(1).max(MAX_CONTENT_LENGTH),
     importance: z.number().int().min(1).max(10),
     // OPTIONAL for backward-compat with exports predating team provenance (A3):
     // older exports lack author/originProjectId, so the service stamps the local
@@ -109,10 +191,32 @@ export const importMemoryRecordSchema = z.object({
     // `originProjectId: null` (and `author: ""`) for locally-authored rows — a
     // team sync round-trips those exported snapshots verbatim, so the schema must
     // accept the null the DTO carries rather than skip-and-warn every local row.
-    author: z.string().nullable().optional(),
-    originProjectId: z.string().nullable().optional(),
-    createdAt: z.string().min(1).optional(),
-    updatedAt: z.string().min(1).optional(),
+    // `author` is rendered directly into the per-session startup injection
+    // context, so it is bounded and stripped of control characters (newlines/CR/
+    // C0/DEL) that could break out of the injection block or smuggle in
+    // prompt-injection payloads.
+    author: z
+        .string()
+        .max(200)
+        .regex(
+    // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+    /^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "author must not contain control characters")
+        .nullable()
+        .optional(),
+    // Bounded like the other id-bearing fields (memoryId/author max 200): an
+    // import file or team-pull payload is externally-supplied, so an unbounded
+    // originProjectId would let a single record carry a multi-MB string. It is
+    // stored only (never rendered into the startup injection), so unlike `author`
+    // it needs no control-character stripping — just a length cap.
+    originProjectId: z.string().max(200).nullable().optional(),
+    createdAt: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/, "must be UTC ISO timestamp")
+        .optional(),
+    updatedAt: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/, "must be UTC ISO timestamp")
+        .optional(),
 });
 export const importMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
@@ -120,7 +224,7 @@ export const importMemoriesRequestSchema = z.object({
     // the service layer can fall back to the policy-config redactionEnabled
     // setting (override > config.json > default precedence).
     redactionEnabled: z.boolean().optional(),
-    memories: z.array(importMemoryRecordSchema),
+    memories: z.array(importMemoryRecordSchema).max(MAX_IMPORT_SIZE),
 });
 // Team pull. Mirrors importMemoriesRequestSchema — the pull
 // path reuses importMemoryRecordSchema verbatim (carrying author/originProjectId
@@ -130,7 +234,7 @@ export const importMemoriesRequestSchema = z.object({
 export const pullMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
     redactionEnabled: z.boolean().optional(),
-    memories: z.array(importMemoryRecordSchema),
+    memories: z.array(importMemoryRecordSchema).max(MAX_IMPORT_SIZE),
 });
 export const statsRequestSchema = z.object({
     projectId: z.string().min(1),
@@ -229,7 +333,7 @@ export const ingestSessionEventsResponseSchema = z.object({
 });
 export const summarizeSessionToMemoryResponseSchema = z.object({
     ok: z.literal(true),
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
 });
 export const handleSessionEndResponseSchema = z.object({
     ok: z.literal(true),
@@ -238,7 +342,7 @@ export const handleSessionEndResponseSchema = z.object({
     warningCodes: z.array(z.string()),
     warningMessages: z.array(z.string()),
     failureRecordId: z.string().min(1).optional(),
-    memoryId: z.string().min(1).optional(),
+    memoryId: z.string().min(1).max(200).optional(),
 });
 export const importMemoriesResponseSchema = z.object({
     ok: z.literal(true),
@@ -247,6 +351,10 @@ export const importMemoriesResponseSchema = z.object({
     // different project's memory. These are never upserted, preventing
     // cross-project overwrite/reassignment via ON CONFLICT(id).
     skippedCrossProject: z.number().int().nonnegative().default(0),
+    // Count of records skipped because their `id` already exists in THIS project.
+    // Imports never overwrite an existing same-project memory; only brand-new ids
+    // are upserted.
+    skippedExisting: z.number().int().nonnegative().default(0),
     warningCodes: z.array(z.string()),
 });
 // Team pull response: distinguishes brand-new inserts from updates so the
@@ -260,20 +368,25 @@ export const pullMemoriesResponseSchema = z.object({
     warningCodes: z.array(z.string()),
 });
 export const batchStoreMemoryItemSchema = z.object({
-    memoryId: z.string().min(1),
-    sessionId: z.string().min(1),
-    sourceAdapter: z.string().min(1),
-    kind: z.string().min(1),
-    content: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
+    sessionId: z.string().min(1).max(200),
+    sourceAdapter: z
+        .string()
+        .min(1)
+        .max(100)
+        // eslint-disable-next-line no-control-regex -- intentionally rejects control chars
+        .regex(/^[^\n\r\x00-\x08\x0e-\x1f\x7f]*$/, "sourceAdapter must not contain control characters"),
+    kind: memoryKindSchema,
+    content: z.string().min(1).max(MAX_CONTENT_LENGTH),
     importance: z.number().int().min(1).max(10),
     redactionEnabled: z.boolean().optional(),
 });
 export const batchStoreMemoryRequestSchema = z.object({
     projectId: z.string().min(1),
-    memories: z.array(batchStoreMemoryItemSchema).min(1),
+    memories: z.array(batchStoreMemoryItemSchema).min(1).max(MAX_BATCH_SIZE),
 });
 export const batchStoreMemoryResultSchema = z.object({
-    memoryId: z.string().min(1),
+    memoryId: z.string().min(1).max(200),
     ok: z.boolean(),
     memory: memorySchema.optional(),
     warningCodes: z.array(z.string()).optional(),

package/dist/core/api/errors.js

@@ -16,14 +16,11 @@ export function toErrorEnvelope(error) {
             details: error.details,
         };
     }
-    if (error instanceof Error) {
-        return {
-            code: "INTERNAL",
-            message: error.message,
-        };
-    }
+    // Don't surface internal .message (may contain fs paths) to MCP client.
+    // Log the real message to stderr; return a static string to the caller.
+    process.stderr.write(`[sessionmem] internal error: ${error instanceof Error ? error.message : String(error)}\n`);
     return {
         code: "INTERNAL",
-        message: "Unexpected error",
+        message: "Internal error",
     };
 }