sessionmem 1.0.5 → 1.1.0

package/dist/adapters/capabilities/fallbackTools.js

@@ -1,34 +1,49 @@
+import { z } from "zod";
 export class FallbackToolRegistrar {
-    static getFallbackTools(capabilities) {
+    static getFallbackTools(capabilities, context) {
         const tools = [];
         if (!capabilities.supportsResources) {
             tools.push({
                 name: "fetch_memories",
-                description: "Fallback tool to fetch memories because host lacks MCP resource support.",
-                schema: {
-                    type: "object",
-                    properties: {
-                        query: { type: "string" },
-                    },
-                    required: ["query"],
+                description: "Fallback memory retrieval for hosts that do not support MCP resources. Call this instead of accessing the sessionmem:// resource URI directly when the host lacks resource support. Semantically equivalent to retrieveMemories — returns stored memories ranked by relevance to the query. Read-only; no side effects.\n\n" +
+                    "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().min(1).max(1000).describe("Natural-language description of what context you need to recall."),
                 },
                 execute: async (args) => {
-                    // Wrap core retrieval logic
-                    return `Fetched memories for ${args.query}`;
-                }
+                    const result = await context.service.call("retrieveMemories", {
+                        projectId: context.projectId,
+                        query: args.query,
+                        limit: 10,
+                        mode: "on-demand",
+                        depth: "default",
+                    });
+                    if (!result.ok)
+                        return `Error: ${result.error.message}`;
+                    return JSON.stringify(result.memories, null, 2);
+                },
             });
         }
         if (!capabilities.supportsPrompts) {
             tools.push({
                 name: "startup_inject_memories",
-                description: "Fallback tool to manually request startup injection because host lacks MCP prompt support.",
-                schema: {
-                    type: "object",
-                    properties: {},
-                },
+                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" +
+                    "Note: access counts are incremented on retrieval.",
+                inputShape: {},
                 execute: async () => {
-                    return "Startup memories injected.";
-                }
+                    const result = await context.service.call("retrieveMemories", {
+                        projectId: context.projectId,
+                        query: "session startup context",
+                        limit: 20,
+                        mode: "auto",
+                        depth: "default",
+                    });
+                    if (!result.ok)
+                        return `Error: ${result.error.message}`;
+                    return result.startupInjection;
+                },
             });
         }
         return tools;

package/dist/adapters/claudeMdInjector.js

@@ -0,0 +1,164 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+export const SESSIONMEM_BLOCK_START = "<!-- sessionmem:start -->";
+export const SESSIONMEM_BLOCK_END = "<!-- sessionmem:end -->";
+const BLOCK_CONTENT = `
+## sessionmem — Persistent Memory
+
+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
+- You discover a non-obvious project constraint or convention
+- A debugging session reveals an important root cause
+- 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 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 (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) and self-contained
+- Use appropriate importance scores (see kinds above)
+`;
+export function generateClaudeMdBlock() {
+    return `${SESSIONMEM_BLOCK_START}\n${BLOCK_CONTENT}\n${SESSIONMEM_BLOCK_END}`;
+}
+export function injectClaudeMdBlock(filePath) {
+    try {
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        let content = "";
+        if (existsSync(filePath)) {
+            content = readFileSync(filePath, "utf8");
+        }
+        const block = generateClaudeMdBlock();
+        if (hasClaudeMdBlock(filePath)) {
+            // Replace existing block
+            const startIdx = content.indexOf(SESSIONMEM_BLOCK_START);
+            const endIdx = content.indexOf(SESSIONMEM_BLOCK_END) + SESSIONMEM_BLOCK_END.length;
+            content = content.slice(0, startIdx) + block + content.slice(endIdx);
+        }
+        else {
+            // Append to file
+            if (content.length > 0 && !content.endsWith("\n")) {
+                content += "\n";
+            }
+            content += "\n" + block + "\n";
+        }
+        writeFileSync(filePath, content, "utf8");
+        return true;
+    }
+    catch {
+        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)) {
+            return true;
+        }
+        const content = readFileSync(filePath, "utf8");
+        const startIdx = content.indexOf(SESSIONMEM_BLOCK_START);
+        if (startIdx === -1) {
+            return true;
+        }
+        const endIdx = content.indexOf(SESSIONMEM_BLOCK_END);
+        if (endIdx === -1) {
+            return true;
+        }
+        const endOfBlock = endIdx + SESSIONMEM_BLOCK_END.length;
+        // Remove the block and any trailing newline
+        let before = content.slice(0, startIdx);
+        let after = content.slice(endOfBlock);
+        // Clean up extra blank lines around the removed block
+        if (after.startsWith("\n")) {
+            after = after.slice(1);
+        }
+        if (before.endsWith("\n\n")) {
+            before = before.slice(0, -1);
+        }
+        writeFileSync(filePath, before + after, "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function hasClaudeMdBlock(filePath) {
+    try {
+        if (!existsSync(filePath)) {
+            return false;
+        }
+        const content = readFileSync(filePath, "utf8");
+        return (content.includes(SESSIONMEM_BLOCK_START) &&
+            content.includes(SESSIONMEM_BLOCK_END));
+    }
+    catch {
+        return false;
+    }
+}

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,9 +1,13 @@
+import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { forgetMemoryRequestSchema, getMemoryRequestSchema, listMemoriesRequestSchema, 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
@@ -13,6 +17,11 @@ import { IDEInstaller } from "./ide/installer.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.
@@ -21,45 +30,182 @@ 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: "Retrieve the most relevant stored memories for a semantic query, ranked by relevance, recency, and importance.",
-        inputShape: shapeWithoutProjectId(retrieveMemoriesRequestSchema.shape),
+        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.\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."),
+            mode: retrieveMemoriesRequestSchema.shape.mode.describe("'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question."),
+            depth: retrieveMemoriesRequestSchema.shape.depth.describe("'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar."),
+        },
     },
     {
         method: "storeMemory",
-        description: "Store a memory (decision, fact, summary, or warning) for the current project.",
-        inputShape: shapeWithoutProjectId(storeMemoryRequestSchema.shape),
+        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', '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. 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."),
+        },
     },
     {
         method: "listMemories",
-        description: "List all stored memories for the current project.",
+        description: "Return every memory stored for the current project, unfiltered and without ranking. Read-only; no side effects.\n\n" +
+            "WHEN TO CALL: When you need a complete inventory of stored memories — to audit what has been saved, detect duplicates, or build a full summary of all known context.\n\n" +
+            "WHEN NOT TO CALL: For normal context loading at session start — use retrieveMemories instead, which ranks by relevance. listMemories returns the entire store unfiltered and can be very large.",
+        annotations: { readOnlyHint: true, idempotentHint: true },
         inputShape: shapeWithoutProjectId(listMemoriesRequestSchema.shape),
     },
     {
         method: "getMemory",
-        description: "Fetch a single stored memory by its ID.",
-        inputShape: shapeWithoutProjectId(getMemoryRequestSchema.shape),
+        description: "Fetch a single memory record by its exact ID. Returns the full record: content, kind, importance, timestamps, and session metadata. Read-only; no side effects.\n\n" +
+            "WHEN TO CALL: When you already have a specific memoryId from a prior retrieveMemories or listMemories result and need its full detail.\n\n" +
+            "WHEN NOT TO CALL: For topic-based search — use retrieveMemories for that. This tool requires an exact ID and does not search by content.",
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        inputShape: {
+            memoryId: getMemoryRequestSchema.shape.memoryId.describe("Exact UUID of the memory to fetch. Obtain from a prior retrieveMemories or listMemories result."),
+        },
     },
     {
         method: "forgetMemory",
-        description: "Delete a stored memory by its ID.",
-        inputShape: shapeWithoutProjectId(forgetMemoryRequestSchema.shape),
+        description: "Permanently delete a single memory by ID. The record is removed from the local SQLite store immediately and CANNOT be recovered. Destructive and irreversible.\n\n" +
+            "WHEN TO CALL: Only when a memory is known to be incorrect, dangerously outdated, or a duplicate that would mislead future sessions.\n\n" +
+            "WHEN NOT TO CALL: If there is any doubt. A memory that is merely old or low-relevance does not need deletion — retrieval ranking deprioritizes it automatically.",
+        annotations: { destructiveHint: true, idempotentHint: false },
+        inputShape: {
+            memoryId: forgetMemoryRequestSchema.shape.memoryId.describe("Exact UUID of the memory to permanently delete. Obtain from a prior listMemories or retrieveMemories call. Deletion is immediate and irreversible."),
+        },
     },
     {
         method: "stats",
-        description: "Report memory statistics (total memories and session events) for the current project.",
+        description: "Return aggregate statistics for the current project: total stored memory count and total ingested session event count. Read-only; no side effects.\n\n" +
+            "WHEN TO CALL: For diagnostic or monitoring purposes — to confirm memories were stored after a session, check store health, or report usage numbers.\n\n" +
+            "WHEN NOT TO CALL: As part of normal context loading. stats returns counts only, not content; use retrieveMemories to load actual context.",
+        annotations: { readOnlyHint: true, idempotentHint: true },
         inputShape: shapeWithoutProjectId(statsRequestSchema.shape),
     },
