@@ -70,6 +70,11 @@ function buildSystem(menu) {
 }
 const TOOLS_TOKENS_EST = Math.round(JSON.stringify(TOOLS).length / 4);
 
+// Cross-session memory recall (docs/levelcode-sessions-memory.md). Added to a run's tools ONLY when the host
+// wires ctx.recallSessions (memory + the recall setting on), so it costs nothing otherwise. Read-only and
+// instant like use_skill — it searches the project's OWN past-session outcomes, never the file system.
+const RECALL_TOOL = { name: 'recall_sessions', description: 'Search THIS project\'s past sessions for relevant earlier work — their recorded outcomes (what was built/fixed/decided) and the files they touched. Use when the user refers to earlier work ("what did we do about refunds?", "did we already fix the webhook?") or when prior context would clearly help before you start. Returns cited past-session outcomes with dates; treat them as memory — informative but possibly stale, so verify against the current code.', input_schema: { type: 'object', properties: { query: { type: 'string', description: 'keywords or a short question, e.g. "refund retries" or "MCP timeline rail"' } }, required: ['query'] } };
+
 // How much of a background command's accumulated output the sniffers re-read on each chunk. Generous
 // next to any single log line, so a url split across chunk boundaries is still found, yet small enough
 // that a noisy watcher which never prints an address costs nothing to keep scanning.
@@ -479,6 +484,14 @@ async function runTool(tu, ctx) {
 			ctx.post({ type: 'agentTool', icon: 'sparkle', text: '🧩 using skill: ' + name });   // quiet chip — only on success (🧩 is the marker; 'sparkle' falls back cleanly)
 			return body;                                                                       // SKILL.md body → tool_result, steers the next turns
 		}
+		if (tu.name === 'recall_sessions') {
+			if (typeof ctx.recallSessions !== 'function') { return 'ERROR: session recall is not available in this session.'; }
+			const query = String(input.query || '').trim();
+			if (!query) { return 'ERROR: pass a non-empty query describing what to recall.'; }
+			ctx.post({ type: 'agentTool', icon: 'history', text: '🧠 recalling: ' + query });
+			try { return String(ctx.recallSessions(query) || 'No matching past sessions in this project.'); }
+			catch (e) { return 'ERROR: recall failed.'; }
+		}
 		// MCP tools (docs/MCP.md S3). An MCP name matches none of the built-in branches above, so every
 		// MCP call necessarily arrives HERE — which is why the router is one block at one line rather
 		// than a dispatch scattered through runTool.
@@ -706,10 +719,12 @@ async function runAgent(ctx) {
 	// as `system`/`systemTokensEst` two lines up — built once per run, then used for every turn.
 	const mcp = await setupMcp(ctx, wsFolders, dbg);
 	ctx.mcpRoutes = mcp.routes;                                        // runTool's router reads this
-	const tools = mcp.tools.length ? TOOLS.concat(mcp.tools) : TOOLS;
-	// Recomputed only when MCP actually contributed tools, so the no-MCP path keeps the module constant
-	// and pays nothing for a feature it isn't using.
-	const toolsTokensEst = mcp.tools.length ? Math.round(JSON.stringify(tools).length / 4) : TOOLS_TOKENS_EST;
+	let tools = mcp.tools.length ? TOOLS.concat(mcp.tools) : TOOLS;
+	if (ctx.recallSessions) { tools = tools.concat([RECALL_TOOL]); }  // cross-session recall (host-gated by memory settings)
+	const baseTools = ctx.recallSessions ? TOOLS.concat([RECALL_TOOL]) : TOOLS;   // built-ins + recall; MCP is the rest
+	// Recomputed only when MCP or recall actually contributed tools, so the plain path keeps the module
+	// constant and pays nothing for a feature it isn't using.
+	const toolsTokensEst = (mcp.tools.length || ctx.recallSessions) ? Math.round(JSON.stringify(tools).length / 4) : TOOLS_TOKENS_EST;
 	// The MCP SHARE of that, reported separately so the context popover can show what these servers cost
 	// (docs/MCP.md S5). Every tool schema rides EVERY turn, so a chatty server is a standing tax on the
 	// window rather than a one-off — and until it has its own segment, that cost is invisible.
@@ -718,7 +733,7 @@ async function runAgent(ctx) {
 	// the JSON delimiters between entries belong to the total, and attributing them consistently is what
 	// keeps `tools` and `mcpTools` summing to the number the bar already draws.
 	const mcpToolsTokensEst = mcp.tools.length
-		? Math.max(0, toolsTokensEst - Math.round(JSON.stringify(TOOLS).length / 4))
+		? Math.max(0, toolsTokensEst - Math.round(JSON.stringify(baseTools).length / 4))
 		: 0;
 
 	const messages = ctx.messages;
 
@@ -778,6 +778,25 @@ function enrichMemoryAsync(id) {
 	}).catch(() => { /* best-effort */ });
 }
 
