diff --git a/CHANGELOG.md b/CHANGELOG.md index 39169a5cd..4dc9d9881 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,8 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### New Features +- `codegraph_sessions` and `codegraph sessions` take `full` / `--full` to return each hit's whole stored passage instead of a 24-token snippet, up to 16,000 bytes in all; hits past the budget keep their snippet and the answer says how many. Snippets stay the default. + - Installers can verify daemon readiness and safely hand writer ownership across build promotion and rollback through a supported runtime-control API. - `codegraph_explore` now finds quoted prose in script strings and template text through a capped source scan, ignoring case and punctuation without requiring a re-index. diff --git a/README.md b/README.md index 57c1f1de5..a6011a56a 100644 --- a/README.md +++ b/README.md @@ -765,7 +765,7 @@ codegraph unlock [path] # Remove a stale lock file that's blocking ind codegraph query # Search symbols (--kind, --limit, --json) codegraph explore # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool) codegraph context # Context for a task: relevant symbols, relationships and code (--format markdown|json, --max-nodes, --no-code) -codegraph sessions # Search Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin, and Grok transcripts and commit messages for this project (--role, --since , --session, --any, --json; same output as codegraph_sessions) +codegraph sessions # Search Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin, and Grok transcripts and commit messages for this project (--role, --since , --session, --any, --full, --json; same output as codegraph_sessions) codegraph node # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node) codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json) codegraph callers # Find what calls a function/method (--limit, --json) @@ -816,7 +816,7 @@ When running as an MCP server, CodeGraph exposes **one tool for code** — `code | Tool | Purpose | |------|---------| | `codegraph_explore` | Answer almost any question in one call — "how does X work", a flow ("how does X reach Y"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus the call paths between them and a blast-radius summary. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. Name a file or symbol in the query to read its current line-numbered source, the same shape the Read tool gives you. | -| `codegraph_sessions` | Search this project's Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin, and Grok transcripts and its last 2000 git commit messages, including active sessions: prompts, replies, and compaction summaries, excluding tool traffic. Uses stemmed, BM25-ranked full-text search, stored locally in `.codegraph/sessions-v2.db` and refreshed for changed files on each call. Each hit includes its session (`claude:`, `codex:`, `cursor:`, `opencode:`, `agy:`, `devin:`, `grok:`, or `git:`), role, time, transcript path, and matching passage. Common words are dropped, and when too few passages hold every remaining word, passages holding some of them follow, marked. Harness-injected text (skill bodies, system reminders) is not indexed. Set `"sessions": false` in `codegraph.json` to opt out; `CODEGRAPH_SESSIONS_DIR` selects another Claude-format transcript directory exclusively. | +| `codegraph_sessions` | Search this project's Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin, and Grok transcripts and its last 2000 git commit messages, including active sessions: prompts, replies, and compaction summaries, excluding tool traffic. Uses stemmed, BM25-ranked full-text search, stored locally in `.codegraph/sessions-v2.db` and refreshed for changed files on each call. Each hit includes its session (`claude:`, `codex:`, `cursor:`, `opencode:`, `agy:`, `devin:`, `grok:`, or `git:`), role, time, transcript path, and matching passage; `full` returns each hit's whole stored passage instead of the snippet, up to 16,000 bytes in all, and later hits keep their snippet. Common words are dropped, and when too few passages hold every remaining word, passages holding some of them follow, marked. Harness-injected text (skill bodies, system reminders) is not indexed. Set `"sessions": false` in `codegraph.json` to opt out; `CODEGRAPH_SESSIONS_DIR` selects another Claude-format transcript directory exclusively. | The other tools (`codegraph_node`, `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore` (its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`), or use their CLI equivalents (`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`). diff --git a/__tests__/cli-sessions-command.test.ts b/__tests__/cli-sessions-command.test.ts index 342bbc387..e8587c429 100644 --- a/__tests__/cli-sessions-command.test.ts +++ b/__tests__/cli-sessions-command.test.ts @@ -86,6 +86,14 @@ describe('codegraph sessions — CLI command', () => { expect(any.fallback).toBeUndefined(); }); + it('--full prints the whole passage and --json carries it as text', () => { + const out = sessions(tempDir, transcripts, ['trailing', 'newlines', '--full']); + expect(out).toContain('> Trimming first keeps a trailing newline from failing the signature check.'); + const parsed = JSON.parse(sessions(tempDir, transcripts, ['trailing', 'newlines', '--full', '--json'])); + expect(parsed.hits[0].text).toBe('Trimming first keeps a trailing newline from failing the signature check.'); + expect(parsed.fullCut).toBe(0); + }); + it('a project without transcripts gets guidance, not an error', () => { const out = sessions(tempDir, undefined, ['anything']); expect(out).toMatch(/No agent-session transcripts to index/); diff --git a/__tests__/sessions-index.test.ts b/__tests__/sessions-index.test.ts index ee7ed22ef..be3a9b04f 100644 --- a/__tests__/sessions-index.test.ts +++ b/__tests__/sessions-index.test.ts @@ -32,6 +32,7 @@ import { querySessions, NoSessionsError, formatSessionHits, + FULL_PASSAGE_BUDGET, } from '../src/sessions'; import { clearProjectConfigCache } from '../src/project-config'; import { isInjectedDoc, slashCommandText, splitPassages, indexableDocs } from '../src/sessions/noise'; @@ -1225,3 +1226,54 @@ describe('repeat scans', () => { expect(unavailable).toEqual([path.join(root, 'brain') + path.sep]); }); }); + +describe('whole passages (full)', () => { + const store = (texts: string[]): string => { + const project = fixtureDir(); + fs.mkdirSync(path.join(project, '.codegraph')); + const transcripts = fixtureDir(); + writeJsonl(path.join(transcripts, 's1.jsonl'), texts.map((t) => user(t)), 1_700_000_000); + process.env.CODEGRAPH_SESSIONS_DIR = transcripts; + return project; + }; + + it('returns the stored passage beside the snippet only when asked, in the printed answer too', () => { + const tail = ' the second paragraph line explains the retry budget in detail and names the limit of three attempts.'; + const project = store([`Decision: keep write-time dedupe.\n\nThe table lists:\n| a | b |\n|---|---|${tail}`]); + const plain = querySessions(project, 'write-time dedupe'); + expect(plain.hits[0]!.text).toBeUndefined(); + expect(plain.fullCut).toBeUndefined(); + const full = querySessions(project, 'write-time dedupe', { full: true }); + expect(full.hits[0]!.text).toContain('| a | b |\n|---|---|'); + expect(full.hits[0]!.snippet).toBe(plain.hits[0]!.snippet); + expect(full.fullCut).toBe(0); + const printed = formatSessionHits('write-time dedupe', full); + expect(printed).toContain('> | a | b |\n> |---|---|'); + expect(printed).toContain('> Decision: keep write-time dedupe.'); + expect(formatSessionHits('write-time dedupe', plain)).not.toContain('> | a | b |'); + }); + + it('spends one byte budget in rank order and says how many hits fell back to the snippet', () => { + const body = (i: number) => `Note ${i} on budgetword: ${`alpha${i} beta${i} gamma${i} `.repeat(160)}`.slice(0, 3000); + const project = store(Array.from({ length: 7 }, (_, i) => body(i))); + const result = querySessions(project, 'budgetword', { full: true }); + expect(result.hits).toHaveLength(7); + const whole = result.hits.filter((h) => h.text !== undefined); + const bytes = whole.reduce((n, h) => n + Buffer.byteLength(h.text!), 0); + expect(bytes).toBeLessThanOrEqual(FULL_PASSAGE_BUDGET); + expect(whole.length).toBeGreaterThan(0); + expect(whole.length).toBeLessThan(7); + expect(result.fullCut).toBe(7 - whole.length); + // Whole passages are a prefix of the ranking: a smaller later hit never jumps the queue. + expect(result.hits.slice(0, whole.length).every((h) => h.text !== undefined)).toBe(true); + const printed = formatSessionHits('budgetword', result); + expect(printed).toContain(`Whole passages are limited to 16,000 bytes in all: the last ${result.fullCut} hits show only the matching snippet.`); + }); + + it('keeps the role filter and the one-hit wording', () => { + const project = store([`Decision: keep write-time dedupe. ${'x'.repeat(2000)}`.replace(/x/g, 'padding ')]); + const hit = querySessions(project, 'write-time dedupe', { full: true, role: 'user' }); + expect(hit.hits).toHaveLength(1); + expect(querySessions(project, 'write-time dedupe', { full: true, role: 'assistant' }).hits).toEqual([]); + }); +}); diff --git a/site/src/content/docs/reference/cli.md b/site/src/content/docs/reference/cli.md index fbb0cbcbf..d1811c2ed 100644 --- a/site/src/content/docs/reference/cli.md +++ b/site/src/content/docs/reference/cli.md @@ -17,7 +17,7 @@ codegraph unlock [path] # Remove a stale lock file that's blocking ind codegraph query # Search symbols (--kind, --limit, --json) codegraph explore # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool) codegraph context # Context for a task: relevant symbols, relationships and code (--format markdown|json, --max-nodes, --no-code) -codegraph sessions # Search this project's earlier agent sessions (--role, --since , --session, --any, --json; same output as codegraph_sessions) +codegraph sessions # Search this project's earlier agent sessions (--role, --since , --session, --any, --full, --json; same output as codegraph_sessions) codegraph node # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node) codegraph files [path] # Show file structure (--format, --filter, --pattern, --max-depth, --json) codegraph callers # Find what calls a function/method (--limit, --json) diff --git a/site/src/content/docs/reference/mcp-server.md b/site/src/content/docs/reference/mcp-server.md index 8da9299ab..4e7bc38bc 100644 --- a/site/src/content/docs/reference/mcp-server.md +++ b/site/src/content/docs/reference/mcp-server.md @@ -17,7 +17,7 @@ By default the server exposes `codegraph_explore` for code and `codegraph_sessio `codegraph_explore` It's Read-equivalent: give it a natural-language question or a bag of symbol and file names, and it returns the **verbatim, line-numbered source** of the relevant symbols grouped by file — the same shape the `Read` tool gives you — plus the call paths between them (including dynamic-dispatch hops like callbacks, React re-render, and JSX children that grep can't follow) and a blast-radius summary of what depends on them. One call usually answers the whole question. When a complete scan of indexed source finishes without skipped files, the summary lists requested names it could not find, helping catch a guessed name. -`codegraph_sessions` searches this project's earlier agent sessions (Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin and Grok transcripts, plus git commit messages) for what a previous session asked, decided or tried. It answers "why is X like this" questions, which the code graph cannot. Set `"sessions": false` in `codegraph.json` to turn it off. +`codegraph_sessions` searches this project's earlier agent sessions (Claude Code, Codex, Cursor/T3, OpenCode, AGY, Devin and Grok transcripts, plus git commit messages) for what a previous session asked, decided or tried. It answers "why is X like this" questions, which the code graph cannot. A hit shows a short snippet; pass `full` (CLI: `--full`) to get each hit's whole stored passage instead, up to 16,000 bytes in all, with later hits keeping their snippet. Set `"sessions": false` in `codegraph.json` to turn it off. T3-hosted provider transcripts can appear in session search; CodeGraph does not read the T3 database. The source includes a disabled-by-default offline Codex metadata prototype that associates caller-supplied T3 titles and thread links with existing hits. It has no CLI or MCP caller, adds no searchable prose and leaves provider titles, keys and ranking unchanged. diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts index d2334a520..8eada08b8 100644 --- a/src/bin/codegraph.ts +++ b/src/bin/codegraph.ts @@ -1502,8 +1502,9 @@ program .option('--since ', 'Only docs from the last N days') .option('--session ', 'Only one session (id prefix)') .option('--any', 'OR the words instead of requiring all of them') + .option('--full', 'Show each hit\'s whole passage (16,000 bytes in all) instead of a snippet') .option('-j, --json', 'Output as JSON') - .action(async (words: string[], options: { path?: string; limit?: string; role?: string; since?: string; session?: string; any?: boolean; json?: boolean }) => { + .action(async (words: string[], options: { path?: string; limit?: string; role?: string; since?: string; session?: string; any?: boolean; full?: boolean; json?: boolean }) => { const projectPath = resolveProjectPath(options.path); try { if (!isInitialized(projectPath)) { @@ -1521,6 +1522,7 @@ program sinceIso: sinceDays > 0 ? new Date(Date.now() - sinceDays * 86_400_000).toISOString() : undefined, session: options.session, any: options.any, + full: options.full, }); } catch (err) { if (err instanceof NoSessionsError) { diff --git a/src/mcp/server-instructions.ts b/src/mcp/server-instructions.ts index c79467b3f..9519b2951 100644 --- a/src/mcp/server-instructions.ts +++ b/src/mcp/server-instructions.ts @@ -54,7 +54,7 @@ against dozens of greps and reads. - **"How does X reach/become Y? / the flow / the path from X to Y"** → \`codegraph_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source. - **Reading or editing a file/symbol you can name** → put its name or file path in the \`codegraph_explore\` query — it returns that current line-numbered source (safe to \`Edit\` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call. - Name what you need as precisely as you can — a receiver type with its method, a constant or variable, a callable, or a file path. Named items are funded first within the output cap; an oversized body comes back as a bounded excerpt whose gap markers name what was left out. Treat returned ranges as already Read; for trimmed parts, query the names in the gap marker. -- **"Why is this like this? What did the last session decide / try / get told about X?"** → \`codegraph_sessions\` with a few words. It searches the prose of this project's earlier Claude Code, Codex, Cursor/T3, OpenCode, AGY, and Devin sessions (prompts, replies, compaction summaries — stemmed, ranked) and names the session each hit came from (\`claude:\`, \`codex:\`, \`cursor:\`, \`opencode:\`, \`agy:\`, \`devin:\`). History and rationale live there, not in the code. +- **"Why is this like this? What did the last session decide / try / get told about X?"** → \`codegraph_sessions\` with a few words. It searches the prose of this project's earlier Claude Code, Codex, Cursor/T3, OpenCode, AGY, and Devin sessions (prompts, replies, compaction summaries — stemmed, ranked) and names the session each hit came from (\`claude:\`, \`codex:\`, \`cursor:\`, \`opencode:\`, \`agy:\`, \`devin:\`). History and rationale live there, not in the code. A hit is a short snippet; pass \`full: true\` to read each hit's whole passage in the same call (up to 16,000 bytes in all). - **Need more?** Call \`codegraph_explore\` again with more specific names — treat the source it returns as already Read. Suggested call counts are advisory only, NOT a quota; extra calls are never rejected or rate-limited. - Qualified symbol names accept dots, \`::\`, or slashes, including containers whose names contain dots (for example, \`AppWeb.Format.group\`). - Named-symbol call paths require exact matches; partial or mistyped names are never silently substituted as flow endpoints. If a graph query reports a missing symbol with did-you-mean suggestions, query the suggested name explicitly. diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts index 31766409f..99ab9517e 100644 --- a/src/mcp/tools.ts +++ b/src/mcp/tools.ts @@ -2058,6 +2058,11 @@ export const tools: ToolDefinition[] = [ description: 'OR the words instead of requiring all of them (default: false).', default: false, }, + full: { + type: 'boolean', + description: 'Return each hit\'s whole passage instead of a short snippet, up to 16,000 bytes in all; later hits keep their snippet (default: false).', + default: false, + }, projectPath: projectPathProperty, }, required: ['query'], @@ -4580,6 +4585,7 @@ export class ToolHandler { sinceIso: sinceDays > 0 ? new Date(Date.now() - sinceDays * 86_400_000).toISOString() : undefined, session, any: args.any === true, + full: args.full === true, }); return this.textResult(formatSessionHits(query, result)); } catch (err) { diff --git a/src/sessions/index.ts b/src/sessions/index.ts index 6af39d662..1e0a9b080 100644 --- a/src/sessions/index.ts +++ b/src/sessions/index.ts @@ -104,8 +104,13 @@ export interface SessionHit { score: number; /** Holds only some of the query words: the every-word query ran short. */ partial?: boolean; + /** The whole stored passage; set only by a `full` search, within {@link FULL_PASSAGE_BUDGET}. */ + text?: string; } +/** Bytes of passage text one `full` search returns in all; hits past it keep their snippet. */ +export const FULL_PASSAGE_BUDGET = 16_000; + export interface SessionSearchOptions { /** Max hits (default 10). */ limit?: number; @@ -117,6 +122,8 @@ export interface SessionSearchOptions { session?: string; /** OR the words instead of ANDing them. */ any?: boolean; + /** Return each hit's whole passage (see {@link FULL_PASSAGE_BUDGET}) beside its snippet. */ + full?: boolean; } /** @@ -490,7 +497,8 @@ export class SessionsIndex { if (seen.has(key) || seen.has(`#${id}`)) continue; seen.add(key); seen.add(`#${id}`); - hits.push(any && !opts.any ? { ...hit, partial: true } : hit); + const found = opts.full ? { ...hit, text } : hit; + hits.push(any && !opts.any ? { ...found, partial: true } : found); if (hits.length === limit) break; } } @@ -623,6 +631,8 @@ export interface SessionsQueryResult { hits: SessionHit[]; /** True when no passage held every word and the hits match any of them. */ fallback?: boolean; + /** A `full` search: how many hits lost their whole passage to the byte budget and keep only the snippet. */ + fullCut?: number; } /** @@ -642,7 +652,7 @@ export function querySessions( if (override) { if (!fs.existsSync(override)) throw new NoSessionsError(projectRoot); const stats = index.refreshListed(walkJsonl(override), (file) => loadHosted(file, 'claude')); - return result(stats, index.search(query, opts)); + return result(stats, index.search(query, opts), opts); } const roots = index.rememberRoots(projectWorktreeRoots(projectRoot)); const unavailable: UnavailableStores = []; @@ -654,15 +664,36 @@ export function querySessions( throw new NoSessionsError(projectRoot); } const stats = index.refreshRecords(records, unavailable); - return result(stats, index.search(query, opts)); + return result(stats, index.search(query, opts), opts); } finally { index.close(); } } -function result(index: SessionsIndexStats, found: ReturnType): SessionsQueryResult { +/** Keeps whole passages in rank order until the budget is spent; later hits fall back to their snippet. */ +function withinPassageBudget(hits: SessionHit[]): number { + let spent = 0; + let cut = 0; + for (const hit of hits) { + if (hit.text === undefined) continue; + spent += Buffer.byteLength(hit.text); + if (cut > 0 || spent > FULL_PASSAGE_BUDGET) { + delete hit.text; + cut++; + } + } + return cut; +} + +function result( + index: SessionsIndexStats, + found: ReturnType, + opts: SessionSearchOptions, +): SessionsQueryResult { const hits = [...found]; - return found.fallback ? { index, hits, fallback: true } : { index, hits }; + const out: SessionsQueryResult = found.fallback ? { index, hits, fallback: true } : { index, hits }; + if (opts.full) out.fullCut = withinPassageBudget(hits); + return out; } /** @@ -752,9 +783,13 @@ export function formatSessionHits(query: string, result: SessionsQueryResult): s const title = h.title ? ` · ${h.title}` : ''; lines.push(`## ${h.session}${title}`); lines.push(`${h.role} · ${h.ts} · ${h.file}${h.partial && !result.fallback ? ' · some words' : ''}`); - lines.push(h.snippet.replace(/\s+/g, ' ').trim()); + if (h.text === undefined) lines.push(h.snippet.replace(/\s+/g, ' ').trim()); + else lines.push(...h.text.split('\n').map((l) => `> ${l}`)); lines.push(''); } + if (result.fullCut) { + lines.push(`Whole passages are limited to ${FULL_PASSAGE_BUDGET.toLocaleString('en-US')} bytes in all: the last ${result.fullCut} hit${result.fullCut === 1 ? '' : 's'} show only the matching snippet. Narrow the search (--role, --session, a smaller limit) to read them whole.`, ''); + } lines.push('A hit names its session id (`claude:`, `codex:`, `cursor:`, `opencode:`, `agy:`, `devin:`, `grok:`, or `git:` for commit messages); the path after the timestamp is the transcript to read when the snippet is not enough.'); return lines.join('\n'); }