@asd412id/mcp-context-manager 1.0.10 → 1.0.12

package/README.md

@@ -10,6 +10,32 @@ MCP (Model Context Protocol) tools for context management in AI coding agents. H
 - **Session Checkpoint** - Save/restore session state
 - **Smart File Loader** - Load files with relevance filtering
 
+## Agent Skill (Recommended)
+
+For optimal agent performance, use the included **`SKILL.md`** file as agent instructions. This skill teaches agents to:
+
+- **Minimize context window usage** - Free up RAM by offloading data to persistent storage
+- **Auto-save progress** - Checkpoint every 10-15 messages
+- **Track decisions & changes** - Maintain project history
+- **Handle long sessions** - Seamless handoff to new sessions when context gets full
+
+### How to Use the Skill
+
+**Option 1: Claude Code / Cline / Cursor**
+Place `SKILL.md` in your project root or reference it in your agent configuration.
+
+**Option 2: Custom Agents**
+Include the content of `SKILL.md` in your system prompt or agent instructions.
+
+**Option 3: Direct Reference**
+Tell your agent: *"Load and follow the instructions in SKILL.md"*
+
+The skill provides:
+- Mandatory triggers for when to use each tool
+- Context cleanup strategies to reduce LLM memory usage
+- Best practices for minimal context consumption
+- Complete tool reference with examples
+
 ## Installation
 
 Requires Node.js >= 18.0.0
@@ -241,7 +267,7 @@ To specify a custom path for storing context data, add environment variables.
 
 | Prompt | Description |
 |--------|-------------|
-| `ctx-init` | Load context from previous session |
+| `ctx-init` | Load context from previous session with context management instructions |
 | `ctx-save` | Save current state to checkpoint |
 | `ctx-remember` | Save important info to memory |
 | `ctx-todo` | Add a todo item |
@@ -249,8 +275,10 @@ To specify a custom path for storing context data, add environment variables.
 | `ctx-status` | Show project status |
 | `ctx-compress` | Compress long context |
 | `ctx-recall` | Search in memory |
+| `ctx-cleanup` | **Free up context window space and reduce RAM usage** |
+| `ctx-handoff` | **Generate handoff document for new session** |
 
-## Available Tools (30 tools)
+## Available Tools (33 tools)
 
 ### Session Management
 
@@ -258,7 +286,7 @@ To specify a custom path for storing context data, add environment variables.
 |------|-------------|
 | `session_init` | Initialize session - loads checkpoint, tracker, memories, detects project in ONE call |
 | `session_handoff` | Generate compact markdown handoff document for seamless session continuation |
-| `project_detect` | Auto-detect project info from package.json, .git, pyproject.toml, Cargo.toml |
+| `project_detect` | Auto-detect project info (supports 20+ languages: Node, Python, Rust, Go, Java, PHP, Ruby, Elixir, .NET, Swift, Kotlin, Dart, Haskell, Scala, Clojure, Lua, Zig, Nim, V, Deno, Bun) |
 
 ### Memory Store
 
@@ -272,6 +300,7 @@ To specify a custom path for storing context data, add environment variables.
 | `memory_list` | List all memory keys |
 | `memory_clear` | Clear memory (all/by tags) |
 | `memory_cleanup` | Remove expired memory entries |
+| `memory_capture_candidates` | Extract and optionally persist important memory candidates from text |
 
 ### Context Summarizer
 
@@ -282,6 +311,7 @@ To specify a custom path for storing context data, add environment variables.
 | `context_list_summaries` | List all summaries |
 | `context_merge_summaries` | Merge multiple summaries |
 | `context_status` | Get storage stats and token usage estimate |
+| `context_prune_smart` | Score context items, keep high-signal, summarize/prune low-signal |
 | `store_health` | Check store integrity and recommendations |
 
 ### Project Tracker
@@ -290,6 +320,7 @@ To specify a custom path for storing context data, add environment variables.
 |------|-------------|
 | `tracker_log` | Log decision/change/todo/note/error |
 | `tracker_status` | Get project status overview |
+| `tracker_get` | Get specific tracker entry by ID |
 | `tracker_todo_update` | Update todo status |
 | `tracker_search` | Search tracker entries |
 | `tracker_set_project` | Set project name |

package/dist/prompts.js

