sessionmem 1.0.6 → 1.1.1

package/dist/adapters/capabilities/fallbackTools.js

@@ -9,7 +9,7 @@ export class FallbackToolRegistrar {
                     "WHEN TO CALL: At session start and mid-session when you need to retrieve context and the host does not support MCP resources. Do not call if the host supports MCP resources — use the sessionmem:// resource URI or retrieveMemories tool instead.\n\n" +
                     "Parameter `query`: natural-language description of what context you need to recall (e.g. 'API design decisions', 'database schema choices').",
                 inputShape: {
-                    query: z.string().describe("Natural-language description of what context you need to recall."),
+                    query: z.string().min(1).max(1000).describe("Natural-language description of what context you need to recall."),
                 },
                 execute: async (args) => {
                     const result = await context.service.call("retrieveMemories", {
@@ -30,7 +30,7 @@ export class FallbackToolRegistrar {
                 name: "startup_inject_memories",
                 description: "Fallback startup-injection for hosts that do not support MCP prompts. Call this once at the very start of a session instead of relying on the automatic sessionmem startup prompt when the host lacks prompt support. Injects the top relevant memories for the current project into the working context. No parameters required.\n\n" +
                     "WHEN TO CALL: Once per session start, before any user task work begins, when the host does not surface MCP prompts automatically. Do not call if the host already surfaces the sessionmem startup prompt — calling both duplicates injected context.\n\n" +
-                    "Read-only; no side effects.",
+                    "Note: access counts are incremented on retrieval.",
                 inputShape: {},
                 execute: async () => {
                     const result = await context.service.call("retrieveMemories", {

package/dist/adapters/claudeMdInjector.js

@@ -5,7 +5,19 @@ export const SESSIONMEM_BLOCK_END = "<!-- sessionmem:end -->";
 const BLOCK_CONTENT = `
 ## sessionmem — Persistent Memory
 
-sessionmem is an MCP memory layer that persists context across sessions. Use its tools to store important decisions, facts, and context so they're available in future sessions without the user re-explaining.
+sessionmem is an MCP memory layer that persists context across sessions. It is installed and active via the \`sessionmem\` MCP server. Use its tools to recall prior context and to store important decisions, facts, and context so they're available in future sessions without the user re-explaining. The user should never have to ask you to do this — it is part of how you work in this project.
+
+### Startup
+On Claude Code, prior context is injected automatically at session start by the
+sessionmem \`SessionStart\` hook — you do not need to fetch it yourself. Do NOT
+call \`startup_inject_memories\` on Claude Code: the hook already provides the
+injection, so calling the tool would duplicate the context (it is not even
+registered on Claude Code for this reason). If you do NOT see a "Relevant prior
+context" block at the start of the session AND the \`startup_inject_memories\`
+tool is available (e.g. the hook is not installed, or you are on a host without
+hook support), call it once before any task work, or call \`retrieveMemories\`
+with the current task as the query. Never inject twice if context was already
+provided.
 
 ### When to store memories (storeMemory)
 - User makes an architectural or design decision
@@ -14,29 +26,35 @@ sessionmem is an MCP memory layer that persists context across sessions. Use its
 - User states a preference about how they want things done
 - A warning or pitfall is discovered that future sessions should know about
 
-### When to retrieve memories (retrieveMemories)
-- At the start of a session or task to check for relevant prior context
+### When to retrieve memories mid-session (retrieveMemories)
 - Before making architectural decisions (check if prior decisions exist)
 - When the user references something from a previous session
 - When working in an area of the codebase that may have stored warnings or decisions
 
+### At session end (RECOMMENDED — do this without being asked)
+Before the session ends, persist what was accomplished so the next session starts
+informed. Store a concise \`summary\` memory (importance 7) of the key outcomes, plus
+any new decisions, facts, or warnings. Use \`batchStoreMemory\` to write several at
+once. This is what makes context survive across sessions and saves tokens later.
+
 ### Memory kinds
 - \`decision\` — architectural or design choices (importance: 7-9)
 - \`fact\` — project constraints, conventions, patterns (importance: 5-7)
 - \`warning\` — pitfalls, gotchas, things that broke before (importance: 8-10)
 - \`preference\` — how the user likes things done (importance: 5-7)
-- \`summary\` — session summaries (auto-generated, importance: 3-5)
+- \`summary\` — session summaries (importance: 7)
 
 ### Other tools
 - \`listMemories\` — browse all stored memories for this project
 - \`getMemory\` — fetch a specific memory by ID
 - \`forgetMemory\` — delete an outdated or incorrect memory
+- \`batchStoreMemory\` — store multiple memories in one call (use at session end)
 - \`stats\` — check memory count and health
 
 ### Guidelines
 - Don't store trivial or easily re-derivable information
 - Don't retrieve memories every single turn — retrieve at task boundaries
-- Keep memory content concise (1-3 sentences)
+- Keep memory content concise (1-3 sentences) and self-contained
 - Use appropriate importance scores (see kinds above)
 `;
 export function generateClaudeMdBlock() {
@@ -73,6 +91,32 @@ export function injectClaudeMdBlock(filePath) {
         return false;
     }
 }
+/**
+ * Inject the sessionmem guidance block into an arbitrary host-guidance file
+ * (CLAUDE.md, AGENTS.md, Windsurf global_rules.md, a Cursor `.mdc` rule, …).
+ *
+ * The block is the same markdown for every host. The only host-specific concern
+ * is Cursor's `.mdc` rule format: a newly-created rule file needs an
+ * `alwaysApply: true` frontmatter header for Cursor to apply it on every
+ * request, so we seed that header before appending the block. Existing files
+ * (and all non-`.mdc` targets) are handled exactly like CLAUDE.md.
+ */
+export function injectGuidanceBlock(filePath) {
+    try {
+        if (filePath.endsWith(".mdc") && !existsSync(filePath)) {
+            const dir = dirname(filePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(filePath, "---\ndescription: sessionmem persistent memory guidance\nalwaysApply: true\n---\n", "utf8");
+        }
+    }
+    catch {
+        // Best-effort frontmatter seeding; fall through to block injection which
+        // creates the file itself if the seeding failed.
+    }
+    return injectClaudeMdBlock(filePath);
+}
 export function removeClaudeMdBlock(filePath) {
     try {
         if (!existsSync(filePath)) {

package/dist/adapters/factory.js

@@ -7,28 +7,58 @@ import { ClineAdapter } from "./ide/cline.js";
 import { GenericMCPAdapter } from "./generic.js";
 import { CodexAdapter } from "./global/codex.js";
 import { QCoderAdapter } from "./global/qcoder.js";
+/**
+ * Canonical adapter names accepted by `--adapter <name>` / SESSIONMEM_ADAPTER.
+ * Kept in sync with {@link AdapterFactory.forName}; surfaced to the CLI for the
+ * install command's choices list.
+ */
+export const ADAPTER_NAMES = [
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "cline",
+    "codex",
+    "antigravity",
+    "qcoder",
+    "generic",
+];
 export class AdapterFactory {
     /**
      * Detect the current host environment and return the appropriate adapter.
+     *
+     * Detection keys are the REAL environment variables each host sets, verified
+     * against live shells:
+     *  - Claude Code sets `CLAUDECODE=1`, `CLAUDE_CODE_ENTRYPOINT=cli`, and
+     *    `CLAUDE_CODE_SESSION_ID=...` (note the `_ID` suffix). `TERM_PROGRAM` is
+     *    the HOST terminal (e.g. `vscode`), never `"claude-code"`. The previous
+     *    `CLAUDE_CODE_SESSION` / `TERM_PROGRAM === "claude-code"` check never
+     *    matched, so the SessionStart-hook install path was never selected.
+     *  - Antigravity sets `ANTIGRAVITY_APP_DATA_DIR` / `ANTIGRAVITY_SESSION_ID`
+     *    (and leaks `ANTIGRAVITY_CLI_ALIAS`); checked first so its own CLI wins in
+     *    its own shell.
      */
     static detectAdapter() {
         const env = process.env;
         if (env.ANTIGRAVITY_APP_DATA_DIR || env.ANTIGRAVITY_SESSION_ID) {
             return new AntigravityAdapter();
         }
-        if (env.CLAUDE_CODE_SESSION || env.TERM_PROGRAM === "claude-code") {
+        if (env.CLAUDECODE === "1" ||
+            env.CLAUDE_CODE_ENTRYPOINT !== undefined ||
+            env.CLAUDE_CODE_SESSION_ID !== undefined) {
             return new ClaudeCodeAdapter();
         }
-        if (env.TERM_PROGRAM === "Cursor" || env.CURSOR_APP_VERSION) {
+        if (env.CURSOR_AGENT !== undefined ||
+            env.CURSOR_CLI !== undefined ||
+            env.CURSOR_TRACE_ID !== undefined) {
             return new CursorAdapter();
         }
-        if (env.TERM_PROGRAM === "Windsurf") {
-            return new WindsurfAdapter();
-        }
-        if (env.CLINE_SESSION_ID) {
-            return new ClineAdapter();
-        }
-        if (env.CODEX_SESSION_ID) {
+        // Windsurf is a VS Code fork with no unique env var; --adapter windsurf
+        // required. No reliable auto-detection branch.
+        // Cline is a VS Code extension; auto-detection is impossible. Use
+        // --adapter cline.
+        // Codex sets CODEX_HOME (and may expose OPENAI_CODEX). CODEX_SESSION_ID was
+        // unverified and never matched.
+        if (env.CODEX_HOME !== undefined || env.OPENAI_CODEX !== undefined) {
             return new CodexAdapter();
         }
         if (env.QCODER_SESSION) {
@@ -37,4 +67,33 @@ export class AdapterFactory {
         // Fallback to generic MCP if no specific host is detected
         return new GenericMCPAdapter();
     }
+    /**
+     * Resolve an adapter by its canonical name. Powers the `--adapter <name>`
+     * install flag and the `SESSIONMEM_ADAPTER` override so a user can force a
+     * host explicitly when auto-detection cannot (e.g. installing from a plain
+     * terminal that is not inside any host). Throws on an unknown name so the CLI
+     * can surface a clear error rather than silently falling back to generic.
+     */
+    static forName(name) {
+        switch (name) {
+            case "claude-code":
+                return new ClaudeCodeAdapter();
+            case "cursor":
+                return new CursorAdapter();
+            case "windsurf":
+                return new WindsurfAdapter();
+            case "cline":
+                return new ClineAdapter();
+            case "codex":
+                return new CodexAdapter();
+            case "antigravity":
+                return new AntigravityAdapter();
+            case "qcoder":
+                return new QCoderAdapter();
+            case "generic":
+                return new GenericMCPAdapter();
+            default:
+                throw new Error(`Unknown adapter "${name}". Valid adapters: ${ADAPTER_NAMES.join(", ")}.`);
+        }
+    }
 }

package/dist/adapters/generic.js

@@ -1,10 +1,13 @@
+import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { batchStoreMemoryRequestSchema, forgetMemoryRequestSchema, getMemoryRequestSchema, listMemoriesRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, statsRequestSchema, storeMemoryRequestSchema, } from "../core/api/contracts.js";
+import { batchStoreMemoryRequestSchema, forgetMemoryRequestSchema, getMemoryRequestSchema, handleSessionEndRequestSchema, ingestSessionEventsRequestSchema, listMemoriesRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, statsRequestSchema, storeMemoryRequestSchema, summarizeSessionToMemoryRequestSchema, } from "../core/api/contracts.js";
 import { join } from "path";
 import { createCliContext } from "../cli/context.js";
 import { IDEInstaller } from "./ide/installer.js";
 import { FallbackToolRegistrar } from "./capabilities/fallbackTools.js";
+import { countStaleEmbeddings } from "../core/storage/memoryRepo.js";
+import { EMBEDDING_VERSION } from "../core/embed/embeddingVersion.js";
 /**
  * Diagnostic logging sink for the stdio server. CRITICAL: the MCP protocol
  * frames are written to STDOUT by StdioServerTransport, so anything this server
@@ -14,6 +17,11 @@ import { FallbackToolRegistrar } from "./capabilities/fallbackTools.js";
 function logDiagnostic(message) {
     process.stderr.write(`[sessionmem] ${message}\n`);
 }
+// Read the package version dynamically so the MCP server's advertised version
+// tracks package.json on every release. A hardcoded literal silently drifts on
+// `npm version` bumps (postversion does not rewrite source), so mirror ping.ts.
+const require = createRequire(import.meta.url);
+const SERVER_VERSION = require("../../package.json").version;
 /**
  * Strip `projectId` from a request schema's shape so the tool input only asks
  * the client for the fields it should provide; the server injects projectId.
@@ -22,14 +30,39 @@ function shapeWithoutProjectId(shape) {
     const { projectId: _projectId, ...rest } = shape;
     return rest;
 }
+/**
+ * Resolve a default sessionId for tools that require one but were invoked
+ * without it. Agents pass arbitrary/inconsistent sessionIds (or none), which
+ * breaks the per-session soft-limit counter and handleSessionEnd correlation.
+ * Preferring CLAUDE_CODE_SESSION_ID ties an agent's storeMemory/ingest calls to
+ * the same Claude Code session the SessionStart hook ran under. Callers can
+ * still override by supplying an explicit sessionId.
+ */
+// Evaluated once per process lifecycle so every storeMemory/ingest call in one
+// MCP server process shares the same fallback session when no env session id is
+// available. Computing `session-${Date.now()}` per call would hand each call a
+// different fake session, breaking the per-session soft-limit counter and
+// handleSessionEnd correlation.
+const PROCESS_SESSION_FALLBACK = `session-${Date.now()}`;
+function resolveDefaultSessionId() {
+    return (process.env.CLAUDE_CODE_SESSION_ID ??
+        process.env.SESSION_ID ??
+        PROCESS_SESSION_FALLBACK);
+}
+function isMissing(value) {
+    return value === undefined || value === null || value === "";
+}
 const TOOL_DEFINITIONS = [
     {
         method: "retrieveMemories",
         description: "Semantically search stored memories and return the top matches ranked by a weighted combination of relevance, recency, and importance. Read-only; no side effects.\n\n" +
             "WHEN TO CALL: (1) At the start of every session — pass the current task or file as the query to pre-load relevant context. (2) Mid-session whenever a new topic, file, or decision area arises that may have prior context. Do NOT call on every user turn.\n\n" +
             "WHEN NOT TO CALL: If you already retrieved memories for this topic this session. Use getMemory if you have a specific memoryId. Use listMemories only to audit the full store, not for context loading.\n\n" +
-            "Returns up to `limit` results (default 20). `mode='auto'` is the standard startup path; `mode='on-demand'` signals an explicit mid-session lookup. `depth='deep'` runs a broader semantic sweep at higher latency — use when the topic is unfamiliar. Phrase `query` as what you need to recall, not what you are about to do.",
-        annotations: { readOnlyHint: true, idempotentHint: true },
+            "Returns up to `limit` results (default 20). `mode='auto'` is the standard startup path; `mode='on-demand'` signals an explicit mid-session lookup. `depth='deep'` runs a broader semantic sweep at higher latency — use when the topic is unfamiliar. Phrase `query` as what you need to recall, not what you are about to do.\n\n" +
+            "NOTE: this tool updates access-pattern counters on the memories it returns (used to boost frequently-recalled memories in future ranking), so it is NOT side-effect-free despite being a lookup.",
+        // retrieveMemories mutates access_count on the rows it returns, so it is
+        // not read-only and the previous idempotentHint was inaccurate.
+        annotations: { readOnlyHint: false },
         inputShape: {
             query: retrieveMemoriesRequestSchema.shape.query.describe("Natural-language description of what you need to recall. Phrase as a topic or question (e.g. 'database connection settings', 'auth flow decisions') — not an action ('store info about...')."),
             limit: retrieveMemoriesRequestSchema.shape.limit.describe("Maximum number of memories to return. Integer 1-100, default 20. Increase for broad topic sweeps; keep at default for focused lookups."),
@@ -42,13 +75,14 @@ const TOOL_DEFINITIONS = [
         description: "Persist a single memory unit to the local SQLite store. Accepts decisions, facts, architectural choices, warnings, and session summaries. NOT idempotent — each call creates a new record even with identical content. Writes to disk immediately.\n\n" +
             "WHEN TO CALL: After any significant decision, discovery, or conclusion that should be available in a future session. Good candidates: technology choices, non-obvious constraints, bug root-causes, architectural decisions, key facts about the codebase.\n\n" +
             "WHEN NOT TO CALL: For trivial observations, transient state, or content that duplicates what was just retrieved. Do not store entire files or full conversation transcripts.\n\n" +
-            "`kind` categories: 'decision', 'fact', 'summary', 'warning', 'architecture'. Write `content` to be self-contained — it must be useful without any surrounding conversation context. `importance` 1-10 (10 = most critical); directly affects retrieval ranking in future sessions.",
+            "`kind` categories: 'decision', 'fact', 'summary', 'warning', 'preference'. Write `content` to be self-contained — it must be useful without any surrounding conversation context. `importance` 1-10 (10 = most critical); directly affects retrieval ranking in future sessions.\n\n" +
+            "RESPONSE may include `warningCodes`: 'session_write_limit_warning' (this session has stored many memories — stop storing trivia and prefer batchStoreMemory) and 'redaction_partial_failure' (a redaction rule errored; the write still succeeded). Treat them as advisory signals, not errors.",
         annotations: { destructiveHint: false, idempotentHint: false },
         inputShape: {
             memoryId: storeMemoryRequestSchema.shape.memoryId.describe("Caller-supplied unique UUID for this memory (e.g. crypto.randomUUID()). Used for deduplication and for later retrieval by ID via getMemory."),
             sessionId: storeMemoryRequestSchema.shape.sessionId.describe("Identifier for the current session. Used to group memories by session for diagnostics. Use a consistent ID within a single session."),
             sourceAdapter: storeMemoryRequestSchema.shape.sourceAdapter.describe("Name of the adapter or host creating this memory (e.g. 'claude-code', 'cursor', 'generic'). Used for provenance tracking."),
-            kind: storeMemoryRequestSchema.shape.kind.describe("Category of this memory. Recommended values: 'decision', 'fact', 'summary', 'warning', 'architecture'. Any non-empty string is valid."),
+            kind: storeMemoryRequestSchema.shape.kind.describe("Category of this memory. One of: 'decision', 'fact', 'warning', 'preference', 'summary'. These are the only recognized kinds — others are rejected."),
             content: storeMemoryRequestSchema.shape.content.describe("The memory text. Must be self-contained and specific — written so it is useful without surrounding conversation context. Avoid vague phrases like 'the user decided to...'."),
             importance: storeMemoryRequestSchema.shape.importance.describe("Integer 1-10 indicating criticality (10 = most important). Directly affects ranking in future retrieveMemories calls. Use 8-10 for decisions that must not be forgotten; 3-5 for useful but non-critical facts."),
             redactionEnabled: storeMemoryRequestSchema.shape.redactionEnabled.describe("If true, PII is stripped from content before storage. Omit to use the project-level redaction setting from config.json."),
@@ -103,20 +137,75 @@ const TOOL_DEFINITIONS = [
         description: "Persist multiple memory units in a single atomic SQLite transaction. Significantly faster than calling storeMemory repeatedly for session-end writes of 10-20 memories.\n\n" +
             "WHEN TO CALL: At session end or whenever you have multiple memories to store at once. Reduces overhead from per-insert fsync by wrapping all writes in one transaction.\n\n" +
             "WHEN NOT TO CALL: For a single memory — use storeMemory instead. For imports from external files — use importMemories.\n\n" +
-            "Each item in the `memories` array follows the same schema as storeMemory (memoryId, sessionId, sourceAdapter, kind, content, importance). Invalid items are reported individually; valid items are still stored atomically.",
+            "Each item in the `memories` array follows the same schema as storeMemory (memoryId, sessionId, sourceAdapter, kind, content, importance). Invalid items are reported individually; valid items are still stored atomically.\n\n" +
+            "NOTE: the per-item `memory` echoed back in the response has its `content` truncated to 2000 characters (a batch can return many rows). The full body is still persisted — fetch it with getMemory if you need the complete text. (Single-record storeMemory echoes the full content.)",
         annotations: { destructiveHint: false, idempotentHint: false },
         inputShape: {
-            memories: batchStoreMemoryRequestSchema.shape.memories.describe("Array of memory objects to store. Each must include: memoryId (unique UUID), sessionId, sourceAdapter, kind, content (self-contained text), importance (1-10). Minimum 1 item."),
+            memories: batchStoreMemoryRequestSchema.shape.memories.describe("Array of memory objects to store. Each must include: memoryId (unique UUID), sessionId, sourceAdapter, kind, content (self-contained text), importance (1-10). Minimum 1 item, maximum 100.\n\n" +
+                "Per-item results may include `warningCodes` (e.g. 'session_write_limit_warning', 'redaction_partial_failure') — advisory signals, not failures."),
         },
     },
+    {
+        method: "ingestSessionEvents",
+        description: "Push raw session events (tool calls, decisions, file edits, user turns) to sessionmem so they can be summarized at session end and counted toward token-savings analytics. Writes immediately, in a single transaction. Re-ingesting the same (sessionId, eventIndex) is a no-op, so retries are safe.\n\n" +
+            "WHEN TO CALL: Periodically during a session (e.g. at task boundaries) to record what happened, OR in one batch shortly before the session ends. This is what powers automatic session-end summarization and `sessionmem savings`.\n\n" +
+            "WHEN NOT TO CALL: For durable, individually-important facts/decisions — use storeMemory for those. Session events are transient raw material for summarization, not first-class memories.\n\n" +
+            "Each event needs: id (unique), eventIndex (monotonic 0-based order within the session), eventType (e.g. 'tool_use', 'user_message'), payloadJson (a JSON string of the event body).\n\n" +
+            "LIMITS: at most 500 events per call. For more than 500 events, call this tool multiple times in chunks — re-ingestion of already-stored events is safe (idempotent via the (project, session, eventIndex) UNIQUE index), so overlapping chunks never double-count.",
+        annotations: { destructiveHint: false, idempotentHint: true },
+        inputShape: shapeWithoutProjectId(ingestSessionEventsRequestSchema.shape),
+    },
+    {
+        method: "summarizeSessionToMemory",
+        description: "Store an agent-authored session summary as a durable 'summary' memory in one call. Upserts on memoryId, so calling it again with the same memoryId replaces the prior summary rather than duplicating it.\n\n" +
+            "WHEN TO CALL: At session end when you have already written a concise summary of what was accomplished and want to persist it directly (the simpler alternative to handleSessionEnd's automatic summarization).\n\n" +
+            "WHEN NOT TO CALL: When you want sessionmem to generate the summary from ingested session events — use handleSessionEnd for that. For non-summary facts/decisions use storeMemory.\n\n" +
+            "Provide: memoryId (stable id for this session's summary), sessionId, sourceAdapter, summary (the text), importance (1-10; 7 is typical for summaries).",
+        annotations: { destructiveHint: false, idempotentHint: true },
+        inputShape: shapeWithoutProjectId(summarizeSessionToMemoryRequestSchema.shape),
+    },
+    {
+        method: "handleSessionEnd",
+        description: "Run the full session-end pipeline: auto-summarize the session's ingested events into a durable memory (when enough events exist) and apply a light retention prune of stale memories. Idempotent on the summary memory (upsert by sessionId).\n\n" +
+            "WHEN TO CALL: Once, at the very end of a session, after ingesting session events via ingestSessionEvents. Lets sessionmem generate and store the session summary for you.\n\n" +
+            "WHEN NOT TO CALL: Mid-session, or when you have already written your own summary (use summarizeSessionToMemory instead). On Claude Code this also runs automatically via the installed SessionEnd hook, so calling it explicitly is usually unnecessary there.\n\n" +
+            "Provide sessionId and sourceAdapter. `memoryId` (optional) pins the summary's id; omit to derive `${sessionId}-summary`. `config` (optional) tunes autoSummarize / minimumEventThreshold / cloud summarization; omit for sensible local-only defaults.\n\n" +
+            "RESPONSE `status` is one of: 'stored', 'skipped_threshold' (too few events), 'skipped_disabled', 'failed'. `warningCodes` may carry cloud/local fallback signals.",
+        annotations: { destructiveHint: false, idempotentHint: true },
+        inputShape: shapeWithoutProjectId(handleSessionEndRequestSchema.shape),
+    },
 ];
 export class GenericMCPAdapter {
     name = "Generic MCP";
+    /**
+     * When true, the `startup_inject_memories` fallback tool is NOT registered.
+     * Hosts that already inject prior context deterministically at session start
+     * (e.g. Claude Code via its SessionStart hook) set this so the agent cannot
+     * double-inject memories — calling the tool on top of the hook would duplicate
+     * the injected content and double-count access_count increments.
+     */
+    suppressStartupInjectionTool = false;
+    // The stdio server (startMcpServer) registers TOOLS only — it never calls
+    // server.registerPrompt() or server.registerResource(). Advertising prompt or
+    // resource support here would make FallbackToolRegistrar SKIP the
+    // startup_inject_memories / fetch_memories tools (it only registers them when
+    // the matching capability is absent), leaving the agent with no automatic
+    // startup-injection path. Capabilities therefore reflect reality: tools only.
+    // Host subclasses inherit this and MUST NOT re-enable prompts/resources unless
+    // they actually register them on the server.
     capabilities = {
-        supportsPrompts: true,
-        supportsResources: true,
+        supportsPrompts: false,
+        supportsResources: false,
         supportsTools: true,
     };
+    /**
+     * Default agent-guidance target for an undetected/generic MCP host: a
+     * project-local AGENTS.md (the emerging cross-tool standard). Host subclasses
+     * override this with the file their agent actually reads at startup.
+     */
+    guidanceTargets() {
+        return [join(process.cwd(), "AGENTS.md")];
+    }
     /**
      * Fallback for hosts that aren't specifically detected: register sessionmem
      * in a project-local `.mcp.json` (the de-facto generic MCP config format).
@@ -146,9 +235,23 @@ export class GenericMCPAdapter {
         // SESSIONMEM_PROJECT_ID) used for isolated integration tests.
         const ctx = createCliContext();
         const { service, projectId } = ctx;
+        // Surface stale embeddings (e.g. after an EMBEDDING_VERSION bump) so the
+        // operator knows semantic ranking has degraded to importance+recency for
+        // those rows until `sessionmem re-embed` is run. Best-effort; to stderr only
+        // so it can never corrupt the stdio protocol stream.
+        try {
+            const stale = countStaleEmbeddings(ctx.db, projectId, EMBEDDING_VERSION);
+            if (stale > 0) {
+                logDiagnostic(`${stale} memory(ies) have stale embeddings (version != ${EMBEDDING_VERSION}). ` +
+                    `Run \`sessionmem re-embed\` to restore full semantic ranking.`);
+            }
+        }
+        catch {
+            // Never block server startup on a diagnostic query.
+        }
         const server = new McpServer({
             name: "sessionmem",
-            version: "1.0.5",
+            version: SERVER_VERSION,
         });
         for (const def of TOOL_DEFINITIONS) {
             server.registerTool(def.method, {
@@ -157,7 +260,26 @@ export class GenericMCPAdapter {
                 ...(def.annotations ? { annotations: def.annotations } : {}),
             }, async (args) => {
                 // Inject the server-resolved projectId; clients never set it.
-                const request = { ...args, projectId };
+                const enriched = { ...args, projectId };
+                // Default a missing sessionId for tools that require one so the
+                // per-session counters and session-end correlation stay consistent
+                // even when the agent omits (or cannot supply) a stable sessionId.
+                if ("sessionId" in def.inputShape && isMissing(enriched.sessionId)) {
+                    enriched.sessionId = resolveDefaultSessionId();
+                }
+                // batchStoreMemory carries sessionId per-item, not at the top level —
+                // backfill each item that omitted it with a single shared default.
+                if (def.method === "batchStoreMemory" && Array.isArray(enriched.memories)) {
+                    let sharedDefault;
+                    enriched.memories = enriched.memories.map((entry) => {
+                        if (entry && typeof entry === "object" && isMissing(entry.sessionId)) {
+                            sharedDefault ??= resolveDefaultSessionId();
+                            return { ...entry, sessionId: sharedDefault };
+                        }
+                        return entry;
+                    });
+                }
+                const request = enriched;
                 const result = await service.call(def.method, request);
                 if (result.ok === false) {
                     return {
@@ -186,13 +308,26 @@ export class GenericMCPAdapter {
         const fallbackTools = FallbackToolRegistrar.getFallbackTools(this.capabilities, {
             service,
             projectId,
-        });
+        }).filter((fallback) => !(this.suppressStartupInjectionTool && fallback.name === "startup_inject_memories"));
         for (const fallback of fallbackTools) {
             server.registerTool(fallback.name, { description: fallback.description, inputSchema: fallback.inputShape }, async (args) => {
                 const result = await fallback.execute(args);
                 return { content: [{ type: "text", text: result }] };
             });
         }
+        // Graceful shutdown: close the DB on SIGINT/SIGTERM so SQLite checkpoints
+        // the WAL and releases its file handles cleanly before the process exits.
+        const shutdown = () => {
+            try {
+                ctx.db.close();
+            }
+            catch {
+                // best-effort; never block exit on a close failure
+            }
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
         logDiagnostic(`Starting Generic MCP server over stdio (project: ${projectId})`);
         await server.connect(new StdioServerTransport());
     }

package/dist/adapters/global/antigravity.js

@@ -2,21 +2,28 @@ import { join } from "path";
 import { homedir } from "os";
 import { GenericMCPAdapter } from "../generic.js";
 import { IDEInstaller } from "../ide/installer.js";
+// ⚠️ UNVERIFIED: The MCP config path for "Antigravity" has not been confirmed
+// against official documentation. `~/.gemini/config/mcp_config.json` is the
+// real path for Gemini CLI, and may apply if Antigravity is a Gemini-family
+// tool. Verify before relying on this adapter for production installs.
+// The `{ "mcpServers": { ... } }` structure IDEInstaller writes is consistent
+// with Gemini CLI's documented MCP config format.
+const ANTIGRAVITY_MCP_CONFIG = [".gemini", "config", "mcp_config.json"];
 export class AntigravityAdapter extends GenericMCPAdapter {
     name = "Antigravity";
-    capabilities = {
-        supportsPrompts: true,
-        supportsResources: true,
-        supportsTools: true,
-    };
+    // Capabilities inherited from GenericMCPAdapter (tools only).
+    /** Antigravity reads AGENTS.md-style guidance from its global config dir. */
+    guidanceTargets() {
+        return [join(homedir(), ".antigravity", "AGENTS.md")];
+    }
     async install() {
-        const configPath = join(homedir(), ".antigravity", "config.json");
+        const configPath = join(homedir(), ...ANTIGRAVITY_MCP_CONFIG);
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);
     }
     async uninstall() {
-        const configPath = join(homedir(), ".antigravity", "config.json");
+        const configPath = join(homedir(), ...ANTIGRAVITY_MCP_CONFIG);
         return IDEInstaller.removeMcpConfig(configPath, "sessionmem");
     }
 }

package/dist/adapters/global/claudeCode.js

@@ -1,22 +1,58 @@
 import { join } from "path";
 import { homedir } from "os";
 import { GenericMCPAdapter } from "../generic.js";
-import { IDEInstaller } from "../ide/installer.js";
+import { IDEInstaller, SESSIONMEM_HOOK_COMMAND, SESSIONMEM_SESSION_END_HOOK_COMMAND, } from "../ide/installer.js";
 export class ClaudeCodeAdapter extends GenericMCPAdapter {
     name = "Claude Code";
-    capabilities = {
-        supportsPrompts: true,
-        supportsResources: true,
-        supportsTools: true,
-    };
+    // Capabilities inherited from GenericMCPAdapter (tools only) so the
+    // fetch_memories fallback tool is registered.
+    // The installed SessionStart hook already injects prior context at the start
+    // of every session, so suppress the startup_inject_memories tool: an agent
+    // calling it on top of the hook would double-inject content and double-count
+    // access_count increments.
+    suppressStartupInjectionTool = true;
+    /**
+     * Claude Code reads ~/.claude/CLAUDE.md as global memory on every session
+     * across all projects — the right place for the sessionmem guidance block.
+     */
+    guidanceTargets() {
+        return [join(homedir(), ".claude", "CLAUDE.md")];
+    }
+    settingsPath() {
+        return join(homedir(), ".claude", "settings.json");
+    }
     async install() {
         const configPath = join(homedir(), ".claude.json");
-        return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
-            "run",
-        ]);
+        // On Windows, the globally-installed `sessionmem` bin is a `.cmd` shim.
+        // Claude Code spawns MCP servers WITHOUT a shell, and `.cmd` shims require
+        // cmd.exe to execute, so a bare `command: "sessionmem"` fails to start.
+        // Route through `cmd /c sessionmem run` so the shim is resolved correctly.
+        const isWindows = process.platform === "win32";
+        const command = isWindows ? "cmd" : "sessionmem";
+        const args = isWindows ? ["/c", "sessionmem", "run"] : ["run"];
+        const mcpOk = await IDEInstaller.injectMcpConfig(configPath, "sessionmem", command, args);
+        // Register a SessionStart hook so prior memories are injected automatically
+        // at the start of EVERY Claude Code session. This is the deterministic
+        // auto-injection path the advisory `startup_inject_memories` tool could
+        // never guarantee: a hook runs unconditionally and Claude Code adds its
+        // output to the session context without the agent choosing to call a tool.
+        // A hook-wiring failure now propagates so the install command reports a
+        // failure if the SessionStart/SessionEnd hooks could not be written.
+        const startHookOk = await IDEInstaller.injectClaudeHook(this.settingsPath(), SESSIONMEM_HOOK_COMMAND);
+        // Register a SessionEnd hook so the session-end pipeline (light retention
+        // prune + auto-summarization of ingested session events) runs once when a
+        // session ends — the deterministic write-side counterpart to the
+        // SessionStart read-side hook.
+        const endHookOk = await IDEInstaller.injectClaudeHook(this.settingsPath(), SESSIONMEM_SESSION_END_HOOK_COMMAND, "SessionEnd");
+        return mcpOk && startHookOk && endHookOk;
     }
     async uninstall() {
         const configPath = join(homedir(), ".claude.json");
-        return IDEInstaller.removeMcpConfig(configPath, "sessionmem");
+        const mcpOk = await IDEInstaller.removeMcpConfig(configPath, "sessionmem");
+        // Propagate hook-removal results so a failure to clean up either hook is
+        // reported as an uninstall failure rather than silently ignored.
+        const startOk = await IDEInstaller.removeClaudeHook(this.settingsPath(), SESSIONMEM_HOOK_COMMAND);
+        const endOk = await IDEInstaller.removeClaudeHook(this.settingsPath(), SESSIONMEM_SESSION_END_HOOK_COMMAND, "SessionEnd");
+        return mcpOk && startOk && endOk;
     }
 }