+// Format recall hits as a cited, verify-first tool result (the recall_sessions result the agent reads).
+function formatRecall(hits, query) {
+	const arr = Array.isArray(hits) ? hits : [];
+	if (!arr.length) { return 'No past sessions in this project match "' + query + '".'; }
+	const lines = arr.map((e) => {
+		const when = e.at ? String(e.at).slice(0, 10) : 'undated';
+		const files = Array.isArray(e.files) && e.files.length ? ' — files: ' + e.files.slice(0, 4).join(', ') : '';
+		return '- ' + (e.summary || e.title || 'a session') + files + ' (' + when + ')';
+	});
+	return 'Recalled from earlier sessions in this project (memory — informative but possibly stale; verify against the current code):\n' + lines.join('\n');
+}
+// The recall_sessions tool callback handed to the agent — only when memory + the recall setting are on.
+function recallSessionsTool(query) {
+	const m = sessionsManager();
+	if (!m) { return 'No project memory is available in this workspace.'; }
+	try { return formatRecall(m.recall(String(query || ''), { limit: 6 }), String(query || '')); }
+	catch (e) { return 'Recall failed.'; }
+}
+
 // A card action from either surface. resume reopens the session; done/delete/rename/pin are append-only edits
 // (§4.9): Done archives (reversible, never deletes), Delete soft-trashes, Rename retitles, Pin toggles.
 // Done/Delete offer an Undo (restore) so an accidental click is recoverable. Best-effort — a History action
@@ -1371,6 +1390,8 @@ async function agentFlow(text) {
 			},
 			skills: skillsObj,                  // M6.5: implicit skills (name+desc menu in SYSTEM + use_skill resolver)
 			projectMemory: projectMemoryMarkdown(), // cross-session memory: a verify-first digest of past sessions, injected like project rules
+			// The recall_sessions tool: search past-session outcomes on demand. Off → the tool isn't offered at all.
+			recallSessions: (aiConfig().get('sessions.memory.enabled', true) && aiConfig().get('sessions.memory.recallTool', true)) ? recallSessionsTool : undefined,
 
 			// MCP (docs/MCP.md S3). Config is read HERE and handed in, like verify/commandTimeout, so
 			// agent.js keeps doing the loading + connecting + naming without reaching for the editor API.
 
@@ -451,6 +451,11 @@
           "default": true,
           "description": "When a substantive session finishes, make one small, fast-model call to refine its journal outcome into a concrete sentence (what was built/fixed/decided) instead of just its goal headline. Runs in the background and only summarizes outcomes and actions, never quoted code. Turn off to skip the model call and keep the plain headline (no cost)."
         },