@@ -1,15 +1,49 @@
 import * as z from 'zod';
+// Built-in instructions for context management and RAM optimization
+const CONTEXT_MANAGEMENT_INSTRUCTIONS = `
+## Context Management Best Practices
+
+**To minimize context window usage and free RAM:**
+
+1. **Recall before reading** - Use memory_search()/tracker_search() first, then read files only if needed
+2. **Offload to persistent storage** - Use memory_set() or memory_capture_candidates() for important findings
+3. **Read files efficiently** - Use file_smart_read(structureOnly:true) or file_smart_read(keywords:[...])
+4. **Smart prune context** - Use context_prune_smart() to keep high-signal items and prune low-signal chatter
+5. **Checkpoint regularly** - Save state every 10-15 messages with checkpoint_save()
+
+**When to cleanup (check with context_status()):**
+- Token usage >50% → Run context_prune_smart() and summarize verbose content
+- Token usage >70% → Checkpoint and consider handoff
+- Token usage >85% → MUST handoff to new session
+
+**Cleanup workflow:**
+1. context_status() → Check token usage
+2. context_prune_smart(items, mode:"hybrid") → Score and prune low-signal context
+3. context_summarize(longText) → Compress high-value verbose content
+4. memory_capture_candidates(text, dryRun:false) → Persist important facts automatically
+5. checkpoint_save() → Save state
+6. session_handoff() → Generate handoff doc
+`;
 export function registerPrompts(server) {
-    // ctx-init - Load previous context
+    // ctx-init - Load previous context with instructions
     server.registerPrompt('ctx-init', {
         title: 'Init Session',
-        description: 'Load previous context at session start'
+        description: 'Load previous context at session start with context management instructions'
     }, () => ({
         messages: [{
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Initialize session with session_init() - loads checkpoint, tracker status, memories, and detects project in one call.`
+                    text: `Initialize session with session_init() - loads checkpoint, tracker status, memories, and detects project in one call.
+
+${CONTEXT_MANAGEMENT_INSTRUCTIONS}
+
+**After init, follow these rules:**
+- Log decisions with tracker_log(type:"decision")
+- Log file changes with tracker_log(type:"change")
+- Capture important findings with memory_capture_candidates() or memory_set()
+- Prune processed context with context_prune_smart()
+- Checkpoint every 10-15 messages`
                 }
             }]
     }));
@@ -99,7 +133,7 @@ export function registerPrompts(server) {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Context getting long. Summarize conversation with context_summarize(), save checkpoint, store key info to memory.`
+                    text: `Context getting long. Run context_prune_smart() first, summarize with context_summarize(), persist key info via memory_capture_candidates(), then save checkpoint.`
                 }
             }]
     }));
@@ -121,4 +155,54 @@ export function registerPrompts(server) {
                 }
             }]
     }));
