memonaut 0.0.0 → 0.1.0

package/src/cli-main.ts

@@ -0,0 +1,475 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseArgs} from 'node:util';
+import {loadConfig, writeStarterConfig, type Config} from './config.js';
+import {getMeta, openDb} from './db.js';
+import {
+	colorsEnabled,
+	makeStyle,
+	renderHit,
+	renderTable,
+	relativeTime,
+	tildify,
+} from './format.js';
+import {index} from './indexer.js';
+import {TIERS, type ChunkKind, type Tier} from './model.js';
+import {readRawEntry} from './pi-source.js';
+import {indexStats, readThread, resolveThread, search} from './search.js';
+
+const USAGE = `memonaut — search your agent conversation transcripts
+
+USAGE
+  recall <command> [options]
+
+COMMANDS
+  index                  Bring the index up to date (incremental by default)
+  search <query...>      Search transcripts, grouped by fork lineage
+  show <ref>             Print a thread (file id, session uuid prefix, name or path)
+  sql <query>            Run a read-only SQL query against the index
+  stats                  Summarise what is indexed
+  config                 Show config paths, or write a starter config
+
+SEARCH OPTIONS
+  --cwd <glob>           Filter by working directory (repeatable, globs, ~ ok)
+  --project <name>       Filter by project (last segment of the cwd, repeatable)
+  --role <role>          user | assistant | toolResult | bashExecution | ... (repeatable)
+  --tool <name>          Filter by tool name (repeatable)
+  --kind <kind>          user | assistant | thinking | toolCall | toolResult | bash | summary | name
+  --since <when>         30d, 6h, 2w, or an ISO date
+  --until <when>         Same forms as --since
+  --limit <n>            Result groups (default 20)
+  --threads <n|all>      Threads shown per group (default 3)
+  --private              Include transcripts matched by the config's private globs
+  --raw                  Pass the query to FTS5 verbatim (no quoting fallback)
+  --no-recency           Rank on bm25 x kind weight only
+  --path                 Show full transcript paths
+  --json                 Machine-readable output
+  --no-sync              Skip the incremental catch-up before querying
+
+INDEX OPTIONS
+  --full                 Rebuild from scratch
+  --tier <t>             slim | default | full (overrides config for this run)
+  --quiet                No progress output
+
+QUERY SYNTAX
+  The query is an FTS5 MATCH expression: bare words are ANDed, "quoted phrases"
+  match in order, OR / NOT / NEAR(a b, 5) work, and trailing * is a prefix.
+  If that fails to parse, the query is retried as quoted literal tokens.
+
+EXAMPLES
+  recall search steering queue --project wherever --since 30d
+  recall search '"fork point" OR parentSession' --threads all
+  recall search --tool bash --kind bash 'fuser -k'
+  recall sql "select project, count(*) n from file group by 1 order by n desc limit 10"
+`;
+
+function fail(message: string): never {
+	process.stderr.write(`recall: ${message}\n`);
+	process.exit(1);
+}
+
+function version(): string {
+	try {
+		const here = path.dirname(fileURLToPath(import.meta.url));
+		for (const candidate of [
+			path.join(here, '../package.json'),
+			path.join(here, '../../package.json'),
+		]) {
+			if (fs.existsSync(candidate)) {
+				return (
+					(JSON.parse(fs.readFileSync(candidate, 'utf8')) as {version?: string})
+						.version ?? '0.0.0'
+				);
+			}
+		}
+	} catch {
+		/* ignore */
+	}
+	return '0.0.0';
+}
+
+/** Accept `30d`, `6h`, `2w`, `3mo`, or anything Date can parse. */
+function parseWhen(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const m = /^(\d+)(mo|[smhdwy])$/.exec(value.trim());
+	if (m) {
+		const n = Number(m[1]);
+		const unit = m[2];
+		const ms =
+			unit === 's'
+				? 1000
+				: unit === 'm'
+					? 60_000
+					: unit === 'h'
+						? 3_600_000
+						: unit === 'd'
+							? 86_400_000
+							: unit === 'w'
+								? 604_800_000
+								: unit === 'mo'
+									? 2_592_000_000
+									: 31_536_000_000;
+		return new Date(Date.now() - n * ms).toISOString();
+	}
+	const parsed = Date.parse(value);
+	if (Number.isNaN(parsed)) fail(`cannot understand time "${value}"`);
+	return new Date(parsed).toISOString();
+}
+
+function withTier(config: Config, tier: string | undefined): Config {
+	if (!tier) return config;
+	if (!TIERS.includes(tier as Tier))
+		fail(`unknown tier "${tier}" (expected ${TIERS.join(', ')})`);
+	return {...config, tier: tier as Tier};
+}
+
+/** Cheap incremental catch-up so a query is never answered from a stale index. */
+function sync(config: Config, quiet: boolean): void {
+	if (!fs.existsSync(config.dbPath)) {
+		fail(`no index at ${tildify(config.dbPath)}. Run \`recall index\` first.`);
+	}
+	const stats = index({config, onProgress: () => {}});
+	if (!quiet && stats.filesIndexed > 0) {
+		process.stderr.write(
+			`recall: synced ${stats.filesIndexed} transcript(s) in ${stats.durationMs}ms\n`,
+		);
+	}
+}
+
+function cmdIndex(argv: string[]): void {
+	const {values} = parseArgs({
+		args: argv,
+		options: {
+			full: {type: 'boolean', default: false},
+			tier: {type: 'string'},
+			quiet: {type: 'boolean', default: false},
+			json: {type: 'boolean', default: false},
+		},
+		allowPositionals: false,
+	});
+	const config = withTier(loadConfig(), values.tier as string | undefined);
+	const quiet = Boolean(values.quiet) || Boolean(values.json);
+	let lastLine = 0;
+	const stats = index({
+		config,
+		full: Boolean(values.full),
+		onProgress: (p) => {
+			if (quiet || !process.stderr.isTTY) return;
+			const now = Date.now();
+			if (now - lastLine < 100) return;
+			lastLine = now;
+			process.stderr.write(`\r${p.phase} ${p.done}/${p.total}\u001b[K`);
+		},
+	});
+	if (!quiet && process.stderr.isTTY) process.stderr.write('\r\u001b[K');
+	if (values.json) {
+		process.stdout.write(JSON.stringify(stats, null, 2) + '\n');
+		return;
+	}
+	const seconds = (stats.durationMs / 1000).toFixed(1);
+	process.stdout.write(
+		[
+			`indexed ${stats.filesIndexed} transcript(s) in ${seconds}s${stats.fullRebuild ? ' (full rebuild)' : ''}`,
+			`  seen ${stats.filesSeen} · skipped ${stats.filesSkipped} · appended ${stats.filesAppended} · removed ${stats.filesRemoved}`,
+			`  ignored ${stats.filesIgnored} · private ${stats.filesPrivate} · lineages rebuilt ${stats.lineagesRebuilt}`,
+			`  entries ${stats.entriesInserted} new, ${stats.entriesShared} inherited by forks · chunks ${stats.chunksInserted}`,
+			`  index: ${tildify(config.dbPath)}`,
+		].join('\n') + '\n',
+	);
+}
+
+function cmdSearch(argv: string[]): void {
+	const {values, positionals} = parseArgs({
+		args: argv,
+		options: {
+			cwd: {type: 'string', multiple: true},
+			project: {type: 'string', multiple: true},
+			role: {type: 'string', multiple: true},
+			tool: {type: 'string', multiple: true},
+			kind: {type: 'string', multiple: true},
+			since: {type: 'string'},
+			until: {type: 'string'},
+			limit: {type: 'string', default: '20'},
+			threads: {type: 'string', default: '3'},
+			private: {type: 'boolean', default: false},
+			raw: {type: 'boolean', default: false},
+			'no-recency': {type: 'boolean', default: false},
+			path: {type: 'boolean', default: false},
+			json: {type: 'boolean', default: false},
+			'no-sync': {type: 'boolean', default: false},
+		},
+		allowPositionals: true,
+	});
+	const text = positionals.join(' ').trim();
+	if (!text) fail('nothing to search for. Try `recall search <words>`');
+
+	const config = loadConfig();
+	if (!values['no-sync']) sync(config, Boolean(values.json));
+
+	const db = openDb(config.dbPath, {readOnly: true});
+	const threadsRaw = String(values.threads);
+	const outcome = search(db, {
+		text,
+		cwd: values.cwd as string[] | undefined,
+		project: values.project as string[] | undefined,
+		role: values.role as string[] | undefined,
+		tool: values.tool as string[] | undefined,
+		kind: values.kind as ChunkKind[] | undefined,
+		since: parseWhen(values.since as string | undefined),
+		until: parseWhen(values.until as string | undefined),
+		includePrivate: Boolean(values.private),
+		limit: Number(values.limit),
+		threadLimit: threadsRaw === 'all' ? -1 : Number(threadsRaw),
+		noRecency: Boolean(values['no-recency']),
+		raw: Boolean(values.raw),
+	});
+
+	if (values.json) {
+		process.stdout.write(JSON.stringify(outcome, null, 2) + '\n');
+		db.close();
+		return;
+	}
+
+	const style = makeStyle(colorsEnabled());
+	if (outcome.hits.length === 0) {
+		process.stdout.write('no matches\n');
+		db.close();
+		return;
+	}
+	if (outcome.quotedFallback) {
+		process.stderr.write(
+			style.dim(`(query retried as literal tokens: ${outcome.usedQuery})\n`),
+		);
+	}
+	const rendered = outcome.hits.map((hit) =>
+		renderHit(hit, {style, showPath: Boolean(values.path)}),
+	);
+	process.stdout.write(rendered.join('\n\n') + '\n');
+	db.close();
+}
+
+function cmdShow(argv: string[]): void {
+	const {values, positionals} = parseArgs({
+		args: argv,
+		options: {
+			from: {type: 'string', default: '0'},
+			limit: {type: 'string', default: '40'},
+			full: {type: 'boolean', default: false},
+			json: {type: 'boolean', default: false},
+		},
+		allowPositionals: true,
+	});
+	const ref = positionals[0];
+	if (!ref)
+		fail(
+			'which thread? Pass a file id, a session uuid prefix, a name, or a path',
+		);
+
+	const config = loadConfig();
+	const db = openDb(config.dbPath, {readOnly: true});
+	const thread = resolveThread(db, ref);
+	if (!thread) fail(`no thread matching "${ref}"`);
+
+	const entries = readThread(
+		db,
+		Number(thread.id),
+		Number(values.from),
+		Number(values.limit),
+	);
+	if (values.json) {
+		process.stdout.write(JSON.stringify({thread, entries}, null, 2) + '\n');
+		db.close();
+		return;
+	}
+
+	const style = makeStyle(colorsEnabled());
+	const header = [
+		style.bold(thread.name ?? thread.project ?? String(thread.id)),
+		style.dim(tildify(thread.cwd ?? '')),
+		style.dim(`${thread.entry_count} entries`),
+		style.dim(`last ${relativeTime(thread.last_activity)}`),
+	].join(' · ');
+	process.stdout.write(
+		header + '\n' + style.dim(tildify(thread.path)) + '\n\n',
+	);
+
+	const indent = (text: string) =>
+		text
+			.split('\n')
+			.map((l) => '     ' + l)
+			.join('\n');
+
+	for (const entry of entries) {
+		const marks = [
+			style.label(entry.role + (entry.tool ? `:${entry.tool}` : '')),
+		];
+		if (entry.shared) marks.push(style.dim('(inherited)'));
+		process.stdout.write(
+			`${style.dim(String(entry.seq).padStart(4))} ${marks.join(' ')}\n`,
+		);
+		if (values.full && entry.ownerPath) {
+			// Full fidelity means going back to the transcript: the index keeps tool
+			// output truncated (or absent), by design, and the byte range is the pointer.
+			const raw = readRawEntry(
+				entry.ownerPath,
+				entry.byteOffset,
+				entry.byteLength,
+			);
+			if (raw !== null) {
+				process.stdout.write(indent(JSON.stringify(raw, null, 2)) + '\n');
+				continue;
+			}
+		}
+		for (const t of entry.texts) {
+			const body = t.text.length > 2000 ? t.text.slice(0, 2000) + ' …' : t.text;
+			process.stdout.write(indent(body) + '\n');
+		}
+	}
+	db.close();
+}
+
+function cmdSql(argv: string[]): void {
+	const {values, positionals} = parseArgs({
+		args: argv,
+		options: {
+			json: {type: 'boolean', default: false},
+			limit: {type: 'string', default: '200'},
+		},
+		allowPositionals: true,
+	});
+	const sql = positionals.join(' ').trim();
+	if (!sql) fail('no SQL given');
+	const config = loadConfig();
+	const db = openDb(config.dbPath, {readOnly: true});
+	let rows: Array<Record<string, unknown>>;
+	try {
+		rows = db.prepare(sql).all() as unknown as Array<Record<string, unknown>>;
+	} catch (err) {
+		db.close();
+		fail((err as Error).message);
+	}
+	const capped = rows.slice(0, Number(values.limit));
+	if (values.json) process.stdout.write(JSON.stringify(capped, null, 2) + '\n');
+	else {
+		process.stdout.write(renderTable(capped) + '\n');
+		if (rows.length > capped.length) {
+			process.stdout.write(
+				`(${rows.length - capped.length} more rows, raise --limit)\n`,
+			);
+		}
+	}
+	db.close();
+}
+
+function cmdStats(argv: string[]): void {
+	const {values} = parseArgs({
+		args: argv,
+		options: {json: {type: 'boolean', default: false}},
+		allowPositionals: false,
+	});
+	const config = loadConfig();
+	const db = openDb(config.dbPath, {readOnly: true});
+	const stats = indexStats(db);
+	const indexedAt = getMeta(db, 'indexed_at');
+	const tier = getMeta(db, 'tier');
+	const size = fs.existsSync(config.dbPath)
+		? fs.statSync(config.dbPath).size
+		: 0;
+	const payload = {
+		...stats,
+		tier,
+		indexedAt: indexedAt ? new Date(Number(indexedAt)).toISOString() : null,
+		dbBytes: size,
+	};
+	if (values.json) {
+		process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+		db.close();
+		return;
+	}
+	const style = makeStyle(colorsEnabled());
+	process.stdout.write(
+		[
+			`${style.bold(String(stats.files))} transcripts · ${stats.lineages} lineages · ${stats.forks} forks`,
+			`${stats.entries} entries · ${stats.memberships} memberships · ${stats.chunks} chunks`,
+			`${stats.projects} projects · ${stats.privateFiles} private · ${stats.orphans} orphaned`,
+			`span ${String(stats.oldest).slice(0, 10)} → ${String(stats.newest).slice(0, 10)}`,
+			`tier ${tier} · db ${(size / 1e6).toFixed(1)} MB · updated ${relativeTime(payload.indexedAt)}`,
+			style.dim(tildify(config.dbPath)),
+		].join('\n') + '\n',
+	);
+	db.close();
+}
+
+function cmdConfig(argv: string[]): void {
+	const {values} = parseArgs({
+		args: argv,
+		options: {
+			init: {type: 'boolean', default: false},
+			json: {type: 'boolean', default: false},
+		},
+		allowPositionals: false,
+	});
+	const config = loadConfig();
+	if (values.init) {
+		const written = writeStarterConfig(config);
+		process.stdout.write(`config: ${tildify(written)}\n`);
+		return;
+	}
+	if (values.json) {
+		process.stdout.write(JSON.stringify(config, null, 2) + '\n');
+		return;
+	}
+	process.stdout.write(
+		[
+			`config   ${tildify(config.configPath)}${config.loaded ? '' : ' (not created yet, using defaults)'}`,
+			`index    ${tildify(config.dbPath)}`,
+			`tier     ${config.tier}`,
+			`sources  ${config.sources.map((s) => `${s.id}:${tildify(s.root)}`).join(', ')}`,
+			`ignore   ${config.ignore.join(', ') || '(none)'}`,
+			`private  ${config.private.join(', ') || '(none)'}`,
+		].join('\n') + '\n',
+	);
+}
+
+function main(): void {
+	const argv = process.argv.slice(2);
+	const command = argv[0];
+	const rest = argv.slice(1);
+	switch (command) {
+		case 'index':
+			return cmdIndex(rest);
+		case 'search':
+		case 's':
+			return cmdSearch(rest);
+		case 'show':
+			return cmdShow(rest);
+		case 'sql':
+			return cmdSql(rest);
+		case 'stats':
+			return cmdStats(rest);
+		case 'config':
+			return cmdConfig(rest);
+		case '--version':
+		case '-v':
+			process.stdout.write(version() + '\n');
+			return;
+		case undefined:
+		case 'help':
+		case '--help':
+		case '-h':
+			process.stdout.write(USAGE);
+			return;
+		default:
+			fail(`unknown command "${command}". Try \`recall help\``);
+	}
+}
+
+/** Entry point. Loaded dynamically by `cli.ts`, see the note there. */
+export function run(): void {
+	try {
+		main();
+	} catch (err) {
+		fail((err as Error).message);
+	}
+}

