memonaut-pi 0.1.0

package/src/index.ts

@@ -0,0 +1,157 @@
+import {silenceSqliteWarning} from 'memonaut';
+import {Type} from 'typebox';
+import type {
+	ExtensionAPI,
+	ToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import {runSearch, runSql, runThread, type ToolOutcome} from './queries.js';
+
+/**
+ * memonaut as a pi extension: three read-only tools over the transcript index.
+ *
+ * Scope is GLOBAL by design. An agent asked "what did we decide about X" usually
+ * means a decision taken in another repo on another day, so restricting to the
+ * current project by default would quietly make the tool useless for its main
+ * job. The filters are how you narrow, and the descriptions teach that.
+ *
+ * Transcripts matched by the config's `private` globs are never returned. That
+ * list exists precisely to draw this line, and no tool parameter can cross it.
+ */
+silenceSqliteWarning();
+
+function result(outcome: ToolOutcome) {
+	return {
+		content: [{type: 'text' as const, text: outcome.text}],
+		details: outcome.details,
+		...(outcome.isError ? {isError: true} : {}),
+	};
+}
+
+export default function extension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: 'recall_search',
+		label: 'Recall Search',
+		description:
+			'Search PAST conversation transcripts (previous sessions with this user, across every project) ' +
+			'for what was said, decided, tried or rejected. Use recall_search when the user refers to ' +
+			'something from an earlier session ("what did we decide about X", "we discussed this before", ' +
+			'"the approach we tried last month"), when you need context that is not in the current ' +
+			'conversation, or before redoing analysis that may already exist. It searches ALL projects by ' +
+			'default: pass project or cwd to narrow, since to bound the time range. The query is an FTS5 ' +
+			'expression: bare words are ANDed, "quoted phrases" match in order, OR and NOT work, NEAR(a b, 5) ' +
+			'matches within a window, and a trailing * is a prefix. Results are grouped per conversation; ' +
+			'when a match falls in history shared by several forked conversations, every fork that inherited ' +
+			'it is listed, newest activity first, so you can pick the right continuation. This searches ' +
+			'transcripts only, never the codebase: use grep for code.',
+		promptSnippet:
+			'Search past conversation transcripts across all projects for earlier decisions and context',
+		promptGuidelines: [
+			'Use recall_search when the user refers to an earlier session or a past decision, rather than guessing or asking them to repeat themselves.',
+			'recall_search covers all projects by default; pass project or since to narrow rather than assuming the current repo.',
+		],
+		parameters: Type.Object({
+			query: Type.String({
+				description:
+					'FTS5 query. Bare words are ANDed; use "quotes" for a phrase, OR, NOT, NEAR(a b, 5), prefix*.',
+			}),
+			project: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						'Narrow to project names (the last path segment of the working directory), e.g. ["wherever"].',
+				}),
+			),
+			cwd: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						'Narrow to working-directory globs, e.g. ["~/dev/**/wherever"].',
+				}),
+			),
+			role: Type.Optional(
+				Type.Array(Type.String(), {
+					description:
+						'Narrow by message role: user, assistant, toolResult, bashExecution.',
+				}),
+			),
+			tool: Type.Optional(
+				Type.Array(Type.String(), {
+					description: 'Narrow to messages involving these tool names.',
+				}),
+			),
+			since: Type.Optional(
+				Type.String({description: 'ISO date lower bound, e.g. "2026-07-01".'}),
+			),
+			until: Type.Optional(Type.String({description: 'ISO date upper bound.'})),
+			limit: Type.Optional(
+				Type.Number({
+					description: 'Conversations to return, 1-50 (default 8).',
+				}),
+			),
+			threads: Type.Optional(
+				Type.Number({
+					description: 'Forked threads listed per result, 1-25 (default 3).',
+				}),
+			),
+		}),
+		async execute(_toolCallId: string, params: Record<string, unknown>) {
+			return result(
+				runSearch(params as unknown as Parameters<typeof runSearch>[0]),
+			);
+		},
+	} as unknown as ToolDefinition);
+
+	pi.registerTool({
+		name: 'recall_thread',
+		label: 'Recall Thread',
+		description:
+			'Read a past conversation in order, given the thread number reported by recall_search. Use it ' +
+			'after a search when the snippet is not enough and you need what was actually said around it. ' +
+			'Paginate with from/limit; entries marked "inherited" came from a conversation this one was ' +
+			'forked out of. Tool output is stored truncated or omitted, so this shows the discussion, not ' +
+			'full command output.',
+		promptSnippet: 'Read a past conversation found via recall_search',
+		promptGuidelines: [
+			'Use recall_thread to read the surrounding discussion after recall_search returns a promising snippet, instead of guessing from the snippet alone.',
+		],
+		parameters: Type.Object({
+			ref: Type.String({
+				description:
+					'Thread number from recall_search (a session uuid prefix or name also works).',
+			}),
+			from: Type.Optional(
+				Type.Number({description: 'Entry index to start at (default 0).'}),
+			),
+			limit: Type.Optional(
+				Type.Number({description: 'Entries to return, 1-200 (default 30).'}),
+			),
+		}),
+		async execute(_toolCallId: string, params: Record<string, unknown>) {
+			return result(
+				runThread(params as unknown as Parameters<typeof runThread>[0]),
+			);
+		},
+	} as unknown as ToolDefinition);
+
+	pi.registerTool({
+		name: 'recall_sql',
+		label: 'Recall SQL',
+		description:
+			'Run a read-only SQL query against the transcript index. Use recall_sql for questions that are ' +
+			'aggregates rather than searches ("which projects did I work on in July", "how many sessions ' +
+			'mention this tool", "when did this conversation start"). Tables: file(id, path, cwd, project, ' +
+			'name, parent_id, lineage_id, private, started, last_activity, entry_count), entry(id, lineage_id, ' +
+			'entry_key, role, tool, ts), membership(entry_id, file_id, seq), chunk(entry_id, kind, text), and ' +
+			'the FTS index chunk_fts. Prefer recall_search for anything that is really a text search.',
+		promptSnippet: 'Run a read-only SQL aggregate over the conversation index',
+		promptGuidelines: [
+			'Use recall_sql for counting and grouping questions about past sessions, and recall_search for finding what was said.',
+		],
+		parameters: Type.Object({
+			sql: Type.String({
+				description: 'A single read-only SELECT. Always include a LIMIT.',
+			}),
+		}),
+		async execute(_toolCallId: string, params: Record<string, unknown>) {
+			return result(runSql(String((params as {sql?: string}).sql ?? '')));
+		},
+	} as unknown as ToolDefinition);
+}

