sessionmem 1.0.5 → 1.0.6

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().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" +
+                    "Read-only; no side effects.",
+                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,120 @@
+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. Use its tools to store important decisions, facts, and context so they're available in future sessions without the user re-explaining.
+
+### 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 (retrieveMemories)
+- At the start of a session or task to check for relevant prior context
+- 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
+
+### 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)
+
+### Other tools
+- \`listMemories\` — browse all stored memories for this project
+- \`getMemory\` — fetch a specific memory by ID
+- \`forgetMemory\` — delete an outdated or incorrect memory
+- \`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)
+- 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;
+    }
+}
+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/generic.js

@@ -1,9 +1,10 @@
 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, listMemoriesRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, statsRequestSchema, storeMemoryRequestSchema, } 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";
 /**
  * Diagnostic logging sink for the stdio server. CRITICAL: the MCP protocol
  * frames are written to STDOUT by StdioServerTransport, so anything this server
@@ -24,34 +25,90 @@ function shapeWithoutProjectId(shape) {
 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.",
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        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', '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.",
+        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."),
+            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.",
+        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."),
+        },
+    },
 ];
 export class GenericMCPAdapter {
     name = "Generic MCP";
@@ -91,12 +148,13 @@ export class GenericMCPAdapter {
         const { service, projectId } = ctx;
         const server = new McpServer({
             name: "sessionmem",
-            version: "1.0.0",
+            version: "1.0.5",
         });
         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 };
@@ -122,6 +180,19 @@ 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,
+        });
+        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 }] };
+            });
+        }
         logDiagnostic(`Starting Generic MCP server over stdio (project: ${projectId})`);
         await server.connect(new StdioServerTransport());
     }

package/dist/adapters/tools/ping.js

@@ -1,3 +1,6 @@
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const pkg = require("../../../package.json");
 export const pingTool = {
     name: "sessionmem_ping",
     description: "Ping the sessionmem MCP server to verify it is running correctly.",
@@ -8,7 +11,7 @@ export const pingTool = {
     execute: async () => {
         return {
             status: "ok",
-            version: "0.1.0",
+            version: pkg.version,
             message: "sessionmem MCP server is operational.",
         };
     }

package/dist/cli/commands/install.js

@@ -1,5 +1,8 @@
 import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
 import { AdapterFactory } from "../../adapters/factory.js";
+import { injectClaudeMdBlock } from "../../adapters/claudeMdInjector.js";
 import { createCliContext } from "../context.js";
 import { configFilePath, writePolicyConfig, DEFAULT_POLICY_CONFIG, } from "../../core/config/policyConfig.js";
 export const MANUAL_CONFIG_BLOCK = JSON.stringify({
@@ -52,6 +55,20 @@ export async function installCommand(_options, contextOverrides) {
         process.exit(1);
     }
     console.log(`✓ ${adapter.name} config updated`);
-    // Step 3: Full success checklist
+    // Step 3: CLAUDE.md injection — non-fatal
+    const claudeMdPath = join(homedir(), ".claude", "CLAUDE.md");
+    try {
+        const injected = injectClaudeMdBlock(claudeMdPath);
+        if (injected) {
+            console.log(`✓ CLAUDE.md instructions injected (${claudeMdPath})`);
+        }
+        else {
+            console.error("✗ CLAUDE.md injection failed (non-fatal)");
+        }
+    }
+    catch {
+        console.error("✗ CLAUDE.md injection failed (non-fatal)");
+    }
+    // Step 4: Full success checklist
     console.log("✓ sessionmem ready");
 }

package/dist/cli/commands/reEmbed.js

@@ -0,0 +1,47 @@
+import { createCliContext } from "../context.js";
+import { deterministicEmbed } from "../../core/embed/deterministicEmbed.js";
+import { EMBEDDING_VERSION } from "../../core/embed/embeddingVersion.js";
+const DEFAULT_EMBEDDING_DIMENSION = 32;
+/**
+ * `sessionmem re-embed`
+ *
+ * Bulk-update embeddings for all memories whose embedding_version does not
+ * match the current EMBEDDING_VERSION. Recomputes each embedding with
+ * deterministicEmbed and writes the new vector + version back to the row.
+ */
+export async function reEmbedCommand(ctx) {
+    const context = ctx ?? createCliContext();
+    const { db } = context;
+    const stale = db
+        .prepare(`
+      SELECT id, content, embedding_dim
+      FROM memories
+      WHERE embedding_version IS NULL OR embedding_version != ?
+    `)
+        .all(EMBEDDING_VERSION);
+    const total = stale.length;
+    if (total === 0) {
+        console.log("All embeddings are up to date.");
+        return;
+    }
+    console.log(`Found ${total} memories with stale embeddings. Re-embedding...`);
+    const updateStmt = db.prepare(`
+    UPDATE memories
+    SET embedding = ?, embedding_dim = ?, embedding_version = ?
+    WHERE id = ?
+  `);
+    let count = 0;
+    const runAll = db.transaction(() => {
+        for (const row of stale) {
+            const dim = row.embedding_dim ?? DEFAULT_EMBEDDING_DIMENSION;
+            const result = deterministicEmbed(row.content, dim);
+            updateStmt.run(JSON.stringify(result.vector), result.dimension, EMBEDDING_VERSION, row.id);
+            count += 1;
+            if (count % 100 === 0 || count === total) {
+                console.log(`  ${count}/${total}`);
+            }
+        }
+    });
+    runAll();
+    console.log(`Re-embedded ${count} memories to version ${EMBEDDING_VERSION}.`);
+}

package/dist/cli/commands/run.js

@@ -4,10 +4,32 @@ import { join } from "path";
 import { homedir } from "os";
 export async function runMcpServer() {
     const adapter = AdapterFactory.detectAdapter();
-    // Setup rudimentary log for debugging manual configs
+    // Startup diagnostics: written to ~/.sessionmem/logs/mcp.log
     const logDir = join(homedir(), ".sessionmem", "logs");
     const logPath = join(logDir, "mcp.log");
-    const logMessage = `[${new Date().toISOString()}] Started sessionmem via ${adapter.name}\n`;
+    // Derive db path for diagnostics (mirrors context.ts defaultDbPath)
+    const envDbPath = process.env.SESSIONMEM_DB_PATH;
+    const dbPath = envDbPath && envDbPath.trim() !== ""
+        ? envDbPath
+        : join(homedir(), ".sessionmem", "memories.db");
+    // Derive project ID for diagnostics (mirrors context.ts deriveProjectId)
+    const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
+    let projectId;
+    if (envProjectId && envProjectId.trim() !== "") {
+        projectId = envProjectId;
+    }
+    else {
+        const cwd = process.cwd();
+        const parts = cwd.replace(/\\/g, "/").split("/");
+        const raw = parts[parts.length - 1] || "default";
+        const sanitized = raw.replace(/[^A-Za-z0-9._-]/g, "_");
+        projectId =
+            sanitized === "" || sanitized === "." || sanitized === ".."
+                ? "default"
+                : sanitized;
+    }
+    const adapterName = adapter.name;
+    const logMessage = `[${new Date().toISOString()}] Started sessionmem | adapter=${adapterName} db=${dbPath} project=${projectId}\n`;
     try {
         mkdirSync(logDir, { recursive: true });
         writeFileSync(logPath, logMessage, { flag: "a" });
@@ -15,6 +37,10 @@ export async function runMcpServer() {
     catch {
         // best-effort logging; ignore failures
     }
+    // Debug output to stderr (never stdout — that's the MCP protocol channel)
+    if (process.env.SESSIONMEM_DEBUG === "1") {
+        process.stderr.write(`[sessionmem] db=${dbPath} project=${projectId} adapter=${adapterName}\n`);
+    }
     // Start the server
     if (adapter.startMcpServer) {
         await adapter.startMcpServer();

package/dist/cli/commands/savings.js

@@ -0,0 +1,75 @@
+import { createCliContext } from "../context.js";
+import { countTokens } from "../../core/injection/tokenBudget.js";
+import { listMemoriesByProject } from "../../core/storage/memoryRepo.js";
+import { countDistinctSessions, listEventPayloads, } from "../../core/storage/tokenSavingsRepo.js";
+import { readPolicyConfig, configFilePath, } from "../../core/config/policyConfig.js";
+/** Default injection token cap, mirroring formatStartupInjection.ts. */
+const DEFAULT_INJECTION_CAP = 450;
+export function savingsCommand(ctx, options) {
+    const context = ctx ?? createCliContext();
+    const { db, projectId } = context;
+    // --- gather raw numbers ---
+    const memoryTokens = listMemoriesByProject(db, projectId).reduce((sum, m) => sum + countTokens(m.content), 0);
+    const rawEventTokens = listEventPayloads(db, projectId).reduce((sum, p) => sum + countTokens(p), 0);
+    const sessions = countDistinctSessions(db, projectId);
+    // Read the injection cap from policy config if it exists; fall back to 450.
+    const _config = readPolicyConfig(options?.configPath ?? configFilePath());
+    const injectionCap = _config.injectionCap ??
+        DEFAULT_INJECTION_CAP;
+    // --- calculations ---
+    const tokensSaved = rawEventTokens - memoryTokens;
+    const savingsPct = rawEventTokens > 0 ? (tokensSaved / rawEventTokens) * 100 : 0;
+    const estimatedReexplainTokens = memoryTokens * 3;
+    const injectionSavings = estimatedReexplainTokens - sessions * injectionCap;
+    const overallSaved = tokensSaved + Math.max(0, injectionSavings);
+    const overallPct = rawEventTokens + estimatedReexplainTokens > 0
+        ? (overallSaved / (rawEventTokens + estimatedReexplainTokens)) * 100
+        : 0;
+    const avgInjectionCost = sessions > 0
+        ? Math.round((sessions * injectionCap) / sessions)
+        : 0;
+    // --- JSON output ---
+    if (options?.json) {
+        const payload = {
+            memoryTokens,
+            rawEventTokens,
+            tokensSaved,
+            savingsPct: Math.round(savingsPct * 10) / 10,
+            sessions,
+            injectionCap,
+            estimatedReexplainTokens,
+            injectionSavings,
+            overallSaved,
+            overallPct: Math.round(overallPct * 10) / 10,
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+        return;
+    }
+    // --- empty state ---
+    if (rawEventTokens === 0 && memoryTokens === 0) {
+        process.stdout.write("No session data yet. Token savings will appear after your first session.\n");
+        return;
+    }
+    // --- formatted report ---
+    const fmt = (n) => n.toLocaleString("en-US");
+    const lines = [
+        "sessionmem token savings",
+        "",
+        "Storage compression:",
+        `  Raw session tokens:  ${fmt(rawEventTokens).padStart(10)}`,
+        `  Memory tokens:       ${fmt(memoryTokens).padStart(10)}`,
+        `  Tokens saved:        ${fmt(tokensSaved).padStart(10)} (${(Math.round(savingsPct * 10) / 10).toFixed(1)}%)`,
+        "",
+        "Session injection:",
+        `  Total sessions:      ${fmt(sessions).padStart(10)}`,
+        `  Avg injection cost:  ${fmt(avgInjectionCost).padStart(10)} tokens/session`,
+        `  Est. re-explain cost:${fmt(estimatedReexplainTokens).padStart(10)} tokens (without sessionmem)`,
+        `  Injection savings:   ${fmt(Math.max(0, injectionSavings)).padStart(10)} tokens across ${fmt(sessions)} sessions`,
+        "",
+        "Overall:",
+        `  Total tokens saved:  ${fmt(overallSaved).padStart(10)}`,
+        `  Efficiency:          ${(Math.round(overallPct * 10) / 10).toFixed(1)}%`,
+        "",
+    ];
+    process.stdout.write(lines.join("\n"));
+}

package/dist/cli/commands/uninstall.js

@@ -2,6 +2,7 @@ import { existsSync, rmSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { AdapterFactory } from "../../adapters/factory.js";
+import { removeClaudeMdBlock } from "../../adapters/claudeMdInjector.js";
 export async function uninstallCommand(options = {}) {
     const adapter = AdapterFactory.detectAdapter();
     if (!adapter.uninstall) {
@@ -14,6 +15,15 @@ export async function uninstallCommand(options = {}) {
         process.exit(1);
     }
     console.log(`✓ ${adapter.name} config removed`);
+    // CLAUDE.md cleanup — non-fatal
+    const claudeMdPath = join(homedir(), ".claude", "CLAUDE.md");
+    try {
+        removeClaudeMdBlock(claudeMdPath);
+        console.log("✓ CLAUDE.md instructions removed");
+    }
+    catch {
+        console.error("✗ CLAUDE.md cleanup failed (non-fatal)");
+    }
     // Resolve dbPath: use injected override (for tests) or the default location
     const dbPath = options.dbPath ?? join(homedir(), ".sessionmem", "memories.db");
     if (options.purge) {

package/dist/cli/index.js

@@ -12,11 +12,13 @@ import { forgetCommand } from "./commands/forget.js";
 import { exportCommand } from "./commands/export.js";
 import { importCommand } from "./commands/import.js";
 import { statsCommand } from "./commands/stats.js";
+import { savingsCommand } from "./commands/savings.js";
 import { redactScanCommand } from "./commands/redactScan.js";
 import { retentionPruneCommand } from "./commands/retention.js";
 import { configGetCommand, configSetCommand } from "./commands/config.js";
 import { teamEnableCommand, teamDisableCommand, teamStatusCommand, } from "./commands/team.js";
 import { syncCommand } from "./commands/sync.js";
+import { reEmbedCommand } from "./commands/reEmbed.js";
 // Source the version from package.json (single source of truth) so `--version`
 // never drifts from the published manifest. createRequire + resolveJsonModule
 // reads the manifest relative to this module; from dist/cli/index.js the
@@ -81,6 +83,11 @@ program
     .command("stats")
     .description("Show memory statistics for the current project")
     .action(() => statsCommand());
+program
+    .command("savings")
+    .description("Show token savings from sessionmem compression and injection")
+    .option("--json", "Output raw metrics as JSON")
+    .action((options) => savingsCommand(undefined, options));
 // redact-scan — one-time scrub over existing memories. Scan is the
 // non-destructive default; --apply redacts matching rows in place.
 program
@@ -134,6 +141,13 @@ team
     .command("status")
     .description("Show team mode state and shared-path availability")
     .action(() => teamStatusCommand());
+// re-embed — bulk-update stale embeddings to the current version.
+// reEmbedCommand declares a trailing `ctx?` test seam, so arrow-wrap to drop
+// commander's trailing Command argument (NOTE above).
+program
+    .command("re-embed")
+    .description("Re-embed all memories with stale embedding versions")
+    .action(() => reEmbedCommand());
 // sync — push a local snapshot to the shared path and pull every
 // teammate snapshot back. syncCommand declares a trailing `ctx?` test seam, so
 // arrow-wrap to drop commander's trailing Command argument (NOTE above).