context-mcp-server 1.0.8 → 1.1.0

package/src/db.js

@@ -15,11 +15,11 @@
 import {
   readFileSync, writeFileSync, mkdirSync, existsSync,
   openSync, closeSync, unlinkSync, renameSync, chmodSync, rmdirSync,
+  readdirSync,
 } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { runMigration } from './migrator.js';
 
 const DATA_DIR     = process.env.CONTEXT_MCP_DIR || join(homedir(), '.context-mcp');
 const PROJECTS_DIR = join(DATA_DIR, 'projects');
@@ -74,7 +74,6 @@ let _dirtyProjects = new Set();
 let _dirty = false;
 let _writeTimer = null;
 let _generation = 0;
-let _migrated = false;
 
 // ── File I/O helpers ─────────────────────────────────────────────────────────
 
@@ -122,7 +121,18 @@ function _readObj(filePath, defaults) {
 
 function loadProjectsIndex() {
   if (_projectsIndex) return _projectsIndex;
-  if (!existsSync(PROJECTS_PATH)) { _projectsIndex = []; return _projectsIndex; }
+  if (!existsSync(PROJECTS_PATH)) {
+    // Fall back to scanning the projects dir so CLI works without projects.json
+    _projectsIndex = [];
+    if (existsSync(PROJECTS_DIR)) {
+      try {
+        for (const slug of readdirSync(PROJECTS_DIR, { withFileTypes: true })) {
+          if (slug.isDirectory()) _projectsIndex.push({ name: slug.name, slug: slug.name });
+        }
+      } catch {}
+    }
+    return _projectsIndex;
+  }
   try {
     const d = JSON.parse(readFileSync(PROJECTS_PATH, 'utf8'));
     _projectsIndex = Array.isArray(d.projects) ? d.projects : [];
@@ -130,21 +140,6 @@ function loadProjectsIndex() {
   return _projectsIndex;
 }
 
-// ── Migration ─────────────────────────────────────────────────────────────────
-
-function migrate() {
-  if (_migrated) return;
-  _migrated = true;
-  runMigration({
-    dataDir:       DATA_DIR,
-    projectsDir:   PROJECTS_DIR,
-    projectsPath:  PROJECTS_PATH,
-    slugify,
-    flushFile:     _flushFile,
-    projectsIndex: loadProjectsIndex(),
-  });
-}
-
 // ── Per-project data loading ─────────────────────────────────────────────────
 
 function loadProjectData(name) {
@@ -166,7 +161,6 @@ function getAllEntries(projectName) {
   return [...data.context, ...data.summary];
 }
 
-// Find an entry by ID, optionally scoped to a project.
 function findEntryById(id, projectHint) {
   const search = (data) => {
     for (const arr of [data.context, data.summary]) {
@@ -184,7 +178,6 @@ function findEntryById(id, projectHint) {
     const e = search(data);
     if (e) return { entry: e, projectName: name };
   }
-  // Load all remaining projects
   const idx = loadProjectsIndex();
   for (const proj of idx) {
     if (_projectData.has(proj.name) || proj.name === projectHint) continue;
@@ -194,7 +187,6 @@ function findEntryById(id, projectHint) {
   return null;
 }
 
-// Remove an entry from its array in the project data.
 function removeEntryFromData(data, entry) {
   if (treeFor(entry) === 'summary') {
     data.summary = data.summary.filter(e => e.id !== entry.id);
@@ -223,7 +215,7 @@ function flushProjectToDisk(name) {
   _flushFile(discussFilePath(name),   { discussions: data.discussions });
 }
 
-function flushToDisk() {
+export function flushToDisk() {
   if (!_dirty) return;
   _writeTimer = null;
 
@@ -244,11 +236,8 @@ process.on('exit', flushToDisk);
 process.on('SIGINT',  () => { flushToDisk(); process.exit(); });
 process.on('SIGTERM', () => { flushToDisk(); process.exit(); });
 
-// ── Initialise: run migration lazily on first access ─────────────────────────
-
 function init() {
   loadProjectsIndex();
-  migrate();
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -283,6 +272,8 @@ function compactEntry(e) {
     updatedAt: e.updatedAt || null,
     preview:   truncate(e.content, PREVIEW_LENGTH),
   };
+  if (e.why)     compact.why     = e.why;
+  if (e.outcome) compact.outcome = e.outcome;
   if (e.files    && e.files.length)    compact.files    = e.files;
   if (e.codeRefs && e.codeRefs.length) compact.codeRefs = e.codeRefs;
   if (e.expiresAt) compact.expiresAt = e.expiresAt;
@@ -291,7 +282,26 @@ function compactEntry(e) {
 
 // ── Context entries ──────────────────────────────────────────────────────────
 
-export function saveContext({ project, content, tags = [], source = 'user', title = '',
+const VALID_TYPES = new Set(['note', 'compaction']);
+
+function computeImportance({ files = [], why = '', outcome = '', tags = [], type } = {}) {
+  if (type === 'compaction') return 5;
+  let score = 0;
+  if (Array.isArray(files) && files.length > 0) score += 2;
+  if (why && why.trim()) score += 1;
+  if (outcome && outcome.trim()) score += 1;
+  if (Array.isArray(tags) && tags.some(t => t === 'plan' || t === 'decision')) score += 1;
+  return score;
+}
+
+const _SECRET_PATTERN = /("?(?:api[-_]?key|password|passwd|pwd|token|secret|authorization|auth_token|access_token|refresh_token|bearer|cookie|signature|private[-_]?key|client[-_]?secret)"?\s*[:=]\s*)("[^"]*"|'[^']*'|\S+)/gi;
+
+function redactSecrets(text) {
+  if (typeof text !== 'string') return text;
+  return text.replace(_SECRET_PATTERN, '$1[REDACTED]');
+}
+
+export function saveContext({ project, content, why = '', outcome = '', tags = [], source = 'user', title = '',
   type = 'note', status = 'active', files = [], codeRefs = [],
   sessionId = null, parentId = null, expiresAt = null, rootPath = null }) {
   init();
@@ -299,6 +309,9 @@ export function saveContext({ project, content, tags = [], source = 'user', titl
   ensureProject(projectName, rootPath || undefined);
   const data = loadProjectData(projectName);
   const now = new Date().toISOString();
+  const validatedType = VALID_TYPES.has(type) ? type : 'note';
+  const normalizedFiles = Array.isArray(files) ? files : [];
+  const normalizedTags = normalizeTags(tags);
   const entry = {
     id: randomUUID(),
     project: projectName,
@@ -306,29 +319,31 @@ export function saveContext({ project, content, tags = [], source = 'user', titl
     parentId: parentId || sessionId || `project:${projectName}`,
     nodeType: 'entry',
     version: 1,
-    title: truncate(title, 60),
-    content: truncate(content, MAX_CONTENT_LENGTH),
-    type,
+    title: truncate(title, 120),
+    content: redactSecrets(truncate(content, MAX_CONTENT_LENGTH)),
+    why: redactSecrets(truncate(why || '', 300)),
+    outcome: redactSecrets(truncate(outcome || '', 300)),
+    type: validatedType,
     status,
-    tags: normalizeTags(tags),
+    tags: normalizedTags,
     source: normalizeSource(source),
-    files: Array.isArray(files) ? files : [],
+    files: normalizedFiles,
     codeRefs: Array.isArray(codeRefs) ? codeRefs : [],
+    importance: computeImportance({ files: normalizedFiles, why, outcome, tags: normalizedTags, type: validatedType }),
     discussionId: null,
     createdAt: now,
     updatedAt: null,
     expiresAt: expiresAt || null,
   };
   const tree = treeFor(entry);
-  if (tree === 'graph') data.graph.entries.push(entry);
-  else if (tree === 'summary') data.summary.push(entry);
+  if (tree === 'summary') data.summary.push(entry);
   else data.context.push(entry);
   _dirtyProjects.add(projectName);
   markDirty();
   return entry;
 }
 
-export function updateContext({ id, content, title, tags, type, status, files, codeRefs, sessionId, parentId, expiresAt }) {
+export function updateContext({ id, content, why, outcome, title, tags, type, status, files, codeRefs, sessionId, parentId, expiresAt }) {
   init();
   const found = findEntryById(id);
   if (!found) return null;
@@ -337,9 +352,11 @@ export function updateContext({ id, content, title, tags, type, status, files, c
 
   const oldTree = treeFor(entry);
   if (content   !== undefined) entry.content   = truncate(content, MAX_CONTENT_LENGTH);
-  if (title     !== undefined) entry.title     = truncate(title, 60);
+  if (why       !== undefined) entry.why       = truncate(why     || '', 300);
+  if (outcome   !== undefined) entry.outcome   = truncate(outcome || '', 300);
+  if (title     !== undefined) entry.title     = truncate(title, 120);
   if (tags      !== undefined) entry.tags      = normalizeTags(tags);
-  if (type      !== undefined) entry.type      = type;
+  if (type      !== undefined) entry.type      = VALID_TYPES.has(type) ? type : entry.type;
   if (status    !== undefined) entry.status    = status;
   if (files     !== undefined) entry.files     = Array.isArray(files) ? files : [];
   if (codeRefs  !== undefined) entry.codeRefs  = Array.isArray(codeRefs) ? codeRefs : [];
@@ -353,11 +370,8 @@ export function updateContext({ id, content, title, tags, type, status, files, c
   const newTree = treeFor(entry);
   if (newTree !== oldTree) {
     removeEntryFromData(data, entry);
-    // Re-add with updated tree
-    const tempEntry = { ...entry };
-    if (newTree === 'graph') data.graph.entries.push(tempEntry);
-    else if (newTree === 'summary') data.summary.push(tempEntry);
-    else data.context.push(tempEntry);
+    if (newTree === 'summary') data.summary.push(entry);
+    else data.context.push(entry);
   }
 
   _dirtyProjects.add(projectName);
@@ -478,7 +492,7 @@ export function deleteProject(nameOrId) {
 
   // Count before removing
   const data = _projectData.get(projectName) || loadProjectData(projectName);
-  const ctxCount  = data.context.length + data.graph.entries.length + data.summary.length;
+  const ctxCount  = data.context.length + data.summary.length;
   const discCount = data.discussions.length;
 
   // Remove project directory from disk
@@ -605,7 +619,7 @@ export function saveDiscussion({ name, title, description, content, project, tag
     project:          project          !== undefined ? (project || 'global')                              : (prev?.project          ?? 'global'),
     sessionId:        sessionId        !== undefined ? (sessionId || null)                                : (prev?.sessionId        ?? null),
     parentId:         parentId         !== undefined ? (parentId || null)                                 : (prev?.parentId         ?? null),
-    title:            title            !== undefined ? truncate(title || name, 80)                        : (prev?.title            ?? name),
+    title:            title            !== undefined ? truncate(title || name, 120)                       : (prev?.title            ?? name),
     description:      description      !== undefined ? (description || '')                                : (prev?.description      ?? ''),
     content:          content          !== undefined ? truncate(content || '', MAX_CONTENT_LENGTH)         : (prev?.content          ?? ''),
     type:             type             !== undefined ? (VALID_DISCUSSION_TYPES.has(type) ? type : 'plan')  : (prev?.type             ?? 'plan'),
@@ -651,7 +665,7 @@ export function updateDiscussion({ id, name, title, description, content, status
     if (found) { disc = found; projName = pName; break; }
   }
   if (!disc) return null;
-  if (title       !== undefined) disc.title       = truncate(title || disc.name, 80);
+  if (title       !== undefined) disc.title       = truncate(title || disc.name, 120);
   if (description !== undefined) disc.description = description || '';
   if (content     !== undefined) disc.content     = truncate(content || '', MAX_CONTENT_LENGTH);
   if (type        !== undefined) disc.type        = VALID_DISCUSSION_TYPES.has(type)      ? type   : disc.type;
@@ -747,28 +761,6 @@ export function linkContextToDiscussion({ discussionId, discussionName, contextI
   return { discussionId: disc.id, contextId };
 }
 
-export function getContextByDiscussion(discussionId) {
-  init();
-  const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
-  const results = [];
-  for (const name of seen) {
-    results.push(...getAllEntries(name).filter(c => c.discussionId === discussionId));
-  }
-  return results;
-}
-
-export function clearDiscussionLink(contextId) {
-  init();
-  const found = findEntryById(contextId);
-  if (!found) return null;
-  found.entry.discussionId = null;
-  found.entry.updatedAt = new Date().toISOString();
-  _dirtyProjects.add(found.projectName);
-  markDirty();
-  return found.entry;
-}
-
 export function deleteDiscussion({ name, id }) {
   init();
   const idx = loadProjectsIndex();
@@ -790,38 +782,6 @@ export function deleteDiscussion({ name, id }) {
   return { deleted: 0 };
 }
 
-export function updateDiscussionStep({ discussionName, discussionId, stepId, status, linkedContextId }) {
-  init();
-  let disc = null;
-  let projName = null;
-  const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
-  for (const pName of seen) {
-    const d = loadProjectData(pName);
-    const found = discussionId
-      ? d.discussions.find(x => x.id   === discussionId)
-      : d.discussions.find(x => x.name === discussionName);
-    if (found) { disc = found; projName = pName; break; }
-  }
-  if (!disc) return null;
-  const step = (disc.steps || []).find(s => s.id === stepId);
-  if (!step) return null;
-  if (status) step.status = status;
-  if (status === 'done') step.completedAt = new Date().toISOString();
-  if (linkedContextId) {
-    if (!Array.isArray(step.linkedContextIds)) step.linkedContextIds = [];
-    if (!step.linkedContextIds.includes(linkedContextId)) step.linkedContextIds.push(linkedContextId);
-    if (!Array.isArray(disc.linkedContextIds)) disc.linkedContextIds = [];
-    if (!disc.linkedContextIds.includes(linkedContextId)) disc.linkedContextIds.push(linkedContextId);
-  }
-  const allDone = disc.steps.every(s => s.status === 'done' || s.status === 'skipped');
-  if (allDone && disc.status !== 'done') disc.status = 'done';
-  disc.updatedAt = new Date().toISOString();
-  _dirtyProjects.add(projName);
-  markDirty();
-  return { discussion: disc, step };
-}
-
 // ── Auto-operations ───────────────────────────────────────────────────────────
 
 export function archiveExpired(project) {
@@ -862,21 +822,39 @@ const COMPACTION_THRESHOLD = 20;
 const COMPACTION_TARGET    = 30;
 
 export function shouldCompact(project) {
-  return countContext(project) > COMPACTION_THRESHOLD;
+  init();
+  // Only count non-compaction entries — compaction summaries themselves don't trigger further compaction
+  const proj = project || 'global';
+  const data = loadProjectData(proj);
+  const nonCompaction = [...data.context, ...data.summary].filter(e => e.type !== 'compaction');
+  return nonCompaction.length > COMPACTION_THRESHOLD;
 }
 
-export function compactProject(project, summaryContent) {
+export function compactProject(project, summaryContent, { skipSummaryEntry = false } = {}) {
   init();
   const proj = project || 'global';
   const data = loadProjectData(proj);
+  const now = Date.now();
   const entries = data.context
-    .sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    .filter(e => e.type !== 'compaction')  // never remove existing compaction summaries
+    .sort((a, b) => {
+      // Higher score = more expendable; oldest + least important drops first
+      const ageDaysA = (now - new Date(a.createdAt || 0).getTime()) / 86_400_000;
+      const ageDaysB = (now - new Date(b.createdAt || 0).getTime()) / 86_400_000;
+      const scoreA = ageDaysA * 0.7 + (5 - (a.importance ?? 0)) * 0.3;
+      const scoreB = ageDaysB * 0.7 + (5 - (b.importance ?? 0)) * 0.3;
+      return scoreB - scoreA;
+    });
   if (entries.length < COMPACTION_TARGET) return null;
   const toRemove = new Set(entries.slice(0, COMPACTION_TARGET).map(e => e.id));
   const removed = entries.filter(e => toRemove.has(e.id));
   for (const entry of removed) removeEntryFromData(data, entry);
   _dirtyProjects.add(proj);
   markDirty();
+  // If AI already saved a compaction entry this call, don't create a duplicate
+  if (skipSummaryEntry) {
+    return { removedCount: removed.length, summaryId: null };
+  }
   const summary = saveContext({
     project: proj,
     title: `Compacted ${removed.length} entries — ${new Date().toISOString().slice(0, 10)}`,
@@ -892,7 +870,6 @@ export function compactProject(project, summaryContent) {
 
 export function saveGraph({ path, nodes, edges, communities, cached, changed, time_ms, summary }) {
   init();
-  // Find project by rootPath matching graph path
   const idx = loadProjectsIndex();
   const proj = idx.find(p => normPath(p.rootPath) === normPath(path));
   const projName = proj ? proj.name : 'global';

package/src/search.js

@@ -1,13 +1,71 @@
-/**
- * search.js — unified search entry point
- *
- * Single function replaces direct calls to searchContext / vectorSearch / findRelated
- * across index.js, cli.js, and error_check. db.js + vector.js stay as low-level impls.
- */
-
 import { getContext, searchContext } from './db.js';
 import { vectorSearch, findRelated } from './vector.js';
 
+// ── Vocabulary cache (lazy singleton per process) ─────────────────────────────
+
+let _vocabCache = null;
+
+function buildVocab(entries) {
+  const vocab = new Set();
+  for (const e of entries) {
+    const text = `${e.title || ''} ${e.content || ''}`.toLowerCase();
+    for (const w of text.split(/\W+/)) {
+      if (w.length > 2) vocab.add(w);
+    }
+  }
+  return vocab;
+}
+
+// ── Levenshtein fuzzy correction ──────────────────────────────────────────────
+
+function levenshtein(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const curr = [i + 1];
+    for (let j = 0; j < b.length; j++) {
+      curr.push(Math.min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (a[i] === b[j] ? 0 : 1)));
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+
+function maxEditDist(len) {
+  if (len <= 4) return 1;
+  if (len <= 12) return 2;
+  return 3;
+}
+
+function fuzzyCorrect(word, vocab) {
+  const max = maxEditDist(word.length);
+  let bestWord = word;
+  let bestDist = max + 1;
+  for (const candidate of vocab) {
+    if (Math.abs(candidate.length - word.length) > max) continue;
+    const dist = levenshtein(word, candidate);
+    if (dist < bestDist) { bestDist = dist; bestWord = candidate; }
+  }
+  return bestDist <= max ? bestWord : word;
+}
+
+// ── Smart snippet (window centered on first match position) ───────────────────
+
+function snippet(text, terms, windowSize = 200) {
+  if (!text) return text;
+  const lower = text.toLowerCase();
+  let bestPos = -1;
+  for (const term of terms) {
+    const idx = lower.indexOf(term.toLowerCase());
+    if (idx !== -1 && (bestPos === -1 || idx < bestPos)) bestPos = idx;
+  }
+  if (bestPos === -1) return text.slice(0, windowSize);
+  const start = Math.max(0, bestPos - Math.floor(windowSize / 3));
+  const end = Math.min(text.length, start + windowSize);
+  return (start > 0 ? '…' : '') + text.slice(start, end) + (end < text.length ? '…' : '');
+}
+
+// ── Unified search ────────────────────────────────────────────────────────────
+
 /**
  * @param {Object} opts
  * @param {string} opts.query      - search query (keyword/semantic)
@@ -21,7 +79,14 @@ export function search({ query, mode = 'semantic', project, limit = 10, id, comp
   switch (mode) {
     case 'keyword': {
       if (!query) throw new Error('query required for keyword search');
-      return searchContext({ query, project, limit, compact });
+      if (!_vocabCache) {
+        _vocabCache = buildVocab(getContext({ project, limit: 500 }));
+      }
+      const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+      const corrected = terms.map(t => fuzzyCorrect(t, _vocabCache));
+      const correctedQuery = corrected.join(' ');
+      const results = searchContext({ query: correctedQuery, project, limit, compact: false });
+      return results.map(e => ({ ...e, content: snippet(e.content, corrected) }));
     }
     case 'semantic': {
       if (!query) throw new Error('query required for semantic search');
@@ -33,7 +98,6 @@ export function search({ query, mode = 'semantic', project, limit = 10, id, comp
       const all = getContext({ limit: 1000 });
       const target = all.find(e => e.id === id || e.id.startsWith(id));
       if (!target) throw new Error(`No entry found with id starting "${id}"`);
-      // explicit relations first, semantic enrichment for remainder
       const explicitIds = new Set([
         ...(target.relations  || []).map(r => r.id),
         ...(target.relatedBy  || []).map(r => r.id),

package/src/templates/AGENTS.md

@@ -1,80 +1,90 @@
 # Context-MCP — Codex CLI Usage Guide
 
 Persistent memory + codebase knowledge graph.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
 
 ---
 
 ## 1. Start of Every Conversation (MANDATORY)
 
-Call the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
+Call `context` MCP tool: `action:"resume"`, `project:"<project>"` before anything else.
 
-Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activePlans` — active AI-created plans for this project
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
+Returns: `recentEntries`, `activePlans`, `codegraph`, `stats.totalEntries`.
 
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
+- `codegraph.built: true` → use graph tools before reading files
+- `codegraph.built: false` → call `codegraph_build(path)` first
+- `stats.totalEntries ≥ 20` → write compaction summary FIRST (see Rule 4)
+- `activePlans` non-empty → read them before starting new work
 
 ---
 
-## 2. When to Auto-Save Context
+## 2. Save Triggers (MANDATORY)
 
-**After graph build or rebuild** — every time `codegraph_build` completes:
-```
-context.save  type: "note"  title: "ContextGraph built — <project>"
-content: "nodes: X | edges: Y | communities: Z"
-```
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
 
-**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
+| Trigger | Required fields |
+|---|---|
+| Task / fix / feature complete | title, why, outcome, files[] |
+| Decision made | title, why, outcome |
+| Discovery / constraint / gotcha | title, content |
+| Config / env / deploy info | title, content |
+| Graph build complete | title, content (nodes/edges count) |
+| User says "save this" | title, content |
+| "compact now" / "compress memory" | `type:"compaction"`, full session summary |
 
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
+**Do NOT save:** routine reads, search results, explanations of existing code.
+
+---
 
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
+## 3. Plans (MANDATORY for multi-file work)
 
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-Need past info → `search` before asking. Always pass `project`.
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
+
+1. Call `plan.save` with name, content, project before starting
+2. Call `plan.update status:"done"` when complete — deletes the plan
+
+Check `activePlans` on resume — don't create duplicates.
 
 ---
 
-## 3. ContextGraph Pipeline
+## 4. Auto-Summary at ≥ 20 Entries (MANDATORY)
 
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
+When `totalEntries ≥ 20`, call `context.save` BEFORE the user's task:
 
-### Step 1 — Build (once, fast, local)
 ```
-codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+type: "compaction"  title: "Session summary — <YYYY-MM-DD>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
 ```
 
-### Step 2 — Query (free, instant)
-```
-codegraph_query(path, question)   →  fetch any details about the codebase
-codegraph_path(path, from, to)    →  shortest path
-codegraph_nodes(path, type)       →  list nodes by type
-codegraph_report(path)            →  full graph analysis
-```
+---
+
+## 5. Search Before Asking
+
+Call `search` before asking user to re-explain past work.
 
 ---
 
-## 4. Graph vs File
+## 6. ContextGraph Tools
+
+```
+codegraph_build(path)                    → build AST graph (run once)
+codegraph_arch(path, limit?)             → module map: files, exports, imports
+codegraph_query(path, question?, node?)  → find symbol or answer structural question
+codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_report(path)                   → structural analysis
+```
 
-**Graph** — use for any question about what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
-**File** — bugs, logic, tracing unexpected behavior.
+Use `codegraph_arch` first. Never read files for structure questions.
 
 ---
 
-## 5. Rules
+## 7. Rules
 
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`**
-3. **`search` before asking** — if user references past work
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic only**
+1. `context.resume` first — before any tool or response
+2. Always pass `project`
+3. Save on task complete — `why` + `outcome` + `files`
+4. Compaction at ≥ 20 entries — before starting task
+5. Plan before multi-file work — `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files