context-mcp-server 1.0.8 → 1.1.1

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/server.js

@@ -1,8 +1,14 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { getConfig } from './config.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
 import * as contextTool    from './tools/context.js';
 import * as searchTool     from './tools/search.js';
 import * as planTool        from './tools/plan.js';
@@ -23,7 +29,7 @@ export function createServer({ enableFileTools = false, enableGitTools = getConf
   };
 
   const server = new Server(
-    { name: 'context-mcp', version: '1.0.0' },
+    { name: 'context-mcp', version },
     { capabilities: { tools: {} } }
   );
 

package/src/templates/antigravity/GEMINI.md

@@ -0,0 +1,96 @@
+# Context-MCP — Antigravity IDE Usage Guide
+
+Persistent memory + codebase knowledge graph via `ctx` CLI commands.
+Run `ctx resume` to start every session. Use `ctx search` to recall past work. Use `ctx save` to persist decisions. Use `ctx add` to record discoveries.
+
+---
+
+## 1. Start of Every Conversation (MANDATORY)
+
+Run `ctx resume --project <project>` (shell command) before anything else.
+
+Returns recent entries, active plans, graph status.
+
+- Graph built → use `ctx graph query` / `ctx graph arch` before reading files
+- Graph not built → run `ctx graph build <path>` first
+- `totalEntries ≥ 20` → save compaction summary FIRST (see Rule 4)
+- Active plans present → read them before starting new work
+
+---
+
+## 2. Save Triggers (MANDATORY)
+
+Run `ctx save` after finishing anything worth keeping:
+
+```
+ctx save --project <project> --title "..." --why "..." --outcome "..." --type note
+ctx save --project <project> --title "..." --content "..." --type bug
+ctx save --project <project> --title "Session summary — YYYY-MM-DD" --content "..." --type compaction
+```
+
+| Trigger | Command |
+|---|---|
+| Task / fix / feature complete | `ctx save` with `--why` + `--outcome` + `--files` |
+| Decision made | `ctx save` with `--why` + `--outcome` |
+| Discovery / constraint | `ctx save` with `--content` |
+| User says "save this" | `ctx save` with `--title` + `--content` |
+| Compact memory | `ctx save --type compaction` |
+
+**Do NOT save:** routine reads, search results, explanations of existing code.
+
+---
+
+## 3. Plans (MANDATORY for multi-file work)
+
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
+
+```
+ctx plan save --project <project> --name "..." --content "..."
+ctx plan done --project <project> --name "..."   # deletes the plan
+```
+
+Check active plans on resume — don't create duplicates.
+
+---
+
+## 4. Auto-Summary at ≥ 20 Entries (MANDATORY)
+
+When `totalEntries ≥ 20`, run this BEFORE the user's task:
+
+```
+ctx save --project <project> --type compaction \
+  --title "Session summary — YYYY-MM-DD" \
+  --content "<what was built, decided, broke, current state>"
+```
+
+---
+
+## 5. Search Before Asking
+
+Run `ctx search "<query>" --project <project>` before asking the user to re-explain past work.
+
+---
+
+## 6. ContextGraph CLI
+
+```
+ctx graph build <path>            → build AST graph (run once, incremental)
+ctx graph arch <path>             → module map: files, exports, imports
+ctx graph query <path> "<question>"  → structural question about the codebase
+ctx graph nodes <path> <type>     → list all nodes of a type
+ctx graph report <path>           → god nodes, clusters, surprising connections
+```
+
+Use `ctx graph arch` first. Never read files for structure questions.
+
+---
+
+## 7. Rules
+
+1. `ctx 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 — `ctx plan done` deletes it
+6. `ctx search` before asking about past work
+7. `ctx graph` before reading files

package/src/templates/antigravity/hooks/context-mcp-post-tool-use.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Antigravity IDE PostToolUse hook for context-mcp.
+ *
+ * Input (stdin JSON): {
+ *   toolCall: { name, args },
+ *   stepIdx, conversationId, workspacePaths,
+ *   error        ← present when the tool invocation failed
+ * }
+ *
+ * Saves failed tool invocations to context-mcp so the next session can see
+ * what broke. Exits silently when the tool succeeded or no error is present.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  let event = {};
+  try {
+    event = input.trim() ? JSON.parse(input) : {};
+  } catch {
+    return;
+  }
+
+  const toolCall = event.toolCall || {};
+  const toolName = toolCall.name || '';
+  const error = event.error;
+
+  if (!error || !toolName) return;
+
+  const args = toolCall.args || {};
+  const argsSnippet = Object.keys(args).length
+    ? JSON.stringify(args).slice(0, 200)
+    : '';
+
+  const cwd = (event.workspacePaths || [])[0] || process.cwd();
+  const project = cwd.replace(/\\/g, '/').replace(/\/$/, '').split('/').pop() || 'default';
+
+  const content = [
+    `Tool: ${toolName}`,
+    argsSnippet ? `Args: ${argsSnippet}` : null,
+    `Error: ${String(error).slice(0, 4000)}`,
+  ].filter(Boolean).join('\n\n');
+
+  spawnSync('ctx', [
+    'save',
+    '--project', project,
+    '--type', 'bug',
+    '--title', `Failed tool: ${toolName.slice(0, 80)}`,
+    '--content', content,
+  ], {
+    encoding: 'utf8',
+    shell: true,
+    stdio: 'ignore',
+  });
+});

package/src/templates/antigravity/workflows/context-resume.md

@@ -0,0 +1,20 @@
+# context-resume
+
+Resume context for the current project from persistent memory.
+
+## Steps
+
+1. Call the `context` MCP tool with `action: "resume"` and `project: "<current project name>"`.
+2. Read `recentEntries` — the last saved notes, decisions, and bug records.
+3. Read `activePlans` — any in-progress multi-step plans.
+4. Check `codegraph.built`:
+   - `true` → graph tools are available; use `codegraph_arch` before reading files
+   - `false` → run `codegraph_build` when structural questions arise
+5. If `stats.totalEntries ≥ 20`, save a compaction summary before starting work:
+   ```
+   context(action:"save", type:"compaction",
+     title:"Session summary — YYYY-MM-DD",
+     content:"<full summary of session>",
+     project:"<project>")
+   ```
+6. Summarize what was found: recent work, open plans, graph status.