+    // ctx-cleanup - Cleanup context and free RAM
+    server.registerPrompt('ctx-cleanup', {
+        title: 'Cleanup Context',
+        description: 'Free up context window space and reduce RAM usage'
+    }, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Cleanup context to free RAM and reduce token usage.
+
+**Execute this workflow:**
+1. context_status() → Check current token usage estimate
+2. Identify verbose content in conversation that can be summarized
+3. context_prune_smart(items, mode:"hybrid") → Keep high-signal and prune low-signal context
+4. context_summarize(verboseText, maxLength:1000) → Compress long content
+5. memory_capture_candidates(text, dryRun:false) → Offload important data automatically
+6. checkpoint_save(name, state) → Save current session state
+7. If token usage >70%, run session_handoff() to prepare for new session
+
+**Tips to reduce context:**
+- Use file_smart_read(structureOnly:true) instead of reading full files
+- Use file_smart_read(keywords:[...]) to read only relevant sections
+- Store discovered info in memory_capture_candidates()/memory_set() instead of keeping in context
+- Don't re-read files - use memory_get() for cached data`
+                }
+            }]
+    }));
+    // ctx-handoff - Generate handoff for new session
+    server.registerPrompt('ctx-handoff', {
+        title: 'Session Handoff',
+        description: 'Generate handoff document for seamless session continuation'
+    }, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Context is getting long. Generate a handoff document for continuing in a new session.
+
+**Execute:**
+1. checkpoint_save() → Save current state
+2. session_handoff() → Generate compact markdown handoff
+
+**Instructions for new session:**
+1. Start new conversation
+2. Paste the handoff document
+3. Run session_init() to restore full context`
+                }
+            }]
+    }));
 }

package/dist/tools/context.d.ts

@@ -1,2 +1,25 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface SmartContextItem {
+    id: string;
+    text: string;
+    source?: string;
+    timestamp?: string;
+    pinned?: boolean;
+}
+declare function summarizeForPrune(text: string, maxLength: number): string;
+declare function scoreSmartContextItem(item: SmartContextItem, now: number): {
+    score: number;
+    signals: string[];
+};
+declare function extractPruneMemoryCandidates(text: string): Array<{
+    keyHint: string;
+    reason: string;
+    value: string;
+}>;
+export declare const __contextTestables: {
+    summarizeForPrune: typeof summarizeForPrune;
+    scoreSmartContextItem: typeof scoreSmartContextItem;
+    extractPruneMemoryCandidates: typeof extractPruneMemoryCandidates;
+};
 export declare function registerContextTools(server: McpServer): void;
+export {};

package/dist/tools/context.js

@@ -78,6 +78,121 @@ async function getBackupStats(basePath) {
     }
     return stats;
 }
+function summarizeForPrune(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    const sentences = text.match(/[^.!?\n]+[.!?]?/g) || [text];
+    const important = [];
+    const normal = [];
+    for (const sentenceRaw of sentences) {
+        const sentence = sentenceRaw.trim();
+        if (!sentence)
+            continue;
+        const lower = sentence.toLowerCase();
+        if (lower.includes('important') ||
+            lower.includes('decision') ||
+            lower.includes('todo') ||
+            lower.includes('error') ||
+            lower.includes('must') ||
+            lower.includes('action')) {
+            important.push(sentence);
+        }
+        else {
+            normal.push(sentence);
+        }
+    }
+    const compact = [];
+    for (const sentence of [...important, ...normal]) {
+        const next = compact.length > 0 ? `${compact.join(' ')} ${sentence}` : sentence;
+        if (next.length > maxLength)
+            break;
+        compact.push(sentence);
+    }
+    const summary = compact.join(' ').trim();
+    return summary || `${text.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+function scoreSmartContextItem(item, now) {
+    const text = item.text || '';
+    const lower = text.toLowerCase();
+    let score = 0;
+    const signals = [];
+    if (item.pinned) {
+        score += 1000;
+        signals.push('pinned');
+    }
+    const importantKeywords = ['error', 'bug', 'decision', 'todo', 'must', 'important', 'action', 'requirement', 'blocked'];
+    const matchedKeywords = importantKeywords.filter((kw) => lower.includes(kw));
+    if (matchedKeywords.length > 0) {
+        score += Math.min(28, matchedKeywords.length * 4);
+        signals.push(`keywords:${matchedKeywords.join(',')}`);
+    }
+    if (item.source) {
+        const sourceLower = item.source.toLowerCase();
+        if (sourceLower.includes('user')) {
+            score += 10;
+            signals.push('source:user');
+        }
+        else if (sourceLower.includes('system')) {
+            score += 8;
+            signals.push('source:system');
+        }
+    }
+    if (/([a-zA-Z]:\\|\/).+\.[a-z0-9]+/i.test(text)) {
+        score += 6;
+        signals.push('contains:path');
+    }
+    if (/\bhttps?:\/\//i.test(text)) {
+        score += 5;
+        signals.push('contains:url');
+    }
+    if (text.length > 400) {
+        score += 4;
+        signals.push('long-context');
+    }
+    else if (text.length < 24) {
+        score -= 4;
+        signals.push('very-short');
+    }
+    if (item.timestamp) {
+        const ts = Date.parse(item.timestamp);
+        if (!Number.isNaN(ts)) {
+            const ageHours = Math.max(0, (now - ts) / (1000 * 60 * 60));
+            const recency = Math.max(0, 20 - Math.floor(ageHours / 2));
+            score += recency;
+            signals.push(`recency:+${recency}`);
+        }
+    }
+    if (/(^|\s)(ok|thanks|noted|done)(\s|$)/i.test(lower)) {
+        score -= 3;
+        signals.push('low-signal-chat');
+    }
+    return { score, signals };
+}
+function extractPruneMemoryCandidates(text) {
+    const candidates = [];
+    const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+    for (const line of lines) {
+        const lower = line.toLowerCase();
+        if (lower.includes('decision:') || lower.includes('decided to')) {
+            candidates.push({ keyHint: 'decision.auto', reason: 'decision-signal', value: line });
+        }
+        if (lower.includes('todo:') || lower.includes('action:') || lower.includes('must ')) {
+            candidates.push({ keyHint: 'todo.auto', reason: 'action-signal', value: line });
+        }
+        if (lower.includes('error') || lower.includes('failed') || lower.includes('exception')) {
+            candidates.push({ keyHint: 'error.auto', reason: 'error-signal', value: line });
+        }
+        if (/\bhttps?:\/\//i.test(line)) {
+            candidates.push({ keyHint: 'reference.url', reason: 'url-signal', value: line });
+        }
+    }
+    return candidates.slice(0, 8);
+}
+export const __contextTestables = {
+    summarizeForPrune,
+    scoreSmartContextItem,
+    extractPruneMemoryCandidates
+};
 export function registerContextTools(server) {
     server.registerTool('context_status', {
         title: 'Context Status',
@@ -140,6 +255,120 @@ WHEN TO USE:
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
         };
     });
+    server.registerTool('context_prune_smart', {
+        title: 'Smart Context Prune',
+        description: `Smart context pruning with relevance scoring, optional summarization, and memory candidate extraction.
+WHEN TO USE:
+- After processing large batches of context/tool output
+- When token pressure is rising and you need to keep only high-signal context
+- To generate compact summaries before pruning noisy context`,
+        inputSchema: {
+            items: z.array(z.object({
+                id: z.string().describe('Unique context item identifier'),
+                text: z.string().describe('Context content text'),
+                source: z.string().optional().describe('Context source (user/tool/system/assistant)'),
+                timestamp: z.string().optional().describe('ISO timestamp for recency scoring'),
+                pinned: z.boolean().optional().describe('Pinned items are always kept')
+            })).describe('Context items to evaluate'),
+            mode: z.enum(['hybrid', 'aggressive', 'conservative']).optional().describe('Prune strategy mode (default: hybrid)'),
+            maxKeep: z.number().optional().describe('Maximum number of items to keep (default: 8)'),
+            summaryMaxLength: z.number().optional().describe('Maximum summary length for compressed entries (default: 240)'),
+            memoryCandidateLimit: z.number().optional().describe('Maximum extracted memory candidates (default: 8)')
+        }
+    }, async ({ items, mode = 'hybrid', maxKeep = 8, summaryMaxLength = 240, memoryCandidateLimit = 8 }) => {
+        if (items.length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            mode,
+                            totalItems: 0,
+                            keep: [],
+                            prune: [],
+                            summaries: [],
+                            memoryCandidates: []
+                        }, null, 2) }]
+            };
+        }
+        const now = Date.now();
+        const normalizedItems = items.map((item) => ({
+            id: item.id,
+            text: item.text,
+            source: item.source,
+            timestamp: item.timestamp,
+            pinned: item.pinned
+        }));
+        const scored = normalizedItems.map((item) => {
+            const { score, signals } = scoreSmartContextItem(item, now);
+            return { item, score, signals };
+        }).sort((a, b) => b.score - a.score);
+        const pinnedItems = scored.filter((entry) => entry.item.pinned);
+        const keepBaseByMode = mode === 'aggressive'
+            ? Math.max(3, Math.ceil(scored.length * 0.25))
+            : mode === 'conservative'
+                ? Math.max(5, Math.ceil(scored.length * 0.7))
+                : Math.max(4, Math.ceil(scored.length * 0.45));
+        const keepTarget = Math.min(scored.length, Math.max(pinnedItems.length, Math.min(maxKeep, keepBaseByMode)));
+        const keepSet = new Set();
+        for (const pinned of pinnedItems) {
+            keepSet.add(pinned.item.id);
+        }
+        for (const entry of scored) {
+            if (keepSet.size >= keepTarget)
+                break;
+            keepSet.add(entry.item.id);
+        }
+        const keep = scored
+            .filter((entry) => keepSet.has(entry.item.id))
+            .map((entry) => ({
+            id: entry.item.id,
+            source: entry.item.source,
+            score: entry.score,
+            pinned: !!entry.item.pinned,
+            signals: entry.signals,
+            textPreview: summarizeForPrune(entry.item.text, 180)
+        }));
+        const prunedScored = scored
+            .filter((entry) => !keepSet.has(entry.item.id));
+        const prune = prunedScored
+            .map((entry) => ({
+            id: entry.item.id,
+            source: entry.item.source,
+            score: entry.score,
+            signals: entry.signals,
+            reason: entry.score < 8 ? 'low-signal' : 'lower-priority',
+            textPreview: summarizeForPrune(entry.item.text, 120)
+        }));
+        const summaries = prunedScored
+            .filter((entry) => entry.item.text.length > summaryMaxLength)
+            .slice(0, 12)
+            .map((entry) => ({
+            id: entry.item.id,
+            source: entry.item.source,
+            originalLength: entry.item.text.length,
+            summary: summarizeForPrune(entry.item.text, summaryMaxLength)
+        }));
+        const memoryCandidates = prunedScored
+            .flatMap((entry) => extractPruneMemoryCandidates(entry.item.text))
+            .slice(0, memoryCandidateLimit);
+        const output = {
+            mode,
+            strategy: {
+                totalItems: scored.length,
+                keepTarget,
+                kept: keep.length,
+                pruned: prune.length
+            },
+            keep,
+            prune,
+            summaries,
+            memoryCandidates,
+            recommendation: prune.length > 0
+                ? 'Prune listed low-signal items and persist memoryCandidates via memory_set or memory_capture_candidates'
+                : 'No prune needed; current context is already high-signal'
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output, null, 2) }]
+        };
+    });
     server.registerTool('store_health', {
         title: 'Store Health',
         description: `Check health of the context store - file integrity, backup status, and recommendations.

package/dist/tools/context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/context.test.js

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { __contextTestables } from './context.js';
+test('summarizeForPrune respects max length and keeps key sentence', () => {
+    const text = [
+        'This is regular background sentence.',
+        'Decision: use smart prune scoring for noisy outputs.',
+        'Another long detail to fill space and trigger compression behavior.'
+    ].join(' ');
+    const summary = __contextTestables.summarizeForPrune(text, 80);
+    assert.ok(summary.length <= 80);
+    assert.ok(summary.toLowerCase().includes('decision'));
+});
+test('scoreSmartContextItem gives higher score for pinned/important content', () => {
+    const now = Date.now();
+    const high = __contextTestables.scoreSmartContextItem({
+        id: 'a',
+        text: 'Important decision: must fix error in src/tools/context.ts',
+        source: 'user',
+        timestamp: new Date(now).toISOString(),
+        pinned: true
+    }, now);
+    const low = __contextTestables.scoreSmartContextItem({
+        id: 'b',
+        text: 'ok thanks',
+        source: 'assistant',
+        timestamp: new Date(now - 1000 * 60 * 60 * 48).toISOString()
+    }, now);
+    assert.ok(high.score > low.score);
+    assert.ok(high.signals.includes('pinned'));
+});
+test('extractPruneMemoryCandidates extracts decision/todo/error/url signals', () => {
+    const candidates = __contextTestables.extractPruneMemoryCandidates([
+        'Decision: Use hybrid mode for prune.',
+        'TODO: add tests for memory capture.',
+        'Error: build failed in CI.',
+        'Reference: https://example.com/docs'
+    ].join('\n'));
+    const reasons = candidates.map((c) => c.reason);
+    assert.ok(reasons.includes('decision-signal'));
+    assert.ok(reasons.includes('action-signal'));
+    assert.ok(reasons.includes('error-signal'));
+    assert.ok(reasons.includes('url-signal'));
+});

package/dist/tools/memory.d.ts

@@ -1,3 +1,17 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function cleanupExpiredMemories(): Promise<number>;
+interface MemoryCandidate {
+    key: string;
+    value: string;
+    tags: string[];
+    confidence: number;
+    reason: string;
+}
+declare function slugify(value: string): string;
+declare function buildMemoryCandidates(text: string, source: string, baseTags: string[]): MemoryCandidate[];
+export declare const __memoryTestables: {
+    slugify: typeof slugify;
+    buildMemoryCandidates: typeof buildMemoryCandidates;
+};
 export declare function registerMemoryTools(server: McpServer): void;
+export {};

package/dist/tools/memory.js

@@ -79,6 +79,80 @@ function deepMerge(target, source) {
     }
     return result;
 }
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 36) || 'item';
+}
+function buildMemoryCandidates(text, source, baseTags) {
+    const candidates = [];
+    const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+    for (const line of lines) {
+        const lower = line.toLowerCase();
+        if (lower.includes('decision:') || lower.includes('decided to')) {
+            const subject = line.replace(/^.*?(decision:\s*|decided to\s*)/i, '').trim() || line;
+            candidates.push({
+                key: `decision.${slugify(subject)}`,
+                value: line,
+                tags: [...baseTags, source, 'decision'],
+                confidence: 0.92,
+                reason: 'decision signal'
+            });
+        }
+        if (lower.includes('todo:') || lower.includes('action:') || lower.includes('must ')) {
+            const subject = line.replace(/^.*?(todo:\s*|action:\s*|must\s*)/i, '').trim() || line;
+            candidates.push({
+                key: `todo.${slugify(subject)}`,
+                value: line,
+                tags: [...baseTags, source, 'todo'],
+                confidence: 0.86,
+                reason: 'actionable item signal'
+            });
+        }
+        if (lower.includes('error') || lower.includes('failed') || lower.includes('exception')) {
+            candidates.push({
+                key: `error.${slugify(line)}`,
+                value: line,
+                tags: [...baseTags, source, 'error'],
+                confidence: 0.9,
+                reason: 'error signal'
+            });
+        }
+        if (/\bhttps?:\/\//i.test(line)) {
+            candidates.push({
+                key: `reference.url.${slugify(line)}`,
+                value: line,
+                tags: [...baseTags, source, 'reference'],
+                confidence: 0.8,
+                reason: 'url reference signal'
+            });
+        }
+        const configMatch = line.match(/\b([A-Z][A-Z0-9_]{2,})\s*[=:]\s*(.+)$/);
+        if (configMatch) {
+            candidates.push({
+                key: `config.${slugify(configMatch[1])}`,
+                value: line,
+                tags: [...baseTags, source, 'config'],
+                confidence: 0.84,
+                reason: 'config/env signal'
+            });
+        }
+    }
+    const dedup = new Map();
+    for (const candidate of candidates) {
+        const existing = dedup.get(candidate.key);
+        if (!existing || candidate.confidence > existing.confidence) {
+            dedup.set(candidate.key, candidate);
+        }
+    }
+    return Array.from(dedup.values());
+}
+export const __memoryTestables = {
+    slugify,
+    buildMemoryCandidates
+};
 export function registerMemoryTools(server) {
     server.registerTool('memory_set', {
         title: 'Memory Set',
@@ -197,6 +271,62 @@ WHEN TO USE:
                 }]
         };
     });
+    server.registerTool('memory_capture_candidates', {
+        title: 'Memory Capture Candidates',
+        description: `Extract and optionally persist important memory candidates from raw text.
+WHEN TO USE:
+- After long tool outputs to store decisions/errors/todos automatically
+- Before pruning context to avoid losing important details
+- For proactive memory capture workflows`,
+        inputSchema: {
+            text: z.string().describe('Raw text to analyze for memory candidates'),
+            source: z.string().optional().describe('Source label for extracted candidates (default: llm)'),
+            autoTags: z.array(z.string()).optional().describe('Additional tags to include on all candidates'),
+            maxCandidates: z.number().optional().describe('Maximum number of candidates to return/store (default: 10)'),
+            dryRun: z.boolean().optional().describe('If true, only preview candidates without persisting')
+        }
+    }, async ({ text, source = 'llm', autoTags = [], maxCandidates = 10, dryRun = true }) => {
+        const candidates = buildMemoryCandidates(text, source, autoTags).slice(0, maxCandidates);
+        if (candidates.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No important memory candidates detected' }]
+            };
+        }
+        if (dryRun) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ dryRun: true, count: candidates.length, candidates }, null, 2)
+                    }]
+            };
+        }
+        const memStore = await getMemoryStore();
+        const now = new Date().toISOString();
+        const savedKeys = [];
+        for (const candidate of candidates) {
+            const existing = memStore.entries[candidate.key];
+            memStore.entries[candidate.key] = {
+                key: candidate.key,
+                value: candidate.value,
+                tags: candidate.tags,
+                createdAt: existing?.createdAt || now,
+                updatedAt: now
+            };
+            savedKeys.push(candidate.key);
+        }
+        await saveMemoryStore(memStore);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        dryRun: false,
+                        savedCount: savedKeys.length,
+                        savedKeys,
+                        candidates
+                    }, null, 2)
+                }]
+        };
+    });
     server.registerTool('memory_delete', {
         title: 'Memory Delete',
         description: 'Delete a memory entry by key.',

package/dist/tools/memory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/memory.test.js

@@ -0,0 +1,27 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { __memoryTestables } from './memory.js';
+test('slugify normalizes and trims tokens safely', () => {
+    const result = __memoryTestables.slugify('  Decision: Add New Feature!  ');
+    assert.equal(result, 'decision-add-new-feature');
+});
+test('buildMemoryCandidates extracts high-signal candidates with tags', () => {
+    const text = [
+        'Decision: use memory capture as default.',
+        'TODO: improve context pruning.',
+        'ERROR: request failed with timeout.',
+        'MCP_CONTEXT_PATH=/tmp/context',
+        'See docs: https://example.dev/mcp'
+    ].join('\n');
+    const candidates = __memoryTestables.buildMemoryCandidates(text, 'llm', ['test']);
+    const keys = candidates.map((item) => item.key);
+    assert.ok(keys.some((key) => key.startsWith('decision.')));
+    assert.ok(keys.some((key) => key.startsWith('todo.')));
+    assert.ok(keys.some((key) => key.startsWith('error.')));
+    assert.ok(keys.some((key) => key.startsWith('config.')));
+    assert.ok(keys.some((key) => key.startsWith('reference.url.')));
+    for (const candidate of candidates) {
+        assert.ok(candidate.tags.includes('test'));
+        assert.ok(candidate.tags.includes('llm'));
+    }
+});

package/dist/tools/session.js

@@ -311,9 +311,10 @@ WHEN TO USE: Call this ONCE at the START of every session/conversation.
 Returns: latest checkpoint, tracker status (todos/decisions), all memories, and auto-detected project info.
 This replaces calling checkpoint_load(), tracker_status(), and memory_list() separately.`,
         inputSchema: {
-            cwd: z.string().optional().describe('Current working directory for project detection (defaults to process.cwd())')
+            cwd: z.string().optional().describe('Current working directory for project detection (defaults to process.cwd())'),
+            verbose: z.boolean().optional().describe('Include full checkpoint/tracker/memory payload (default: false)')
         }
-    }, async ({ cwd }) => {
+    }, async ({ cwd, verbose = false }) => {
         const workingDir = cwd || process.cwd();
         // Cleanup expired memories first
         const cleanedUp = await cleanupExpiredMemories();
@@ -345,13 +346,37 @@ This replaces calling checkpoint_load(), tracker_status(), and memory_list() sep
             memoriesCount: Array.isArray(memories) ? memories.length : 0,
             cleanedUpExpiredMemories: cleanedUp
         };
+        const output = verbose
+            ? { summary, ...state }
+            : {
+                summary,
+                checkpoint: checkpoint
+                    ? {
+                        id: checkpoint.id,
+                        name: checkpoint.name,
+                        createdAt: checkpoint.createdAt,
+                        files: checkpoint.files || []
+                    }
+                    : null,
+                tracker: {
+                    projectName: tracker.projectName,
+                    pendingTodos: tracker.pendingTodos || [],
+                    recentChanges: tracker.recentChanges || [],
+                    decisions: tracker.decisions || []
+                },
+                memories: Array.isArray(memories)
+                    ? memories.map((m) => ({
+                        key: m.key,
+                        tags: m.tags || [],
+                        updatedAt: m.updatedAt
+                    }))
+                    : [],
+                project
+            };
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify({
-                        summary,
-                        ...state
-                    }, null, 2)
+                    text: JSON.stringify(output, null, 2)
                 }]
         };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd412id/mcp-context-manager",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "MCP tools for context management - summarizer, memory store, project tracker, checkpoints, and smart file loader",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +15,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
+    "test": "npm run build && node --test dist/**/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [