smart-context-mcp 0.8.0 → 1.0.0

package/README.md

@@ -1,16 +1,76 @@
 # smart-context-mcp
 
-`smart-context-mcp` is an MCP server that reduces agent token usage and improves response quality with compact file summaries, ranked code search, and curated context.
+[![npm version](https://badge.fury.io/js/smart-context-mcp.svg)](https://www.npmjs.com/package/smart-context-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-It exposes:
+**MCP server that reduces AI agent token usage by 90% and improves response quality.**
 
-- `smart_read`: compact file summaries instead of full-file dumps
+Instead of reading entire files and repeating context, this MCP provides 7 smart tools that compress, rank, and maintain context efficiently.
+
+## Why use this?
+
+**Problem:** AI agents waste tokens reading full files, repeating context, and searching inefficiently.
+
+**Solution:** This MCP reduces token usage by **~90%** in real projects while improving response quality.
+
+**Real metrics from production use:**
+- 14.5M tokens → 1.6M tokens (89.87% reduction)
+- 3,666 successful calls across 7 tools
+- Compression ratios: 3x to 46x depending on tool
+
+## Quick Start (2 commands)
+
+```bash
+npm install smart-context-mcp
+npx smart-context-init --target .
+```
+
+That's it. Restart your AI client (Cursor, Codex, Claude Desktop) and the tools are available.
+
+## What you get
+
+Seven focused tools that work automatically:
+
+- `smart_read`: compact file summaries instead of full file dumps (3x compression)
 - `smart_read_batch`: read multiple files in one call — reduces round-trip latency
-- `smart_search`: ripgrep-first code search with grouped, ranked results and intent-aware ranking
-- `smart_context`: one-call context planner that combines search + read + graph expansion
-- `smart_shell`: safe diagnostic shell execution with a restricted allowlist
+- `smart_search`: ripgrep-first code search with intent-aware ranking (21x compression)
+- `smart_context`: one-call context planner — search + read + graph expansion
+- `smart_summary`: maintain compressed conversation state across sessions (46x compression)
+- `smart_shell`: safe diagnostic shell execution with restricted commands (18x compression)
 - `build_index`: lightweight symbol index for faster lookups and smarter ranking
 
+**Strongest in:** Modern web/backend codebases (JS/TS, React, Next.js, Node.js, Python, Go, Rust), infra repos (Terraform, Docker, YAML)
+
+## Example: Before vs After
+
+### Without this MCP
+```
+Agent: Let me read auth.js...
+[Reads 4,000 tokens of full file]
+
+Agent: Let me search for "jwt validation"...
+[Returns 10,000 tokens of grep results]
+
+Agent: [Next turn] What were we doing?
+[Repeats 5,000 tokens of context]
+
+Total: ~19,000 tokens
+```
+
+### With this MCP
+```
+Agent: Let me use smart_read on auth.js...
+[Returns 500 tokens of signatures]
+
+Agent: Let me use smart_search for "jwt validation"...
+[Returns 400 tokens of ranked snippets]
+
+Agent: [Next turn] Let me get the context...
+[smart_summary returns 100 tokens]
+
+Total: ~1,000 tokens (95% reduction)
+```
+
 ## Quick start
 
 ```bash
@@ -109,7 +169,7 @@ After installing and running `smart-context-init`, each client picks up the serv
 
 ### Cursor
 
-Open the project in Cursor. The MCP server starts automatically. Enable it in **Cursor Settings > MCP** if needed. All six tools are available in Agent mode.
+Open the project in Cursor. The MCP server starts automatically. Enable it in **Cursor Settings > MCP** if needed. All seven tools are available in Agent mode.
 
 ### Codex CLI
 
@@ -355,6 +415,92 @@ When using diff mode, the response includes a `diffSummary`:
 }
 ```
 
+### `smart_summary`
+
+Maintain compressed conversation state across sessions. Solves the context-loss problem when resuming work after hours or days.
+
+**Actions:**
+
+| Action | Purpose | Returns |
+|--------|---------|---------|
+| `get` | Retrieve current or specified session | Resume summary (≤500 tokens) + compression metadata |
+| `update` | Create or replace session | New session with compressed state |
+| `append` | Add to existing session | Merged session state |
+| `reset` | Clear session | Confirmation |
+| `list_sessions` | Show all available sessions | Array of sessions with metadata |
+
+**Parameters:**
+- `action` (required) — one of the actions above
+- `sessionId` (optional) — session identifier; auto-generated from `goal` if omitted
+- `update` (required for update/append) — object with:
+  - `goal`: primary objective
+  - `status`: current state (`planning` | `in_progress` | `blocked` | `completed`)
+  - `pinnedContext`: critical context that should survive compression when possible
+  - `unresolvedQuestions`: open questions that matter for the next turn
+  - `currentFocus`: current work area in one short phrase
+  - `whyBlocked`: blocker summary when status is `blocked`
+  - `completed`: array of completed steps
+  - `decisions`: array of key decisions with rationale
+  - `blockers`: array of current blockers
+  - `nextStep`: immediate next action
+  - `touchedFiles`: array of modified files
+- `maxTokens` (optional, default 500) — hard cap on summary size
+
+`update` replaces the stored session state for that `sessionId`, so omitted fields are cleared. Use `append` when you want to keep existing state and add progress incrementally.
+
+**Storage:**
+- Sessions persist in `.devctx/sessions/<sessionId>.json`
+- Active session tracked in `.devctx/sessions/active.json`
+- 30-day retention for inactive sessions
+- No expiration for active sessions
+
+**Resume summary fields:**
+- `status` and `nextStep` are preserved with highest priority
+- `pinnedContext` and `unresolvedQuestions` preserve critical context and open questions
+- `currentFocus` and `whyBlocked` are included when relevant
+- `recentCompleted`, `keyDecisions`, and `hotFiles` are derived from the persisted state
+- `completedCount`, `decisionsCount`, and `touchedFilesCount` preserve activity scale cheaply
+- Empty fields are omitted to save tokens
+
+**Response metadata:**
+- `schemaVersion`: persisted session schema version
+- `truncated`: whether the resume summary had to be compressed
+- `compressionLevel`: `none` | `trimmed` | `reduced` | `status_only`
+- `omitted`: fields dropped from the resume summary to fit the token budget
+
+**Compression strategy:**
+- Keeps the persisted session state intact and compresses only the resume summary
+- Prioritizes `nextStep`, `status`, and active blockers over history
+- Deduplicates repeated completed steps, decisions, and touched files
+- Uses token-aware reduction until the summary fits `maxTokens`
+
+**Example workflow:**
+
+```javascript
+// Start of work session
+smart_summary({ action: "get" })
+// → retrieves last active session or returns "not found"
+
+// After implementing auth middleware
+smart_summary({ 
+  action: "append",
+  update: {
+    completed: ["auth middleware"],
+    decisions: ["JWT with 1h expiry, refresh tokens in Redis"],
+    touchedFiles: ["src/middleware/auth.js"],
+    nextStep: "add role-based access control"
+  }
+})
+
+// Monday after weekend - resume work
+smart_summary({ action: "get" })
+// → full context restored, continue from nextStep
+
+// List all sessions
+smart_summary({ action: "list_sessions" })
+// → see all available sessions, pick one to resume
+```
+
 ### `build_index`
 
 - Builds a lightweight symbol index for the project (functions, classes, methods, types, etc.)
@@ -403,8 +549,9 @@ Metrics include: P@5, P@10, Recall, wrong-file rate, retrieval honesty, follow-u
 ## Notes
 
 - `@vscode/ripgrep` provides a bundled `rg` binary, so a system install is not required.
-- Metrics are written under `.devctx/metrics.jsonl` in the package root.
-- Symbol index stored in `.devctx/index.json` when `build_index` is used.
+- Metrics are written to `<projectRoot>/.devctx/metrics.jsonl` (override with `DEVCTX_METRICS_FILE` env var).
+- Symbol index stored in `<projectRoot>/.devctx/index.json` when `build_index` is used.
+- Conversation sessions stored in `<projectRoot>/.devctx/sessions/` when `smart_summary` is used.
 - This package is a navigation and diagnostics layer, not a full semantic code intelligence system.
 
 ## Repository
@@ -412,3 +559,13 @@ Metrics include: P@5, P@10, Recall, wrong-file rate, retrieval honesty, follow-u
 Source repository and full project documentation:
 
 - https://github.com/Arrayo/devctx-mcp-mvp
+
+## Author
+
+**Francisco Caballero Portero**  
+Email: fcp1978@hotmail.com  
+GitHub: [@Arrayo](https://github.com/Arrayo)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "MCP server that reduces agent token usage and improves response quality with compact file summaries, ranked code search, and curated context.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/scripts/init-clients.js

@@ -20,7 +20,7 @@ const parseArgs = (argv) => {
   const options = {
     target: process.cwd(),
     name: 'devctx',
-    command: 'node',
+    command: process.execPath,
     args: null,
     clients: [...supportedClients],
     dryRun: false,

package/scripts/report-metrics.js

@@ -90,6 +90,16 @@ const readEntries = (filePath) => {
   return { entries, invalidLines };
 };
 
+const getCompressedTokens = (entry) => Number(entry.compressedTokens ?? entry.finalTokens ?? 0);
+
+const getSavedTokens = (entry, compressedTokens) => {
+  if (entry.savedTokens !== undefined) {
+    return Number(entry.savedTokens ?? 0);
+  }
+
+  return Math.max(0, Number(entry.rawTokens ?? 0) - compressedTokens);
+};
+
 const aggregate = (entries) => {
   const byTool = new Map();
   let rawTokens = 0;
@@ -98,6 +108,8 @@ const aggregate = (entries) => {
 
   for (const entry of entries) {
     const tool = entry.tool ?? 'unknown';
+    const compressedTokensForEntry = getCompressedTokens(entry);
+    const savedTokensForEntry = getSavedTokens(entry, compressedTokensForEntry);
     const current = byTool.get(tool) ?? {
       tool,
       count: 0,
@@ -108,13 +120,13 @@ const aggregate = (entries) => {
 
     current.count += 1;
     current.rawTokens += Number(entry.rawTokens ?? 0);
-    current.compressedTokens += Number(entry.compressedTokens ?? 0);
-    current.savedTokens += Number(entry.savedTokens ?? 0);
+    current.compressedTokens += compressedTokensForEntry;
+    current.savedTokens += savedTokensForEntry;
     byTool.set(tool, current);
 
     rawTokens += Number(entry.rawTokens ?? 0);
-    compressedTokens += Number(entry.compressedTokens ?? 0);
-    savedTokens += Number(entry.savedTokens ?? 0);
+    compressedTokens += compressedTokensForEntry;
+    savedTokens += savedTokensForEntry;
   }
 
   const tools = [...byTool.values()]

package/src/server.js

@@ -8,6 +8,7 @@ import { smartSearch } from './tools/smart-search.js';
 import { smartContext } from './tools/smart-context.js';
 import { smartReadBatch } from './tools/smart-read-batch.js';
 import { smartShell } from './tools/smart-shell.js';
+import { smartSummary } from './tools/smart-summary.js';
 import { projectRoot, projectRootSource } from './utils/paths.js';
 
 const require = createRequire(import.meta.url);
@@ -120,6 +121,31 @@ export const createDevctxServer = () => {
     },
   );
 
+  server.tool(
+    'smart_summary',
+    'Maintain compressed conversation state across turns. Actions: get (retrieve current/last session), update (create or replace a session; omitted fields are cleared), append (add to existing session), reset (clear session), list_sessions (show all sessions). Sessions persist in .devctx/sessions/ with 30-day retention. Auto-generates sessionId from goal if not provided. Returns a resume summary capped at maxTokens (default 500) plus compression metadata (`truncated`, `compressionLevel`, `omitted`) and `schemaVersion`. Tracks: goal, status, pinned context, unresolved questions, current focus, blockers, next step, completed steps, key decisions, and touched files.',
+    {
+      action: z.enum(['get', 'update', 'append', 'reset', 'list_sessions']),
+      sessionId: z.string().optional(),
+      update: z.object({
+        goal: z.string().optional(),
+        status: z.enum(['planning', 'in_progress', 'blocked', 'completed']).optional(),
+        pinnedContext: z.array(z.string()).optional(),
+        unresolvedQuestions: z.array(z.string()).optional(),
+        currentFocus: z.string().optional(),
+        whyBlocked: z.string().optional(),
+        completed: z.array(z.string()).optional(),
+        decisions: z.array(z.string()).optional(),
+        blockers: z.array(z.string()).optional(),
+        nextStep: z.string().optional(),
+        touchedFiles: z.array(z.string()).optional(),
+      }).optional(),
+      maxTokens: z.number().int().min(100).max(2000).optional(),
+    },
+    async ({ action, sessionId, update, maxTokens }) =>
+      asTextResult(await smartSummary({ action, sessionId, update, maxTokens })),
+  );
+
   return server;
 };
 

package/src/tools/smart-summary.js

@@ -0,0 +1,585 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectRoot } from '../utils/runtime-config.js';
+import { countTokens } from '../tokenCounter.js';
+import { persistMetrics } from '../metrics.js';
+
+const MAX_SESSION_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_TOKENS = 500;
+const VALID_STATUSES = new Set(['planning', 'in_progress', 'blocked', 'completed']);
+const DEFAULT_STATUS = 'in_progress';
+const SESSION_SCHEMA_VERSION = 2;
+
+const getSessionsDir = () => path.join(projectRoot, '.devctx', 'sessions');
+const getActiveSessionFile = () => path.join(getSessionsDir(), 'active.json');
+
+const ensureSessionsDir = () => {
+  const sessionsDir = getSessionsDir();
+  if (!fs.existsSync(sessionsDir)) {
+    fs.mkdirSync(sessionsDir, { recursive: true });
+  }
+};
+
+const generateSessionId = (goal) => {
+  const date = new Date().toISOString().split('T')[0];
+  const slug = goal
+    ? goal.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 30)
+    : 'session';
+  return `${date}-${slug}`;
+};
+
+const getSessionPath = (sessionId) => path.join(getSessionsDir(), `${sessionId}.json`);
+
+const loadSession = (sessionId) => {
+  const sessionPath = getSessionPath(sessionId);
+  if (!fs.existsSync(sessionPath)) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+    return data;
+  } catch {
+    return null;
+  }
+};
+
+const saveSession = (sessionId, data) => {
+  ensureSessionsDir();
+  const sessionPath = getSessionPath(sessionId);
+  const sessionData = {
+    ...data,
+    schemaVersion: SESSION_SCHEMA_VERSION,
+    sessionId,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2), 'utf8');
+  
+  const activeSessionFile = getActiveSessionFile();
+  fs.writeFileSync(activeSessionFile, JSON.stringify({ sessionId, updatedAt: sessionData.updatedAt }, null, 2), 'utf8');
+  
+  return sessionData;
+};
+
+const getActiveSession = () => {
+  const activeSessionFile = getActiveSessionFile();
+  if (!fs.existsSync(activeSessionFile)) {
+    return null;
+  }
+  try {
+    const { sessionId } = JSON.parse(fs.readFileSync(activeSessionFile, 'utf8'));
+    const activeSession = loadSession(sessionId);
+    if (!activeSession) {
+      fs.unlinkSync(activeSessionFile);
+      return null;
+    }
+    return activeSession;
+  } catch {
+    try {
+      fs.unlinkSync(activeSessionFile);
+    } catch {}
+    return null;
+  }
+};
+
+const cleanupStaleSessions = () => {
+  ensureSessionsDir();
+  const sessionsDir = getSessionsDir();
+  const files = fs.readdirSync(sessionsDir).filter(f => f.endsWith('.json') && f !== 'active.json');
+  const now = Date.now();
+  let cleaned = 0;
+  
+  const activeSession = getActiveSession();
+  const activeSessionId = activeSession?.sessionId;
+  
+  for (const file of files) {
+    const sessionPath = path.join(sessionsDir, file);
+    try {
+      const data = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+      
+      if (data.sessionId === activeSessionId) {
+        continue;
+      }
+      
+      const age = now - new Date(data.updatedAt).getTime();
+      if (age > MAX_SESSION_AGE_MS) {
+        fs.unlinkSync(sessionPath);
+        cleaned += 1;
+      }
+    } catch {
+      fs.unlinkSync(sessionPath);
+      cleaned += 1;
+    }
+  }
+  
+  return cleaned;
+};
+
+const listSessions = () => {
+  ensureSessionsDir();
+  cleanupStaleSessions();
+  
+  const sessionsDir = getSessionsDir();
+  const files = fs.readdirSync(sessionsDir).filter(f => f.endsWith('.json') && f !== 'active.json');
+  const now = Date.now();
+  
+  return files
+    .map(file => {
+      const sessionPath = path.join(sessionsDir, file);
+      try {
+        const data = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+        const age = now - new Date(data.updatedAt).getTime();
+        return {
+          sessionId: data.sessionId,
+          goal: data.goal,
+          status: data.status,
+          updatedAt: data.updatedAt,
+          ageMs: age,
+          isStale: age > MAX_SESSION_AGE_MS,
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.updatedAt) - new Date(a.updatedAt));
+};
+
+const truncateString = (str, maxLength) => {
+  if (!str || str.length <= maxLength) return str;
+  if (maxLength <= 3) return '';
+  return str.slice(0, maxLength - 3) + '...';
+};
+
+const normalizeStatus = (status, fallback = DEFAULT_STATUS) =>
+  VALID_STATUSES.has(status) ? status : fallback;
+
+const isMeaningfulString = (value) => typeof value === 'string' && value.trim().length > 0;
+
+const compactFilePath = (filePath) => {
+  if (!isMeaningfulString(filePath)) {
+    return filePath;
+  }
+
+  const normalized = filePath.replace(/\\/g, '/');
+  const parts = normalized.split('/').filter(Boolean);
+  if (parts.length <= 3 && normalized.length <= 60) {
+    return normalized;
+  }
+
+  const tail = parts.slice(-3).join('/');
+  return normalized.length <= tail.length ? normalized : `.../${tail}`;
+};
+
+const validateUpdateInput = (update) => {
+  if (!update || typeof update !== 'object') {
+    throw new Error('update parameter is required for update/append actions');
+  }
+
+  if (update.status !== undefined && !VALID_STATUSES.has(update.status)) {
+    throw new Error(`Invalid status: ${update.status}. Valid statuses: planning, in_progress, blocked, completed`);
+  }
+};
+
+const mergeUniqueStrings = (...lists) => {
+  const seen = new Set();
+  const result = [];
+
+  for (const list of lists) {
+    for (const item of list || []) {
+      if (!isMeaningfulString(item) || seen.has(item)) {
+        continue;
+      }
+      seen.add(item);
+      result.push(item);
+    }
+  }
+
+  return result;
+};
+
+const uniqueTail = (items, limit) => mergeUniqueStrings(items || []).slice(-limit);
+const uniqueHead = (items, limit) => mergeUniqueStrings(items || []).slice(0, limit);
+
+const buildSummaryMetrics = (rawTokens, finalTokens) => ({
+  rawTokens,
+  finalTokens,
+  compressedTokens: finalTokens,
+  savedTokens: Math.max(0, rawTokens - finalTokens),
+});
+
+const pruneEmptyFields = (value) =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, item]) => {
+      if (item === undefined || item === null || item === '') {
+        return false;
+      }
+      if (Array.isArray(item) && item.length === 0) {
+        return false;
+      }
+      return true;
+    }),
+  );
+
+const buildResumeSummary = (data) => {
+  const status = normalizeStatus(data.status);
+  const whyBlocked = status === 'blocked'
+    ? (isMeaningfulString(data.whyBlocked) ? data.whyBlocked : (data.blockers || []).find(isMeaningfulString))
+    : undefined;
+  const completed = mergeUniqueStrings(data.completed);
+  const decisions = mergeUniqueStrings(data.decisions);
+  const touchedFiles = mergeUniqueStrings(data.touchedFiles);
+
+  return pruneEmptyFields({
+    status,
+    nextStep: isMeaningfulString(data.nextStep) ? data.nextStep : undefined,
+    pinnedContext: uniqueHead(data.pinnedContext, 3),
+    unresolvedQuestions: uniqueHead(data.unresolvedQuestions, 3),
+    currentFocus: isMeaningfulString(data.currentFocus) ? data.currentFocus : undefined,
+    whyBlocked,
+    goal: isMeaningfulString(data.goal) ? data.goal : undefined,
+    recentCompleted: uniqueTail(completed, 3),
+    keyDecisions: uniqueTail(decisions, 2),
+    hotFiles: uniqueTail(touchedFiles.map(compactFilePath), 5),
+    completedCount: data.completedCount ?? completed.length,
+    decisionsCount: data.decisionsCount ?? decisions.length,
+    touchedFilesCount: data.touchedFilesCount ?? touchedFiles.length,
+  });
+};
+
+const compressSummary = (data, maxTokens) => {
+  const baseSummary = buildResumeSummary(data);
+  let compressed = baseSummary;
+  let summary = JSON.stringify(compressed, null, 2);
+  let tokens = countTokens(summary);
+
+  if (tokens <= maxTokens) {
+    return { compressed, tokens, truncated: false, omitted: [], compressionLevel: 'none' };
+  }
+
+  const recomputeTokens = () => {
+    compressed = pruneEmptyFields(compressed);
+    summary = JSON.stringify(compressed, null, 2);
+    tokens = countTokens(summary);
+  };
+
+  const shrinkScalarField = (field, { removable = true } = {}) => {
+    const value = compressed[field];
+    if (!isMeaningfulString(value)) {
+      return false;
+    }
+
+    if (value.length <= 12) {
+      if (!removable) {
+        return false;
+      }
+      delete compressed[field];
+      return true;
+    }
+
+    const next = truncateString(value, Math.max(4, Math.floor(value.length * 0.6)));
+    if (!next || next === value) {
+      if (!removable) {
+        return false;
+      }
+      delete compressed[field];
+      return true;
+    }
+
+    compressed[field] = next;
+    return true;
+  };
+
+  const shrinkArrayField = (field) => {
+    const value = compressed[field];
+    if (!Array.isArray(value) || value.length === 0) {
+      return false;
+    }
+
+    if (value.length > 1) {
+      compressed[field] = value.slice(-1);
+      return true;
+    }
+
+    const [item] = value;
+    if (!isMeaningfulString(item)) {
+      delete compressed[field];
+      return true;
+    }
+
+    if (item.length <= 12) {
+      delete compressed[field];
+      return true;
+    }
+
+    compressed[field] = [truncateString(item, Math.max(4, Math.floor(item.length * 0.6)))];
+    return true;
+  };
+
+  const reductionSteps = [
+    () => shrinkArrayField('recentCompleted'),
+    () => shrinkArrayField('keyDecisions'),
+    () => shrinkArrayField('hotFiles'),
+    () => shrinkArrayField('unresolvedQuestions'),
+    () => shrinkScalarField('goal'),
+    () => shrinkScalarField('currentFocus'),
+    () => shrinkScalarField('whyBlocked'),
+    () => shrinkArrayField('pinnedContext'),
+    () => shrinkScalarField('nextStep', { removable: false }),
+  ];
+
+  let madeProgress = true;
+
+  while (tokens > maxTokens && madeProgress) {
+    madeProgress = false;
+
+    for (const reduce of reductionSteps) {
+      if (!reduce()) {
+        continue;
+      }
+
+      recomputeTokens();
+      madeProgress = true;
+
+      if (tokens <= maxTokens) {
+        break;
+      }
+    }
+  }
+
+  if (tokens > maxTokens && isMeaningfulString(compressed.nextStep)) {
+    while (tokens > maxTokens && shrinkScalarField('nextStep')) {
+      recomputeTokens();
+    }
+  }
+
+  if (tokens > maxTokens) {
+    compressed = pruneEmptyFields({
+      status: normalizeStatus(data.status),
+      nextStep: isMeaningfulString(data.nextStep) ? data.nextStep : undefined,
+      pinnedContext: uniqueHead(data.pinnedContext, 1),
+      completedCount: data.completedCount ?? mergeUniqueStrings(data.completed).length,
+      decisionsCount: data.decisionsCount ?? mergeUniqueStrings(data.decisions).length,
+      touchedFilesCount: data.touchedFilesCount ?? mergeUniqueStrings(data.touchedFiles).length,
+    });
+    recomputeTokens();
+
+    while (tokens > maxTokens && isMeaningfulString(compressed.nextStep) && shrinkScalarField('nextStep')) {
+      recomputeTokens();
+    }
+  }
+
+  if (tokens > maxTokens) {
+    compressed = { status: normalizeStatus(data.status) };
+    recomputeTokens();
+  }
+
+  const omitted = Object.keys(baseSummary).filter((key) => !(key in compressed));
+  const compressionLevel = Object.keys(compressed).length === 1 && compressed.status
+    ? 'status_only'
+    : omitted.length > 0
+      ? 'reduced'
+      : 'trimmed';
+
+  return { compressed, tokens, truncated: true, omitted, compressionLevel };
+};
+
+export const smartSummary = async ({ action, sessionId, update, maxTokens = DEFAULT_MAX_TOKENS }) => {
+  const startTime = Date.now();
+  
+  ensureSessionsDir();
+  
+  if (action === 'list_sessions') {
+    const sessions = listSessions();
+    const activeSession = getActiveSession();
+    
+    return {
+      action: 'list_sessions',
+      sessions,
+      activeSessionId: activeSession?.sessionId || null,
+      totalSessions: sessions.length,
+      staleSessions: sessions.filter(s => s.isStale).length,
+    };
+  }
+  
+  if (action === 'get') {
+    const targetSessionId = sessionId || getActiveSession()?.sessionId;
+    
+    if (!targetSessionId) {
+      return {
+        action: 'get',
+        sessionId: null,
+        found: false,
+        message: 'No active session found. Use action=update to create one.',
+      };
+    }
+    
+    const session = loadSession(targetSessionId);
+    
+    if (!session) {
+      return {
+        action: 'get',
+        sessionId: targetSessionId,
+        found: false,
+        message: 'Session not found.',
+      };
+    }
+    
+    const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(session, maxTokens);
+    
+    const rawTokens = countTokens(JSON.stringify(session));
+    const summaryMetrics = buildSummaryMetrics(rawTokens, tokens);
+
+    persistMetrics({
+      tool: 'smart_summary',
+      action: 'get',
+      sessionId: targetSessionId,
+      ...summaryMetrics,
+      latencyMs: Date.now() - startTime,
+    });
+    
+    return {
+      action: 'get',
+      sessionId: targetSessionId,
+      found: true,
+      summary: compressed,
+      tokens,
+      truncated,
+      omitted,
+      compressionLevel,
+      schemaVersion: session.schemaVersion ?? 1,
+      updatedAt: session.updatedAt,
+    };
+  }
+  
+  if (action === 'reset') {
+    const targetSessionId = sessionId || getActiveSession()?.sessionId;
+    
+    if (!targetSessionId) {
+      return {
+        action: 'reset',
+        sessionId: null,
+        message: 'No session to reset.',
+      };
+    }
+    
+    const activeSession = getActiveSession();
+    const isActiveSession = activeSession?.sessionId === targetSessionId;
+    
+    const sessionPath = getSessionPath(targetSessionId);
+    if (fs.existsSync(sessionPath)) {
+      fs.unlinkSync(sessionPath);
+    }
+    
+    if (isActiveSession) {
+      const activeSessionFile = getActiveSessionFile();
+      if (fs.existsSync(activeSessionFile)) {
+        fs.unlinkSync(activeSessionFile);
+      }
+    }
+    
+    return {
+      action: 'reset',
+      sessionId: targetSessionId,
+      message: 'Session cleared.',
+    };
+  }
+  
+  if (action === 'update' || action === 'append') {
+    validateUpdateInput(update);
+    
+    let targetSessionId = sessionId;
+    let existingData = {};
+    
+    if (!targetSessionId || targetSessionId === 'new') {
+      if (action === 'append') {
+        const activeSession = getActiveSession();
+        if (activeSession) {
+          targetSessionId = activeSession.sessionId;
+          existingData = activeSession;
+        } else {
+          targetSessionId = generateSessionId(update.goal);
+        }
+      } else {
+        targetSessionId = generateSessionId(update.goal);
+      }
+    } else {
+      const existing = loadSession(targetSessionId);
+      if (existing) {
+        existingData = existing;
+      }
+    }
+    
+    const resolvedStatus = normalizeStatus(update.status, normalizeStatus(existingData.status));
+    const completed = action === 'append'
+      ? mergeUniqueStrings(existingData.completed, update.completed)
+      : mergeUniqueStrings(update.completed);
+    const decisions = action === 'append'
+      ? mergeUniqueStrings(existingData.decisions, update.decisions)
+      : mergeUniqueStrings(update.decisions);
+    const touchedFiles = action === 'append'
+      ? mergeUniqueStrings(existingData.touchedFiles, update.touchedFiles)
+      : mergeUniqueStrings(update.touchedFiles);
+    const mergedData = action === 'append'
+      ? {
+          goal: update.goal || existingData.goal || 'Untitled session',
+          status: resolvedStatus,
+          pinnedContext: mergeUniqueStrings(existingData.pinnedContext, update.pinnedContext),
+          unresolvedQuestions: mergeUniqueStrings(existingData.unresolvedQuestions, update.unresolvedQuestions),
+          currentFocus: update.currentFocus || existingData.currentFocus || '',
+          whyBlocked: update.whyBlocked || existingData.whyBlocked || '',
+          completed,
+          decisions,
+          blockers: update.blockers !== undefined ? mergeUniqueStrings(update.blockers) : (existingData.blockers || []),
+          nextStep: update.nextStep || existingData.nextStep || '',
+          touchedFiles,
+          completedCount: completed.length,
+          decisionsCount: decisions.length,
+          touchedFilesCount: touchedFiles.length,
+        }
+      : {
+          goal: update.goal || 'Untitled session',
+          status: normalizeStatus(update.status),
+          pinnedContext: mergeUniqueStrings(update.pinnedContext),
+          unresolvedQuestions: mergeUniqueStrings(update.unresolvedQuestions),
+          currentFocus: update.currentFocus ?? '',
+          whyBlocked: update.whyBlocked ?? '',
+          completed,
+          decisions,
+          blockers: mergeUniqueStrings(update.blockers),
+          nextStep: update.nextStep ?? '',
+          touchedFiles,
+          completedCount: completed.length,
+          decisionsCount: decisions.length,
+          touchedFilesCount: touchedFiles.length,
+        };
+    
+    const savedData = saveSession(targetSessionId, mergedData);
+    const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(savedData, maxTokens);
+    
+    const rawTokens = countTokens(JSON.stringify(savedData));
+    const summaryMetrics = buildSummaryMetrics(rawTokens, tokens);
+
+    persistMetrics({
+      tool: 'smart_summary',
+      action,
+      sessionId: targetSessionId,
+      ...summaryMetrics,
+      latencyMs: Date.now() - startTime,
+    });
+    
+    return {
+      action,
+      sessionId: targetSessionId,
+      summary: compressed,
+      tokens,
+      truncated,
+      omitted,
+      compressionLevel,
+      schemaVersion: savedData.schemaVersion,
+      updatedAt: savedData.updatedAt,
+      message: action === 'append' ? 'Session updated incrementally.' : 'Session saved.',
+    };
+  }
+  
+  throw new Error(`Invalid action: ${action}. Valid actions: get, update, append, reset, list_sessions`);
+};