@aabadin/project-memory-context 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aabadin/project-memory-context",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -11,7 +11,8 @@
     "./retrieval": "./src/retrieval/query-engine.mjs"
   },
   "bin": {
-    "pmc": "bin/pmc.mjs"
+    "pmc": "bin/pmc.mjs",
+    "pmc-query-server": "mcp/pmc-query-server.mjs"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",

package/src/command-dispatch.mjs

@@ -14,6 +14,7 @@ const COMMANDS = new Map([
   ['install-pmc', 'cli/install-pmc.mjs'],
   ['new-project', 'cli/new-project.mjs'],
   ['project-context', 'cli/project-context.mjs'],
+  ['query', 'cli/query.mjs'],
   ['sanitize', 'cli/sanitize.mjs'],
   ['setup', 'cli/setup.mjs'],
   ['status', 'cli/status.mjs'],

package/src/plugin-config.mjs

@@ -1,6 +1,14 @@
 export function buildInjectedPmcConfig({ installState }) {
   return {
     mcp: {
+      'pmc-query': {
+        type: 'local',
+        command: ['npx', '--yes', '--package', '@aabadin/project-memory-context', 'pmc-query-server'],
+        enabled: true,
+        environment: {
+          PMC_PROJECT_ROOT: installState.projectRoot,
+        },
+      },
       'pmc-agent-memory': {
         type: 'local',
         command: ['npx', '-y', '@aabadin/agent-memory-mcp'],

package/src/query/load-artifacts.mjs

@@ -0,0 +1,96 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function normalizePath(filePath) {
+  return String(filePath ?? '').replace(/\\/g, '/');
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function readJsonDirectory(directoryPath) {
+  try {
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.json'))
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function loadMemories(projectContextDir) {
+  const materializedDir = join(projectContextDir, 'materialized');
+  const materializedEntries = await readJsonDirectory(materializedDir);
+  const directory = materializedEntries.length > 0 ? materializedDir : projectContextDir;
+  const fileNames = materializedEntries.length > 0
+    ? materializedEntries
+    : await readJsonDirectory(projectContextDir);
+
+  const memories = [];
+  for (const fileName of fileNames) {
+    const path = join(directory, fileName);
+    const memory = await readJson(path, null);
+    if (memory) {
+      memories.push({ ...memory, path });
+    }
+  }
+
+  return memories;
+}
+
+function parseSymbol(symbolKey, entry, semanticSummary) {
+  const parts = String(symbolKey ?? '').split('|');
+  return {
+    symbolKey,
+    filePath: parts.length >= 2 ? normalizePath(parts[1]) : '',
+    name: parts.length >= 2 ? parts[parts.length - 2] : '',
+    graphNodeId: entry?.graphNodeId ?? null,
+    memoryId: entry?.memoryId ?? null,
+    status: entry?.status ?? null,
+    semanticSummary,
+  };
+}
+
+export async function loadQueryArtifacts(projectRoot) {
+  const pmcRoot = join(projectRoot, '.planning', 'project-memory-context');
+  const projectContextDir = join(pmcRoot, 'project-context');
+  const symbolIndexPath = join(pmcRoot, 'enrichment', 'symbol-index.json');
+  const graphPath = join(pmcRoot, 'graph', 'graph.json');
+
+  const memories = await loadMemories(projectContextDir);
+  const symbolIndex = await readJson(symbolIndexPath, {});
+  const graph = await readJson(graphPath, {});
+  const nodes = graph.nodes ?? [];
+  const edges = graph.edges ?? graph.links ?? [];
+
+  const nodeById = new Map(nodes.map((node) => [node?.id, node]));
+  const symbols = Object.entries(symbolIndex).map(([symbolKey, entry]) => {
+    const semanticSummary = String(
+      entry?.semanticSummary
+      ?? nodeById.get(entry?.graphNodeId)?.metadata?.semanticSummary
+      ?? '',
+    ).trim();
+
+    return parseSymbol(symbolKey, entry, semanticSummary);
+  });
+
+  return {
+    memories,
+    symbols,
+    nodes,
+    edges,
+  };
+}

package/src/query/orchestrator.mjs

@@ -0,0 +1,175 @@
+import { loadQueryArtifacts } from './load-artifacts.mjs';
+
+function normalizePath(filePath) {
+  return String(filePath ?? '').replace(/\\/g, '/');
+}
+
+function tokenize(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2);
+}
+
+function countMatches(tokens, fields) {
+  if (tokens.length === 0) {
+    return 0;
+  }
+
+  const haystack = fields.join(' ').toLowerCase();
+  let score = 0;
+  for (const token of tokens) {
+    if (haystack.includes(token)) {
+      score += 1;
+    }
+  }
+  return score;
+}
+
+function searchMemoryMatches(memories, tokens) {
+  return memories
+    .map((memory) => ({
+      ...memory,
+      score: countMatches(tokens, [
+        memory.title,
+        memory.summary,
+        memory.body,
+        ...(memory.tags ?? []),
+      ]),
+    }))
+    .filter((memory) => memory.score > 0)
+    .sort((a, b) => b.score - a.score || String(a.path).localeCompare(String(b.path)));
+}
+
+function searchSymbolMatches(symbols, tokens, fileFilter) {
+  const normalizedFilter = normalizePath(fileFilter);
+
+  return symbols
+    .map((symbol) => ({
+      ...symbol,
+      score: countMatches(tokens, [symbol.name, symbol.filePath, symbol.semanticSummary]),
+    }))
+    .filter((symbol) => symbol.score > 0)
+    .filter((symbol) => !normalizedFilter || symbol.filePath === normalizedFilter)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+
+function buildRelatedSymbols(symbols) {
+  const symbolByKey = new Map(symbols.map((symbol) => [symbol.symbolKey, symbol]));
+  const symbolKeyByNodeId = new Map(
+    symbols
+      .filter((symbol) => symbol.graphNodeId)
+      .map((symbol) => [symbol.graphNodeId, symbol.symbolKey]),
+  );
+
+  return { symbolByKey, symbolKeyByNodeId };
+}
+
+export function createQueryOrchestrator({ projectRoot, loadArtifacts = loadQueryArtifacts }) {
+  async function searchSymbols(query, fileFilter) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0) {
+      return [];
+    }
+
+    const artifacts = await loadArtifacts(projectRoot);
+    return searchSymbolMatches(artifacts.symbols, tokens, fileFilter);
+  }
+
+  async function query(question) {
+    const tokens = tokenize(question);
+    if (tokens.length === 0) {
+      return { answer: '', sources: [], tokens_saved: 0 };
+    }
+
+    const artifacts = await loadArtifacts(projectRoot);
+    const memoryMatches = searchMemoryMatches(artifacts.memories, tokens);
+    const symbolMatches = searchSymbolMatches(artifacts.symbols, tokens);
+
+    if (memoryMatches.length === 0 && symbolMatches.length === 0) {
+      return { answer: '', sources: [], tokens_saved: 0 };
+    }
+
+    const answerParts = [];
+    const sources = [];
+    let sourceCharacters = 0;
+
+    for (const memory of memoryMatches.slice(0, 3)) {
+      const body = String(memory.body ?? '').trim();
+      if (!body) {
+        continue;
+      }
+
+      answerParts.push(`${memory.title}: ${body}`);
+      sources.push({
+        type: 'project-context',
+        path: normalizePath(memory.path),
+        title: memory.title,
+      });
+      sourceCharacters += body.length + String(memory.summary ?? '').length;
+    }
+
+    for (const symbol of symbolMatches.slice(0, 3)) {
+      const summary = String(symbol.semanticSummary ?? '').trim();
+      if (!summary) {
+        continue;
+      }
+
+      answerParts.push(`Symbol ${symbol.name} (${symbol.filePath}): ${summary}`);
+      sources.push({
+        type: 'symbol',
+        symbolKey: symbol.symbolKey,
+        filePath: symbol.filePath,
+        graphNodeId: symbol.graphNodeId,
+      });
+      sourceCharacters += summary.length;
+    }
+
+    const answer = answerParts.join('\n\n');
+    if (!answer) {
+      return { answer: '', sources: [], tokens_saved: 0 };
+    }
+
+    return {
+      answer,
+      sources,
+      tokens_saved: Math.max(0, Math.ceil(sourceCharacters / 4) - Math.ceil(answer.length / 4)),
+    };
+  }
+
+  async function getRelatedSymbols(symbolKey, direction) {
+    if (!symbolKey) {
+      return [];
+    }
+
+    const artifacts = await loadArtifacts(projectRoot);
+    const { symbolByKey, symbolKeyByNodeId } = buildRelatedSymbols(artifacts.symbols);
+    const origin = symbolByKey.get(symbolKey);
+    if (!origin?.graphNodeId) {
+      return [];
+    }
+
+    return artifacts.edges
+      .map((edge) => {
+        const relatedNodeId = direction === 'inbound'
+          ? (edge.target === origin.graphNodeId ? edge.source : null)
+          : (edge.source === origin.graphNodeId ? edge.target : null);
+
+        return relatedNodeId ? symbolKeyByNodeId.get(relatedNodeId) : null;
+      })
+      .filter(Boolean)
+      .map((relatedKey) => symbolByKey.get(relatedKey));
+  }
+
+  return {
+    query,
+    searchSymbols,
+    getDependents(symbolKey) {
+      return getRelatedSymbols(symbolKey, 'inbound');
+    },
+    getDependencies(symbolKey) {
+      return getRelatedSymbols(symbolKey, 'outbound');
+    },
+  };
+}

package/src/retrieval/context-renderer-v1.mjs

@@ -0,0 +1,53 @@
+export function renderTargetContext({ summary = [], target = {}, relevant = [], relations = [], nextReads = [], metadata = {} } = {}) {
+  const lines = [];
+
+  lines.push('Summary');
+  if (summary.length > 0) {
+    for (const s of summary) {
+      lines.push(`- ${s}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('Target');
+  if (target.mode != null) lines.push(`  mode: ${target.mode}`);
+  if (target.name != null) lines.push(`  name: ${target.name}`);
+  if (target.value != null) lines.push(`  value: ${target.value}`);
+  if (target.filePath != null) lines.push(`  filePath: ${target.filePath}`);
+
+  lines.push('Relevant');
+  if (relevant.length > 0) {
+    for (const r of relevant) {
+      const display = r.filePath ?? r.label ?? 'unknown';
+      lines.push(`- ${display}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('Relations');
+  if (relations.length > 0) {
+    for (const rel of relations) {
+      const itemsStr = (rel.items ?? []).join(', ');
+      lines.push(`- ${rel.kind}: ${itemsStr}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('Next Reads');
+  if (nextReads.length > 0) {
+    for (const nr of nextReads) {
+      lines.push(`- ${nr}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('Metadata');
+  if (metadata.depth != null) lines.push(`  depth: ${metadata.depth}`);
+  if (metadata.focus != null) lines.push(`  focus: ${metadata.focus}`);
+
+  return lines.join('\n');
+}

package/src/retrieval/target-resolver.mjs

@@ -0,0 +1,57 @@
+function normalizeTargetPath(target) {
+  return String(target ?? '').replace(/\\/g, '/');
+}
+
+function hasFileNameishLastSegment(target) {
+  const last = target.split(/[\\/]/).pop();
+  return looksLikeBareFilename(last) || /\.[a-zA-Z0-9]{2,6}$/.test(last);
+}
+
+function looksLikePath(target) {
+  return /^[A-Za-z]:[\\/]/.test(target)
+    || /^[\\/]{2}/.test(target)
+    || /^\.{1,2}$/.test(target)
+    || /^\.{1,2}[\\/]/.test(target)
+    || (/[\\/]/.test(target) && (!/\s/.test(target) || hasFileNameishLastSegment(target)));
+}
+
+function looksLikeBareFilename(target) {
+  return /^(Dockerfile|Makefile|README\.(md|txt)|package\.json|tsconfig\.json|jsconfig\.json|\.gitignore|\.npmrc|\.env(\.[A-Za-z0-9_-]+)?)$/i.test(target);
+}
+
+function resolveSymbolTarget(engine, target) {
+  const symbolKeys = engine.findSymbolKeyByName(target);
+  if (symbolKeys.length === 1) {
+    return { mode: 'symbol', target, symbolKey: symbolKeys[0] };
+  }
+  if (symbolKeys.length > 1) {
+    return { mode: 'symbol-ambiguous', target, symbolKeys };
+  }
+  return { mode: 'symbol-missing', target };
+}
+
+export function resolveTarget({ engine, explicitMode = null, target }) {
+  if (explicitMode === 'query') {
+    return { mode: 'query', target };
+  }
+
+  if (explicitMode === 'file') {
+    return { mode: 'file', target: normalizeTargetPath(target) };
+  }
+
+  if (explicitMode === 'symbol') {
+    return resolveSymbolTarget(engine, target);
+  }
+
+  const normalizedTarget = normalizeTargetPath(target);
+  if (looksLikePath(target) || looksLikeBareFilename(target) || engine.findSymbolKeysByFilePath(normalizedTarget).length > 0) {
+    return { mode: 'file', target: normalizedTarget };
+  }
+
+  const symbolResult = resolveSymbolTarget(engine, target);
+  if (symbolResult.mode !== 'symbol-missing') {
+    return symbolResult;
+  }
+
+  return { mode: 'query', target };
+}

package/src/setup-bootstrap.mjs

@@ -145,6 +145,7 @@ export async function bootstrapProjectInstall({
   const dirs = await ensureProjectMemoryContextDirs(projectRoot);
   const memoryDbPath = join(dirs.base, 'memory-db');
   const installState = {
+    projectRoot,
     packageRoot,
     ollamaBaseUrl,
     ollamaModel,

package/src/template-installer.mjs

@@ -69,6 +69,10 @@ function stripBlockMarkers(content, marker) {
     .trim();
 }
 
+function wrapBlock(marker, block) {
+  return `<!-- pmc:${marker} -->\n${block}\n<!-- /pmc:${marker} -->\n`;
+}
+
 async function installWithBlockMarker({ projectRoot, packageRoot, placeholders, targetFile, templatePath, marker = 'init' }) {
   const targetPath = join(projectRoot, targetFile);
   const snippet = renderTemplate(await readTemplate(packageRoot, templatePath), placeholders);
@@ -84,6 +88,12 @@ async function installWithBlockMarker({ projectRoot, packageRoot, placeholders,
     return;
   }
 
+  if (existing.trim()) {
+    const updated = replaceOrAppendBlock(existing, marker, stripBlockMarkers(snippet, marker));
+    await writeFile(targetPath, updated, 'utf8');
+    return;
+  }
+
   await writeFile(targetPath, snippet, 'utf8');
 }
 
@@ -103,14 +113,20 @@ async function installOpencode({ projectRoot, packageRoot, placeholders, globalC
   for (const tpl of commandTemplates) {
     const rendered = renderTemplate(await readTemplate(packageRoot, tpl), placeholders);
     const fileName = tpl.split('/').at(-1);
-    await writeIfMissingOrForced(join(globalDir, 'commands', fileName), rendered, { force: true });
+    await writeIfMissingOrForced(join(globalDir, 'commands', fileName), rendered);
   }
 
   const enrichTemplate = renderTemplate(
     await readTemplate(packageRoot, 'opencode/agent/enrich.md'),
     placeholders,
   );
-  await writeIfMissingOrForced(join(globalDir, 'agents', 'enrich.md'), enrichTemplate, { force: true });
+  await writeIfMissingOrForced(join(globalDir, 'agents', 'enrich.md'), enrichTemplate);
+
+  const pmcSkill = renderTemplate(
+    await readTemplate(packageRoot, 'pmc-skill/SKILL.md'),
+    placeholders,
+  );
+  await writeIfMissingOrForced(join(globalDir, 'skills', 'pmc-skill', 'SKILL.md'), pmcSkill);
 
   const agentsMdPath = join(projectRoot, 'AGENTS.md');
   const autostartBlock = renderTemplate(
@@ -148,11 +164,43 @@ async function installCursor({ projectRoot, packageRoot, placeholders }) {
 }
 
 async function installGeneric({ projectRoot, packageRoot, placeholders }) {
+  const marker = 'generic';
+  const readmePath = join(projectRoot, 'README-SETUP.md');
+  const statePath = join(projectRoot, '.pmc', 'generic-readme-installed');
   const readme = renderTemplate(
     await readTemplate(packageRoot, 'generic/README-SETUP.md'),
     placeholders,
   );
-  await writeFile(join(projectRoot, 'README-SETUP.md'), readme, 'utf8');
+  const block = stripBlockMarkers(readme, marker);
+
+  if (existsSync(statePath)) {
+    if (!existsSync(readmePath)) {
+      await writeFile(readmePath, wrapBlock(marker, block), 'utf8');
+      return;
+    }
+
+    const existing = await readFile(readmePath, 'utf8');
+    if (hasBlockMarker(existing, marker)) {
+      await writeFile(readmePath, replaceOrAppendBlock(existing, marker, block), 'utf8');
+    } else {
+      await writeFile(readmePath, replaceOrAppendBlock(existing, marker, block), 'utf8');
+    }
+    return;
+  }
+
+  if (existsSync(readmePath)) {
+    const existing = await readFile(readmePath, 'utf8');
+    if (existing.trim()) {
+      await writeFile(readmePath, replaceOrAppendBlock(existing, marker, block), 'utf8');
+    } else {
+      await writeFile(readmePath, wrapBlock(marker, block), 'utf8');
+    }
+  } else {
+    await writeFile(readmePath, wrapBlock(marker, block), 'utf8');
+  }
+
+  await mkdir(dirname(statePath), { recursive: true });
+  await writeFile(statePath, 'installed\n', 'utf8');
 }
 
 const INSTALLERS = {
@@ -172,11 +220,15 @@ export async function installAgentTemplates({
     throw new Error(`Unsupported agent type: ${agent}. Supported: ${[...SUPPORTED_AGENTS].join(', ')}`);
   }
 
+  if (agent === 'opencode' && !globalConfigDir) {
+    throw new Error('globalConfigDir is required for agent: opencode');
+  }
+
   const pkgRoot = packageRoot ?? resolvePackageRoot();
   const placeholders = await buildPlaceholders(projectRoot, pkgRoot);
 
   await INSTALLERS[agent]({
-    globalConfigDir: globalConfigDir ?? join(projectRoot, '.pmc'),
+    globalConfigDir,
     packageRoot: pkgRoot,
     placeholders,
     projectRoot,

package/templates/claude-code/CLAUDE.md.snippet

@@ -2,6 +2,14 @@
 
 <!-- pmc:init -->
 
+PMC first, files second.
+
+Query PMC before reading more than 3 files. Prefer PMC for architecture, symbol lookup, dependencies, and callers before reading raw source.
+
+Available PMC MCP tools: `pmc_query_project`, `pmc_search_symbols`, `pmc_get_dependents`, `pmc_get_dependencies`.
+
+`/get-context` resolves a target (symbol, file, or query) and returns structural context. Accepts optional depth (compact|extended|deep) and focus (all|dependencies|callers|containment|impact).
+
 When the user types `/map-project`, run:
 
 ```bash
@@ -11,7 +19,7 @@ When the user types `/map-project`, run:
 When the user types `/get-context`, run:
 
 ```bash
-{{PMC_BIN}} context . --refresh
+{{PMC_BIN}} context <target> [depth] [focus]
 ```
 
 When the user types `/enrich-status`, run:
@@ -48,7 +56,7 @@ When starting a session in a project with `.planning/project-memory-context/`:
 2. If pending/stale entries exist, launch background enrichment: `{{PMC_BIN}} enrich .`
 3. Check `.planning/project-memory-context/enrichment/sync-manifest.json` for pending entries.
 4. If sync-manifest has pending entries, inform the user: "PMC has {n} pending sync operations. Run `/sync-context` to apply them."
-5. Search agent-memory with `query: "project context overview"` to fetch base context.
+5. Search agent-memory with `query: "project context overview"` and `tags: ["project-context"]` to fetch base context.
 6. Remind the user: "Use `/get-context <target>` for structural deep-dive before reading files."
 
 <!-- /pmc:init -->

package/templates/cursor/.cursorrules.snippet

@@ -2,6 +2,14 @@
 
 <!-- pmc:init -->
 
+PMC first, files second.
+
+Query PMC before reading more than 3 files. Prefer PMC for architecture, symbol lookup, dependencies, and callers before reading raw source.
+
+Available PMC MCP tools: `pmc_query_project`, `pmc_search_symbols`, `pmc_get_dependents`, `pmc_get_dependencies`.
+
+`/get-context` resolves a target (symbol, file, or query) and returns structural context. Accepts optional depth (compact|extended|deep) and focus (all|dependencies|callers|containment|impact).
+
 When the user types "/map-project", run:
 
 ```bash
@@ -11,7 +19,7 @@ When the user types "/map-project", run:
 When the user types "/get-context", run:
 
 ```bash
-{{PMC_BIN}} context . --refresh
+{{PMC_BIN}} context <target> [depth] [focus]
 ```
 
 When the user types "/enrich-status", run:
@@ -48,7 +56,7 @@ When starting a session in a project with `.planning/project-memory-context/`:
 2. If pending/stale entries exist, launch background enrichment: `{{PMC_BIN}} enrich .`
 3. Check `.planning/project-memory-context/enrichment/sync-manifest.json` for pending entries.
 4. If sync-manifest has pending entries, inform the user: "PMC has {n} pending sync operations. Run /sync-context to apply them."
-5. Search agent-memory with query "project context overview" to fetch base context.
+5. Search agent-memory with query "project context overview" and tags ["project-context"] to fetch base context.
 6. Remind the user: "Use /get-context <target> for structural deep-dive before reading files."
 
 <!-- /pmc:init -->

package/templates/opencode/commands/get-context.md

@@ -1,22 +1,39 @@
 ---
 name: get-context
-description: Retrieve structured project context from agent-memory for the current project.
-argument-hint: "<target>"
+description: Retrieve structured project context for a target (symbol, file, or query).
+argument-hint: "<target> [depth] [focus]"
 allowed-tools:
   - Bash
   - Read
 ---
 
 <objective>
-Retrieve and display structured project context from agent-memory. Use before reading files to get a structural overview.
+Retrieve and display structured project context for the given target. Use before reading files to get a structural overview.
 </objective>
 
 <execution>
-Run:
+Auto mode (recommended):
+
+```bash
+{{PMC_BIN}} context <target> [depth] [focus]
+```
+
+Explicit modes:
+
+```bash
+{{PMC_BIN}} context symbol <target> [depth] [focus]
+{{PMC_BIN}} context file <target> [depth] [focus]
+{{PMC_BIN}} context query <target> [depth] [focus]
+```
+
+Depths: compact (default), extended, deep.
+Focus modes: all (default), dependencies, callers, containment, impact.
+
+Repository refresh (legacy):
 
 ```bash
 {{PMC_BIN}} context . --refresh
 ```
 
-This materializes or refreshes the 9 base project-context memories and outputs a summary.
+This resets the 9 base project-context memories without a specific target.
 </execution>

package/templates/pmc-skill/SKILL.md

@@ -0,0 +1,34 @@
+# PMC-Aware Workflow
+
+PMC first, files second.
+
+Before reading more than 3 files, query PMC for structural context first. Use PMC to understand symbols, dependencies, and callers before falling back to raw file reads.
+
+## Rule of thumb
+
+- Query PMC before reading more than 3 files.
+- Prefer PMC summaries for architecture, dependencies, and symbol lookup.
+- Read source files after PMC when you need exact implementation details.
+
+## Available commands
+
+- `/map-project`
+- `/get-context`
+- `/enrich-status`
+- `/doctor`
+- `/init-project`
+- `/sync-context`
+- `/sanitize`
+
+- `/get-context <target> [depth] [focus]`—resolve a symbol, file, or query and return structural context
+
+## Available MCP tools
+
+- `pmc_query_project`
+- `pmc_search_symbols`
+- `pmc_get_dependents`
+- `pmc_get_dependencies`
+
+## Why this saves tokens
+
+PMC returns focused structural context, so the agent can avoid loading many full files into context. Querying graph-backed summaries first usually costs fewer tokens than broad file reads and helps reserve file inspection for the exact places that matter.