+    {
+        method: "resetAccessCounts",
+        description: "Reset access-pattern counters for all memories in the current project. Sets access_count to 0 and clears last_accessed timestamps without deleting any memories. Useful after large refactors when old access patterns no longer reflect current relevance.\n\n" +
+            "WHEN TO CALL: After major codebase restructuring, project pivots, or when access-boosted rankings no longer reflect current relevance.\n\n" +
+            "WHEN NOT TO CALL: During normal operation — access patterns self-correct as usage shifts.",
+        annotations: { destructiveHint: false, idempotentHint: true },
+        inputShape: shapeWithoutProjectId(resetAccessCountsRequestSchema.shape),
+    },
+    {
+        method: "batchStoreMemory",
+        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.\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, 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).
@@ -89,17 +235,51 @@ 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.0",
+            version: SERVER_VERSION,
         });
         for (const def of TOOL_DEFINITIONS) {
             server.registerTool(def.method, {
                 description: def.description,
                 inputSchema: def.inputShape,
+                ...(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 {
@@ -122,6 +302,32 @@ export class GenericMCPAdapter {
                 };
             });
         }
+        // Register fallback tools for hosts that lack resource or prompt support.
+        // These provide fetch_memories and startup_inject_memories as tool-based
+        // alternatives, wired to the same service instance used by TOOL_DEFINITIONS.
+        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());
     }