package/src/cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import {silenceSqliteWarning} from './quiet.js';
+
+/**
+ * Launcher, deliberately thin.
+ *
+ * `node:sqlite` prints an ExperimentalWarning the moment it is LOADED, and ES
+ * modules load the whole graph before any module body runs. So a static import
+ * of anything that touches sqlite would emit the warning before the filter
+ * could be installed, no matter where the call sits. Installing the filter here
+ * and pulling the real CLI in dynamically is what keeps two lines of noise off
+ * every single invocation.
+ */
+silenceSqliteWarning();
+
+const {run} = await import('./cli-main.js');
+run();

package/src/config.ts

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {expandTilde} from './glob.js';
+import type {Tier} from './model.js';
+import {TIERS} from './model.js';
+
+export interface SourceConfig {
+	/** Short label stored on every file row, so multi-source indexes stay legible. */
+	id: string;
+	/** Only `pi` for now. The adapter seam is here so other agents can be added. */
+	kind: 'pi';
+	root: string;
+}
+
+export interface Config {
+	sources: SourceConfig[];
+	/** cwd globs that are never read, never stored. */
+	ignore: string[];
+	/** cwd globs that are indexed but hidden from agents unless asked for. */
+	private: string[];
+	tier: Tier;
+	/** Bytes kept per tool result (tier `full` only). */
+	toolResultHeadBytes: number;
+	/** Bytes kept per tool call argument blob. */
+	toolArgsHeadBytes: number;
+	configDir: string;
+	dataDir: string;
+	dbPath: string;
+	configPath: string;
+	/** True when a config file was actually found on disk. */
+	loaded: boolean;
+}
+
+export const DEFAULT_TIER: Tier = 'default';
+
+function xdg(envVar: string, fallback: string): string {
+	const v = process.env[envVar];
+	if (v && v.trim()) return v;
+	return path.join(os.homedir(), fallback);
+}
+
+export function defaultConfigDir(env = process.env): string {
+	if (env.MEMONAUT_CONFIG_DIR) return env.MEMONAUT_CONFIG_DIR;
+	return path.join(xdg('XDG_CONFIG_HOME', '.config'), 'memonaut');
+}
+
+export function defaultDataDir(env = process.env): string {
+	if (env.MEMONAUT_DATA_DIR) return env.MEMONAUT_DATA_DIR;
+	return path.join(xdg('XDG_DATA_HOME', '.local/share'), 'memonaut');
+}
+
+export function defaultSources(): SourceConfig[] {
+	return [
+		{id: 'pi', kind: 'pi', root: path.join(os.homedir(), '.pi/agent/sessions')},
+	];
+}
+
+/**
+ * Load config, filling in defaults. Every path is resolved here so nothing
+ * downstream ever has to think about `~` or XDG again.
+ */
+export function loadConfig(env = process.env): Config {
+	const configDir = defaultConfigDir(env);
+	const dataDir = defaultDataDir(env);
+	const configPath = path.join(configDir, 'config.json');
+
+	let raw: Record<string, unknown> = {};
+	let loaded = false;
+	if (fs.existsSync(configPath)) {
+		try {
+			raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Record<
+				string,
+				unknown
+			>;
+			loaded = true;
+		} catch (err) {
+			throw new Error(
+				`config at ${configPath} is not valid JSON: ${(err as Error).message}`,
+			);
+		}
+	}
+
+	const sources =
+		Array.isArray(raw.sources) && raw.sources.length
+			? (raw.sources as SourceConfig[])
+			: defaultSources();
+
+	const tier =
+		typeof raw.tier === 'string' && TIERS.includes(raw.tier as Tier)
+			? (raw.tier as Tier)
+			: DEFAULT_TIER;
+
+	return {
+		sources: sources.map((s) => ({
+			...s,
+			root: path.resolve(expandTilde(s.root)),
+		})),
+		ignore: (raw.ignore as string[]) ?? [],
+		private: (raw.private as string[]) ?? [],
+		tier,
+		toolResultHeadBytes: (raw.toolResultHeadBytes as number) ?? 4096,
+		toolArgsHeadBytes: (raw.toolArgsHeadBytes as number) ?? 2048,
+		configDir,
+		dataDir,
+		dbPath: env.MEMONAUT_DB ?? path.join(dataDir, 'index.db'),
+		configPath,
+		loaded,
+	};
+}
+
+/** Write a starter config, never clobbering an existing one. */
+export function writeStarterConfig(config: Config): string {
+	fs.mkdirSync(config.configDir, {recursive: true});
+	if (fs.existsSync(config.configPath)) return config.configPath;
+	const starter = {
+		sources: defaultSources(),
+		ignore: ['/tmp/**'],
+		private: [],
+		tier: DEFAULT_TIER,
+		toolResultHeadBytes: 4096,
+		toolArgsHeadBytes: 2048,
+	};
+	fs.writeFileSync(
+		config.configPath,
+		JSON.stringify(starter, null, '\t') + '\n',
+		{mode: 0o600},
+	);
+	return config.configPath;
+}