package/src/queries.ts

@@ -0,0 +1,323 @@
+import {
+	indexStats,
+	loadConfig,
+	openDb,
+	readThread,
+	relativeTime,
+	resolveThread,
+	search,
+	syncIfStale,
+	tildify,
+	type ChunkKind,
+	type Config,
+	type SearchHit,
+} from 'memonaut';
+
+/**
+ * Agent-facing query layer.
+ *
+ * Deliberately free of any pi import so it can be tested (and reused) on its
+ * own. The pi extension in `index.ts` is a thin wrapper that maps tool
+ * parameters onto these functions.
+ */
+
+export interface ToolOutcome {
+	text: string;
+	details?: Record<string, unknown>;
+	isError?: boolean;
+}
+
+export interface ToolOptions {
+	/** Hard cap on returned characters, so one call cannot eat the context. */
+	maxChars?: number;
+	/** Skip the incremental catch-up if the index was synced this recently. */
+	syncTtlMs?: number;
+	config?: Config;
+	now?: number;
+}
+
+const DEFAULT_MAX_CHARS = 6000;
+
+function options(
+	opts: ToolOptions,
+): Required<Pick<ToolOptions, 'maxChars' | 'syncTtlMs'>> & {config: Config} {
+	const config = opts.config ?? loadConfig();
+	return {
+		maxChars:
+			opts.maxChars ??
+			Number(process.env.MEMONAUT_TOOL_MAX_CHARS ?? DEFAULT_MAX_CHARS),
+		syncTtlMs:
+			opts.syncTtlMs ?? Number(process.env.MEMONAUT_TOOL_SYNC_TTL_MS ?? 15_000),
+		config,
+	};
+}
+
+function missingIndex(config: Config): ToolOutcome {
+	return {
+		isError: true,
+		text:
+			`No transcript index exists yet at ${tildify(config.dbPath)}.\n` +
+			'Tell the user to run `recall index` once (it takes well under a minute), ' +
+			'or run it yourself with bash if they have already agreed to that.',
+	};
+}
+
+/** Strip FTS5 highlight markers down to something readable in a tool result. */
+function cleanSnippet(snippet: string): string {
+	return snippet
+		.replace(/\s+/g, ' ')
+		.replace(/\u0001/g, '<<')
+		.replace(/\u0002/g, '>>')
+		.trim();
+}
+
+function truncate(lines: string[], maxChars: number, tail: string): string {
+	const out: string[] = [];
+	let used = 0;
+	for (const line of lines) {
+		if (used + line.length + 1 > maxChars) {
+			out.push(`… output truncated. ${tail}`);
+			break;
+		}
+		out.push(line);
+		used += line.length + 1;
+	}
+	return out.join('\n');
+}
+
+export interface SearchParams {
+	query: string;
+	project?: string[];
+	cwd?: string[];
+	role?: string[];
+	tool?: string[];
+	kind?: string[];
+	since?: string;
+	until?: string;
+	limit?: number;
+	threads?: number;
+}
+
+function renderHit(hit: SearchHit, position: number, now: number): string[] {
+	const primary = hit.threads[0];
+	const lines: string[] = [];
+	const when = (hit.ts ?? '').slice(0, 10);
+	lines.push(
+		`[${position}] ${primary?.project ?? '?'} · ${hit.role}${hit.tool ? `:${hit.tool}` : ''} · ${when} · thread ${primary?.fileId ?? '?'}`,
+	);
+	lines.push(`    ${cleanSnippet(hit.snippet)}`);
+	if (hit.threadTotal > 1) {
+		// The entry lives in shared history: every fork that inherited it is a
+		// real, separate continuation, and which one to resume is the agent's
+		// decision to surface, not ours to silently make.
+		const shown = hit.threads
+			.map(
+				(t) =>
+					`${t.fileId} (last ${relativeTime(t.lastActivity, now)}, +${t.after} after)`,
+			)
+			.join(', ');
+		const hidden = hit.threadTotal - hit.threads.length;
+		lines.push(
+			`    shared history: ${hit.threadTotal} threads carry this message: ${shown}` +
+				(hidden > 0 ? `, +${hidden} more` : ''),
+		);
+	}
+	if (hit.otherHits > 0)
+		lines.push(
+			`    ${hit.otherHits} further match(es) in the same conversation`,
+		);
+	return lines;
+}
+
+export function runSearch(
+	params: SearchParams,
+	opts: ToolOptions = {},
+): ToolOutcome {
+	const {config, maxChars, syncTtlMs} = options(opts);
+	const now = opts.now ?? Date.now();
+	try {
+		syncIfStale(config, syncTtlMs);
+	} catch {
+		return missingIndex(config);
+	}
+
+	const db = openDb(config.dbPath, {readOnly: true});
+	try {
+		const limit = Math.min(Math.max(params.limit ?? 8, 1), 50);
+		const outcome = search(
+			db,
+			{
+				text: params.query,
+				project: params.project,
+				cwd: params.cwd,
+				role: params.role,
+				tool: params.tool,
+				kind: params.kind as ChunkKind[] | undefined,
+				since: params.since,
+				until: params.until,
+				limit,
+				threadLimit: Math.min(Math.max(params.threads ?? 3, 1), 25),
+				// Private transcripts are never exposed here. That is the entire
+				// point of the config's `private` list: things the user is willing
+				// to index for themselves but not to hand to an agent.
+				includePrivate: false,
+			},
+			now,
+		);
+
+		if (outcome.hits.length === 0) {
+			const stats = indexStats(db);
+			return {
+				text:
+					`No matches for: ${outcome.usedQuery}\n` +
+					`Searched ${stats.files} conversations across ${stats.projects} projects.\n` +
+					'Try fewer words, a quoted phrase, OR between alternatives, or drop the filters.',
+				details: {hits: 0, usedQuery: outcome.usedQuery},
+			};
+		}
+
+		const scope = params.project?.length
+			? `project ${params.project.join(', ')}`
+			: params.cwd?.length
+				? `cwd ${params.cwd.join(', ')}`
+				: 'all projects';
+		const header = `${outcome.hits.length} result(s) · query ${outcome.usedQuery} · scope: ${scope}`;
+		const lines = [header, ''];
+		outcome.hits.forEach((hit, i) => lines.push(...renderHit(hit, i + 1, now)));
+		lines.push('');
+		lines.push('Use recall_thread with a thread number to read one in full.');
+
+		return {
+			text: truncate(
+				lines,
+				maxChars,
+				'Narrow with project/since or lower limit.',
+			),
+			details: {
+				usedQuery: outcome.usedQuery,
+				quotedFallback: outcome.quotedFallback,
+				hits: outcome.hits.map((h) => ({
+					role: h.role,
+					ts: h.ts,
+					threadTotal: h.threadTotal,
+					threads: h.threads.map((t) => ({
+						id: t.fileId,
+						project: t.project,
+						lastActivity: t.lastActivity,
+					})),
+				})),
+			},
+		};
+	} finally {
+		db.close();
+	}
+}
+
+export interface ThreadParams {
+	ref: string;
+	from?: number;
+	limit?: number;
+}
+
+export function runThread(
+	params: ThreadParams,
+	opts: ToolOptions = {},
+): ToolOutcome {
+	const {config, maxChars} = options(opts);
+	let db;
+	try {
+		db = openDb(config.dbPath, {readOnly: true});
+	} catch {
+		return missingIndex(config);
+	}
+	try {
+		const thread = resolveThread(db, String(params.ref));
+		if (!thread)
+			return {isError: true, text: `No conversation matches "${params.ref}".`};
+		if (thread.private) {
+			// Resolvable by id, but explicitly withheld: say so rather than
+			// pretending it does not exist, so the user can lift it if they meant to.
+			return {
+				isError: true,
+				text: `Conversation ${params.ref} is marked private in the memonaut config and is not readable by tools.`,
+			};
+		}
+
+		const from = Math.max(params.from ?? 0, 0);
+		const limit = Math.min(Math.max(params.limit ?? 30, 1), 200);
+		const entries = readThread(db, Number(thread.id), from, limit);
+
+		const lines = [
+			`thread ${thread.id} · ${thread.name ?? thread.project ?? '?'} · ${thread.entry_count} entries · last activity ${thread.last_activity ?? '?'}`,
+			`cwd: ${thread.cwd ?? '?'}`,
+			'',
+		];
+		for (const entry of entries) {
+			const label = `${entry.seq} ${entry.role}${entry.tool ? `:${entry.tool}` : ''}${entry.shared ? ' (inherited from an earlier conversation)' : ''}`;
+			lines.push(label);
+			for (const text of entry.texts)
+				lines.push(
+					`    [${text.kind}] ${text.text.replace(/\s+/g, ' ').slice(0, 1200)}`,
+				);
+		}
+		const end = from + entries.length;
+		if (end < Number(thread.entry_count)) {
+			lines.push('');
+			lines.push(
+				`(showing ${from}-${end} of ${thread.entry_count}; call again with from=${end} to continue)`,
+			);
+		}
+
+		return {
+			text: truncate(
+				lines,
+				maxChars,
+				`Call again with from=${from + Math.floor(limit / 2)} and a smaller limit.`,
+			),
+			details: {
+				threadId: thread.id,
+				from,
+				count: entries.length,
+				total: thread.entry_count,
+			},
+		};
+	} finally {
+		db?.close();
+	}
+}
+
+export function runSql(sql: string, opts: ToolOptions = {}): ToolOutcome {
+	const {config, maxChars} = options(opts);
+	let db;
+	try {
+		db = openDb(config.dbPath, {readOnly: true});
+	} catch {
+		return missingIndex(config);
+	}
+	try {
+		const rows = db.prepare(sql).all() as unknown as Array<
+			Record<string, unknown>
+		>;
+		if (rows.length === 0) return {text: '(no rows)', details: {rows: 0}};
+		const lines = rows.slice(0, 200).map((row) => JSON.stringify(row));
+		return {
+			text: truncate(
+				[`${rows.length} row(s):`, ...lines],
+				maxChars,
+				'Add a LIMIT or aggregate instead.',
+			),
+			details: {rows: rows.length},
+		};
+	} catch (err) {
+		return {
+			isError: true,
+			text:
+				`SQL failed: ${(err as Error).message}\n` +
+				'Tables: file(id, path, cwd, project, name, parent_id, lineage_id, private, started, last_activity, entry_count), ' +
+				'entry(id, lineage_id, entry_key, role, tool, ts), membership(entry_id, file_id, seq), chunk(entry_id, kind, text). ' +
+				'The connection is read-only.',
+		};
+	} finally {
+		db?.close();
+	}
+}