+        "levelcode.ai.sessions.memory.recallTool": {
+          "type": "boolean",
+          "default": true,
+          "description": "Give the agent a recall_sessions tool so it can search this project's past-session outcomes on demand — e.g. when you ask \"what did we do about refunds?\" it looks up the earlier work instead of guessing. Read-only, searches only the local journal. Turn off to remove the tool."
+        },
         "levelcode.ai.sessions.autoArchiveDays": {
           "type": "number",
           "default": 30,
 
@@ -98,6 +98,33 @@ function latestBySession(entries) {
 	return out;
 }
 
+// ── recall: on-demand search over the journal (design §3 — the recall tool's engine) ──────────────
+
+/**
+ * Rank journal entries against a free-text query — term matches in the outcome summary, title, and files
+ * (recency breaks ties). Pure and cheap (no file reads): the recall tool searches the small journal, not
+ * every transcript. Returns the top `limit` matching entries, best-first; [] for an empty/too-short query.
+ * @param {any[]} entries  journal entries (usually latestBySession)
+ * @param {string} query
+ * @param {{ limit?: number }} [opts]
+ */
+function recallRank(entries, query, opts) {
+	const o = opts || {};
+	const limit = Number.isFinite(o.limit) && o.limit > 0 ? o.limit : 6;
+	const terms = String(query || '').toLowerCase().split(/\s+/).map((t) => t.replace(/[^a-z0-9_.-]/g, '')).filter((t) => t.length >= 2);
+	if (!terms.length) { return []; }
+	const scored = [];
+	for (const e of (Array.isArray(entries) ? entries : [])) {
+		if (!e) { continue; }
+		const hay = ((e.summary || '') + ' ' + (e.title || '') + ' ' + (Array.isArray(e.files) ? e.files.join(' ') : '')).toLowerCase();
+		let score = 0;
+		for (const t of terms) { if (hay.indexOf(t) >= 0) { score++; } }
+		if (score > 0) { scored.push({ e, score }); }
+	}
+	scored.sort((a, b) => b.score - a.score || String(b.e.at || '').localeCompare(String(a.e.at || '')));
+	return scored.slice(0, limit).map((x) => x.e);
+}
+
 // ── the always-on digest (design §3/§8) ──────────────────────────────────────────────────────────
 
 /**
@@ -164,5 +191,5 @@ module.exports = {
 	SCHEMA_V,
 	memoryDir, journalFile, factsFile, memoryMdFile,
 	outcomeEntry, appendJournal, readJournal, latestBySession, writeMemoryMd,
-	buildDigest, digestSummary, digestMarkdown
+	recallRank, buildDigest, digestSummary, digestMarkdown
 };
@@ -165,6 +165,11 @@ function createSessions(opts) {
 		try { return memory.buildDigest(memory.readJournal(root, slug), Object.assign({ nowMs: clock().getTime() }, opts)); }
 		catch (e) { return { recently: [], pinned: [], total: 0 }; }
 	}
+	/** On-demand recall: the top past-session outcomes matching a query (journal search). Empty on error. */
+	function recall(query, opts) {
+		try { return memory.recallRank(memory.latestBySession(memory.readJournal(root, slug)), query, opts); }
+		catch (e) { return []; }
+	}
 	/** The deterministic consolidation pass: rewrite MEMORY.md from the current journal. Returns the digest. */
 	function consolidate(opts) {
 		const o = Object.assign({ nowMs: clock().getTime() }, opts);
@@ -202,7 +207,7 @@ function createSessions(opts) {
 
 	function liveId() { return live ? live.id : null; }
 
-	return { ensure, recordTurn, seal, resume, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, refineSummary, memoryPaths, list, liveId };
+	return { ensure, recordTurn, seal, resume, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, refineSummary, recall, memoryPaths, list, liveId };
 }
 
 module.exports = { createSessions };
@@ -70,6 +70,19 @@ test('LATEST: one outcome per session — the latest supersedes, newest-first',
 	assert.strictEqual(latest.find((e) => e.id === 'a').title, 'a-new', 'the later line supersedes the earlier');
 });
 
+test('RECALL: ranks journal entries by term matches in summary/title/files, best-first', () => {
+	const j = [
+		{ id: 'a', at: '2026-07-01', summary: 'Made refunds idempotent with a Redis lock', title: 'refund retries', files: ['refund.rb'] },
+		{ id: 'b', at: '2026-07-10', summary: 'Fixed the flaky payment webhook test', title: 'webhook', files: ['webhook_spec.rb'] },
+		{ id: 'c', at: '2026-07-20', summary: 'Tidied the CHANGELOG', title: 'changelog', files: ['RELEASE-NOTES.md'] }
+	];
+	assert.strictEqual(M.recallRank(j, 'refund redis', { limit: 5 })[0].id, 'a', 'two term hits rank first');
+	assert.deepStrictEqual(M.recallRank(j, 'webhook_spec.rb').map((e) => e.id), ['b'], 'matches on a file path too');
+	assert.deepStrictEqual(M.recallRank(j, 'zzz nothing'), [], 'no match → empty');
+	assert.deepStrictEqual(M.recallRank(j, 'a'), [], 'too-short terms are ignored (no accidental match-all)');
+	assert.ok(M.recallRank(j, 'the', { limit: 2 }).length <= 2, 'respects the limit');
+});
+
 test('DIGEST: recent (windowed, newest-first) + pinned, built from the journal', () => {
 	const DAY = 86400000, T0 = Date.parse('2026-08-01T12:00:00Z');
 	const ago = (d) => new Date(T0 - d * DAY).toISOString();
 
@@ -263,4 +263,15 @@ test('MEMORY: refineSummary supersedes the deterministic outcome (model enrichme
 	assert.ok(!m.refineSummary(id, '   '), 'a blank refinement is refused');
 });
 
+test('MEMORY: recall finds a past session by a query over its outcome + files', () => {
+	const root = freshRoot(), slug = store.projectSlug('/prc');
+	const m = createSessions({ root, slug, projectPath: '/prc' });
+	m.recordTurn(turn('Add idempotency to refunds', 'refund.rb'), 'm'); m.seal('done');
+	m.recordTurn(turn('Tidy the CHANGELOG', 'RELEASE-NOTES.md'), 'm'); m.seal('done');
+	const hits = m.recall('refund');
+	assert.strictEqual(hits.length, 1, 'only the refunds session matches');
+	assert.match(hits[0].title, /idempotency to refunds/);
+	assert.deepStrictEqual(m.recall('zzz-nomatch'), [], 'no match → empty');
+});
+
 console.log('sessions: ' + n + ' tests passed');
@@ -175,6 +175,16 @@ test('MEMORY (enrichment): a cheap-lane model call refines the journal outcome w
 	assert.ok((pkg.contributes.configuration.properties || {})['levelcode.ai.sessions.memory.summarize'], 'gated by a contributed setting');
 });
 
+test('MEMORY (recall): a recall_sessions agent tool searches past-session outcomes on demand', () => {
+	const agentSrc = fs.readFileSync(path.join(__dirname, '..', 'agent.js'), 'utf8');
+	assert.match(agentSrc, /name: 'recall_sessions'/, 'the tool schema exists');
+	assert.match(agentSrc, /if \(ctx\.recallSessions\) \{ tools = tools\.concat\(\[RECALL_TOOL\]\)/, 'offered ONLY when the host wires it (host-gated)');
+	assert.match(agentSrc, /tu\.name === 'recall_sessions'/, 'and dispatched to ctx.recallSessions');
+	assert.match(ext, /function recallSessionsTool/, 'extension.js provides the recall callback');
+	assert.match(ext, /recallSessions: \(aiConfig\(\)\.get\('sessions\.memory\.enabled'.*recallTool/, 'gated by enabled + recallTool');
+	assert.ok((pkg.contributes.configuration.properties || {})['levelcode.ai.sessions.memory.recallTool'], 'the setting is contributed');
+});
+
 test('VIEW: the sidebar view and the modal share the EXACT same render block (no drift)', () => {
 	const grab = (s) => s.slice(s.indexOf('// [SESSIONS-PURE-START]'), s.indexOf('// [SESSIONS-PURE-END]'));
 	assert.ok(grab(view).length > 500, 'the view carries the pure block');