headlesscode 1.0.2

package/src/memory/local.ts

@@ -0,0 +1,259 @@
+/**
+ * LocalMemoryStore — the fully working, file-backed Phase 3 memory backend.
+ *
+ * Implements the `MemoryStore` contract (src/memory/types.ts) with plain
+ * `node:fs` + JSONL — NO new dependencies. This is the harness-side
+ * implementation until the AIRunner/UwUChat endpoints exist; a future
+ * `UwUChatMemoryStore` implements the same interface over HTTP.
+ *
+ * Storage layout (under a single memory root dir, per-project scoped):
+ *
+ *   <root>/facts/<project>.jsonl      — one JSON `MemoryFact` per line
+ *   <root>/sessions/<project>.jsonl   — one JSON `SessionSummary` per line
+ *
+ * Append-only: reads parse the whole file, writes append a line. Validation is
+ * deliberately LOOSE (matching the orchestrator state-file style): malformed
+ * or partially-written lines are skipped, missing files are treated as empty.
+ *
+ * Root dir resolution order:
+ *   1. `options.dir` (constructor override — tests and the CLI pass this)
+ *   2. `process.env.HEADLESSCODE_MEMORY_DIR`
+ *   3. `<cwd>/.headlesscode/memory`
+ *
+ * Project scoping: project names are sanitized to a filesystem-safe slug and
+ * every method scopes strictly to that project's file. Project A's data can
+ * never be returned for project B.
+ *
+ * Data isolation: this store lives under the harness's own memory root and is
+ * NEVER the same storage any customer tenant route touches (see the isolation
+ * requirement in src/memory/types.ts and docs/memory-uwuchat-contract.md).
+ */
+
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+import { cosine, createLocalEmbedder } from "./embed.js"
+import { buildRollingSummary } from "./summarizer.js"
+import type { Embedder, FactInput, MemoryFact, MemoryStore, RecallResult, SessionSummary } from "./types.js"
+
+export interface LocalMemoryStoreOptions {
+	/** Memory root dir. Default: $HEADLESSCODE_MEMORY_DIR else <cwd>/.headlesscode/memory. */
+	dir?: string
+	/** Embedder for semantic recall (default: createLocalEmbedder(256)). */
+	embedder?: Embedder
+}
+
+/** Weight of exact tag/keyword matches in the recall score (weighted HIGH). */
+export const KEYWORD_WEIGHT = 1.0
+/** Weight of embedder cosine similarity in the recall score. */
+export const SEMANTIC_WEIGHT = 0.5
+/** Default number of recalled facts/summaries. */
+export const DEFAULT_RECALL_LIMIT = 5
+
+/**
+ * Sanitize a project name into a filesystem-safe slug used for the JSONL
+ * filename. Repo names are typically `my-repo` already; separators and other
+ * unsafe characters become `_`.
+ */
+export function sanitizeProject(project: string): string {
+	const cleaned = project
+		.replace(/[^A-Za-z0-9._-]+/g, "_")
+		.replace(/^[._-]+|[._-]+$/g, "")
+	return cleaned || "default"
+}
+
+/** Deterministic content hash (hex) — used for idempotent fact dedupe. */
+function contentHash(content: string): string {
+	const bytes = Buffer.from(content, "utf-8")
+	let hash = 0x811c9dc5
+	for (const b of bytes) {
+		hash ^= b
+		hash = Math.imul(hash, 0x01000193)
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0")
+}
+
+async function readJsonl<T>(file: string): Promise<T[]> {
+	let raw: string
+	try {
+		raw = await fsp.readFile(file, "utf-8")
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return []
+		}
+		throw error
+	}
+	const items: T[] = []
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim()
+		if (!trimmed) {
+			continue
+		}
+		try {
+			items.push(JSON.parse(trimmed) as T)
+		} catch {
+			// Loose validation: skip malformed / partially-written lines.
+		}
+	}
+	return items
+}
+
+async function appendJsonl(file: string, record: unknown): Promise<void> {
+	await fsp.mkdir(path.dirname(file), { recursive: true })
+	await fsp.appendFile(file, JSON.stringify(record) + "\n", "utf-8")
+}
+
+function sortedLatest<T extends { createdAt: string }>(items: T[]): T[] {
+	return [...items].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+}
+
+export class LocalMemoryStore implements MemoryStore {
+	readonly dir: string
+	private readonly embedder: Embedder
+
+	constructor(options: LocalMemoryStoreOptions = {}) {
+		const resolvedDir =
+			options.dir ?? process.env.HEADLESSCODE_MEMORY_DIR ?? path.join(process.cwd(), ".headlesscode", "memory")
+		this.dir = path.resolve(resolvedDir)
+		this.embedder = options.embedder ?? createLocalEmbedder()
+	}
+
+	// ─── Path helpers (per-project scoping) ──────────────────────────────────
+
+	private projectKey(project: string): string {
+		return sanitizeProject(project)
+	}
+
+	private factsPath(projectKey: string): string {
+		return path.join(this.dir, "facts", `${projectKey}.jsonl`)
+	}
+
+	private sessionsPath(projectKey: string): string {
+		return path.join(this.dir, "sessions", `${projectKey}.jsonl`)
+	}
+
+	// ─── MemoryStore implementation ──────────────────────────────────────────
+
+	async listFacts(project: string): Promise<MemoryFact[]> {
+		return readJsonl<MemoryFact>(this.factsPath(this.projectKey(project)))
+	}
+
+	async addFact(project: string, factInput: FactInput): Promise<MemoryFact> {
+		const projectKey = this.projectKey(project)
+		const file = this.factsPath(projectKey)
+		const existing = await readJsonl<MemoryFact>(file)
+		// Idempotent: dedupe by content within the project (content-hash key).
+		const duplicate = existing.find((f) => f.content === factInput.content)
+		if (duplicate) {
+			return duplicate
+		}
+		const fact: MemoryFact = {
+			id: `fact_${contentHash(factInput.content)}`,
+			project: projectKey,
+			kind: factInput.kind,
+			content: factInput.content,
+			tags: [...new Set([...(factInput.tags ?? []), factInput.kind])],
+			source: factInput.source,
+			createdAt: new Date().toISOString(),
+		}
+		await appendJsonl(file, fact)
+		return fact
+	}
+
+	async queryRecall(project: string, query: string, limit = DEFAULT_RECALL_LIMIT): Promise<RecallResult> {
+		const projectKey = this.projectKey(project)
+		const [facts, sessions] = await Promise.all([readJsonl<MemoryFact>(this.factsPath(projectKey)), readJsonl<SessionSummary>(this.sessionsPath(projectKey))])
+		if (facts.length === 0 && sessions.length === 0) {
+			return { facts: [], summaries: [] }
+		}
+
+		const queryVec = this.embedder.embed(query)
+		const tokens = keywordTokens(query)
+
+		const scoreFact = (fact: MemoryFact): number => {
+			const keyword = keywordScore(fact.content, fact.tags, tokens)
+			const semantic = cosine(queryVec, this.embedder.embed(`${fact.kind} ${fact.content} ${fact.tags.join(" ")}`))
+			return keyword * KEYWORD_WEIGHT + semantic * SEMANTIC_WEIGHT
+		}
+		const scoreSummary = (s: SessionSummary): number => {
+			const keyword = keywordScore(`${s.task} ${s.summary}`, [], tokens)
+			const semantic = cosine(queryVec, this.embedder.embed(`${s.task} ${s.summary} ${s.mode ?? ""}`))
+			return keyword * KEYWORD_WEIGHT + semantic * SEMANTIC_WEIGHT
+		}
+
+		const scoredFacts = facts.map((f) => ({ ...f, score: scoreFact(f) }))
+		const scoredSummaries = sessions.map((s) => ({ ...s, score: scoreSummary(s) }))
+
+		// Deterministic ordering: score desc, then createdAt desc.
+		scoredFacts.sort((a, b) => byScoreThenNewest(a, b))
+		scoredSummaries.sort((a, b) => byScoreThenNewest(a, b))
+
+		return {
+			facts: scoredFacts.slice(0, limit),
+			summaries: scoredSummaries.slice(0, limit),
+		}
+	}
+
+	async recordSession(project: string, summary: SessionSummary): Promise<void> {
+		const projectKey = this.projectKey(project)
+		const file = this.sessionsPath(projectKey)
+		const existing = await readJsonl<SessionSummary>(file)
+		if (existing.some((s) => s.id === summary.id)) {
+			// Idempotent by id: never double-record the same session.
+			return
+		}
+		const record: SessionSummary = {
+			...summary,
+			project: projectKey,
+			id: summary.id || `session_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`,
+			facts: summary.facts.map((f) => ({ ...f, project: projectKey })),
+		}
+		await appendJsonl(file, record)
+	}
+
+	async listSessions(project: string): Promise<SessionSummary[]> {
+		return readJsonl<SessionSummary>(this.sessionsPath(this.projectKey(project)))
+	}
+
+	async summarize(project: string, options: { maxEntries?: number } = {}): Promise<string> {
+		const sessions = await this.listSessions(project)
+		return buildRollingSummary(sessions, options.maxEntries)
+	}
+}
+
+// ─── Recall scoring helpers ──────────────────────────────────────────────────
+
+/** Deterministic ordering: score desc, then createdAt desc. */
+function byScoreThenNewest<T extends { score?: number; createdAt: string }>(a: T, b: T): number {
+	const scoreDiff = (b.score ?? 0) - (a.score ?? 0)
+	if (scoreDiff !== 0) {
+		return scoreDiff
+	}
+	return a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0
+}
+
+/** Lowercased alphanumeric tokens from the query (deduped, capped at 10). */
+function keywordTokens(query: string): string[] {
+	const raw = query.toLowerCase().match(/[a-z0-9]+/g) ?? []
+	return [...new Set(raw)].filter((t) => t.length > 1).slice(0, 10)
+}
+
+/**
+ * Exact tag/content keyword match score (weighted HIGH per the contract):
+ * +0.4 per query token found in the content, +0.3 per token found in tags.
+ */
+function keywordScore(content: string, tags: string[], tokens: string[]): number {
+	const text = content.toLowerCase()
+	const tagText = tags.join(" ").toLowerCase()
+	let score = 0
+	for (const token of tokens) {
+		if (text.includes(token)) {
+			score += 0.4
+		}
+		if (tagText.includes(token)) {
+			score += 0.3
+		}
+	}
+	return score
+}
+

package/src/memory/summarizer.ts

@@ -0,0 +1,283 @@
+/**
+ * Session summarization — Phase 3 deterministic stand-in.
+ *
+ * `extractSessionSummary` converts a `SessionResult` (+ the session's tool-call
+ * history) into a persisted `SessionSummary`, and `buildRollingSummary` turns a
+ * list of session summaries into a compact markdown recap so a session can
+ * carry context forward WITHOUT keeping the infinite raw history (the
+ * AgentMemory equivalent).
+ *
+ * This is a DETERMINISTIC stand-in: the summary text is the session's final
+ * answer (or failure reason), files/commands are derived from the tool-call
+ * history, and facts are extracted with keyword heuristics. An LLM-based
+ * extractor (the spec's Phase 3.1 "summarize session" endpoint) can be plugged
+ * in later via the `SummarizeWithLlm` hook — NO LLM is required for the
+ * default path or for tests.
+ */
+
+import type { ChatMessage, LlmClient, SessionResult } from "../engine/types.js"
+import type { MemoryFact, SessionSummary } from "./types.js"
+
+/** Maximum number of facts extracted from one session result. */
+export const MAX_FACTS_PER_SESSION = 8
+/** Maximum length of an extracted fact's content. */
+export const MAX_FACT_CHARS = 500
+/** Default number of sessions kept in a rolling summary. */
+export const DEFAULT_ROLLING_MAX_ENTRIES = 10
+
+/**
+ * Optional LLM-based summarization hook (Phase 3.1 placeholder).
+ *
+ * `(llmClient, transcript) => Promise<summaryText>`. Not wired into the
+ * deterministic path; documented as the swap-in point for the future
+ * AIRunner/UwUChat summarize-session endpoint.
+ */
+export type SummarizeWithLlm = (llmClient: LlmClient, transcript: string) => Promise<string>
+
+/**
+ * Default summarizer: returns the transcript unchanged (deterministic, no
+ * LLM). Callers that want the LLM hook may implement/replace this.
+ */
+export class NoopSummarizer {
+	summarize(transcript: string): string {
+		return transcript
+	}
+}
+
+export interface ExtractSummaryOptions {
+	taskText: string
+	mode?: string
+	project: string
+	/**
+	 * Full session message history (system/user/assistant/tool) — used to
+	 * derive `filesTouched` + `commandsRun` from the executed tool calls.
+	 * When omitted, those lists are empty (callers that have the history
+	 * should always pass it).
+	 */
+	messages?: ChatMessage[]
+}
+
+/**
+ * Build a `SessionSummary` from a session result + its tool history.
+ *
+ * Deterministic, no LLM required:
+ *   - summary  = attempt_completion result text, or the final assistant text,
+ *                or the failure error message;
+ *   - outcome  = success | failure from `result.status`;
+ *   - filesTouched  = paths from write_to_file / read_file (and cwd of
+ *                     execute_command) calls in the message history;
+ *   - commandsRun   = command strings from execute_command calls;
+ *   - facts    = heuristic extraction from the result text (see
+ *                `extractFacts`), capped at MAX_FACTS_PER_SESSION.
+ */
+export function extractSessionSummary(result: SessionResult, options: ExtractSummaryOptions): SessionSummary {
+	const outcome: "success" | "failure" = result.status === "success" ? "success" : "failure"
+	const summaryText =
+		(result.result ?? "").trim() || (result.error ?? "").trim() || "Task completed without a final message"
+
+	const { filesTouched, commandsRun } = deriveToolActivity(options.messages ?? [])
+
+	return {
+		id: `summary_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`,
+		project: options.project,
+		task: options.taskText.trim() || "(untitled task)",
+		mode: options.mode,
+		outcome,
+		summary: summaryText.slice(0, 4000),
+		facts: extractFacts(summaryText, options),
+		filesTouched,
+		commandsRun,
+		createdAt: new Date().toISOString(),
+	}
+}
+
+/**
+ * Deterministic fact extraction from a session result text.
+ *
+ * Heuristic: split into lines, keep lines containing fact-ish keywords, map
+ * them to a kind by keyword, cap content at MAX_FACT_CHARS, dedupe by content,
+ * cap at MAX_FACTS_PER_SESSION. This is the Phase 3 stand-in for the LLM-based
+ * extractor the spec's summarize endpoint will run.
+ */
+export function extractFacts(text: string, options: ExtractSummaryOptions): MemoryFact[] {
+	const source = `session:${options.taskText.trim().slice(0, 80) || "extracted"}`
+	const facts: MemoryFact[] = []
+	const seen = new Set<string>()
+
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.replace(/^[-*\d.\s)\]]+\s*/, "").trim()
+		if (line.length < 12) {
+			continue
+		}
+		const kind = classifyLine(line)
+		if (!kind) {
+			continue
+		}
+		const content = line.slice(0, MAX_FACT_CHARS)
+		if (seen.has(content)) {
+			continue
+		}
+		seen.add(content)
+		facts.push({
+			id: "", // assigned/project-scoped by the store on addFact
+			project: options.project,
+			kind,
+			content,
+			tags: keywordTags(line),
+			source,
+			createdAt: new Date().toISOString(),
+		})
+		if (facts.length >= MAX_FACTS_PER_SESSION) {
+			break
+		}
+	}
+	return facts
+}
+
+/**
+ * Keyword → kind mapping (first match wins; priority: failure > decision >
+ * convention > knowledge). "Things that didn't work" map to `failure`.
+ */
+const FACT_KEYWORD_RULES: Array<{ kind: MemoryFact["kind"]; regex: RegExp }> = [
+	{
+		kind: "failure",
+		regex: /never|bug|break|broke|failed|doesn'?t work|didn'?t work|does not work|did not work|\bfix(ed|ing|es)?\b/i,
+	},
+	{
+		kind: "decision",
+		regex: /decision|decided|chose|migration|todo|xxx|we (will|should|now) (use|keep|adopt)/i,
+	},
+	{ kind: "convention", regex: /rule|convention|always/i },
+	{ kind: "knowledge", regex: /note|remember/i },
+]
+
+export function classifyLine(line: string): MemoryFact["kind"] | null {
+	for (const rule of FACT_KEYWORD_RULES) {
+		if (rule.regex.test(line)) {
+			return rule.kind
+		}
+	}
+	return null
+}
+
+/** Tags derived from the matched keywords in a line (deduped, lowercased). */
+function keywordTags(line: string): string[] {
+	const words = line.toLowerCase().match(/[a-z]{3,}/g) ?? []
+	const interesting = words.filter((w) =>
+		["never", "always", "rule", "convention", "bug", "fix", "migration", "decision", "note", "todo", "xxx"].includes(w),
+	)
+	return [...new Set(interesting)]
+}
+
+/**
+ * Derive filesTouched + commandsRun from the executed tool-call history.
+ *
+ * The PRIMARY source is assistant messages' `tool_calls` (the args the model
+ * emitted) — the loop stores the executor's RESULT text in `tool` messages,
+ * not the args, so they can't be parsed from there. A `tool`-message fallback
+ * (content that is itself JSON args) is kept for robustness.
+ */
+function deriveToolActivity(messages: ChatMessage[]): { filesTouched: string[]; commandsRun: string[] } {
+	const filesTouched: string[] = []
+	const commandsRun: string[] = []
+	const seenFiles = new Set<string>()
+	const seenCommands = new Set<string>()
+
+	const recordFile = (p: string): void => {
+		const key = p.trim()
+		if (key !== "" && !seenFiles.has(key)) {
+			seenFiles.add(key)
+			filesTouched.push(key)
+		}
+	}
+	const recordCommand = (c: string): void => {
+		const key = c.trim()
+		if (key !== "" && !seenCommands.has(key)) {
+			seenCommands.add(key)
+			commandsRun.push(key)
+		}
+	}
+
+	for (const message of messages) {
+		if (message.role === "assistant" && message.tool_calls) {
+			for (const call of message.tool_calls) {
+				const name = call.function?.name
+				let args: Record<string, unknown> = {}
+				try {
+					args = JSON.parse(call.function?.arguments ?? "") as Record<string, unknown>
+				} catch {
+					// Malformed args — best effort: skip this call.
+				}
+				recordToolActivity(name, args, recordFile, recordCommand)
+			}
+		} else if (message.role === "tool") {
+			let args: Record<string, unknown> = {}
+			try {
+				args = JSON.parse(message.content ?? "") as Record<string, unknown>
+			} catch {
+				continue // tool results carry no args (real loop shape)
+			}
+			recordToolActivity(message.name, args, recordFile, recordCommand)
+		}
+	}
+	return { filesTouched, commandsRun }
+}
+
+function recordToolActivity(
+	name: string | undefined,
+	args: Record<string, unknown>,
+	recordFile: (p: string) => void,
+	recordCommand: (c: string) => void,
+): void {
+	if (name === "write_to_file" || name === "read_file") {
+		if (typeof args["path"] === "string") {
+			recordFile(args["path"])
+		}
+	} else if (name === "execute_command") {
+		if (typeof args["command"] === "string") {
+			recordCommand(args["command"])
+		}
+		if (typeof args["cwd"] === "string") {
+			recordFile(args["cwd"])
+		}
+	}
+}
+
+/**
+ * Compact markdown recap of the last `maxEntries` sessions (most recent
+ * first) — the AgentMemory equivalent: a session can carry this forward as
+ * context instead of the full raw history.
+ *
+ * Deterministic ordering: sessions are sorted by `createdAt` desc, then the
+ * most recent `maxEntries` are rendered.
+ */
+export function buildRollingSummary(sessions: SessionSummary[], maxEntries = DEFAULT_ROLLING_MAX_ENTRIES): string {
+	const sorted = [...sessions].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+	const recent = sorted.slice(0, maxEntries)
+
+	if (recent.length === 0) {
+		return "No prior sessions recorded for this project."
+	}
+
+	const lines: string[] = []
+	lines.push(`### Rolling session recap (last ${recent.length} session${recent.length === 1 ? "" : "s"})`)
+	for (const session of recent) {
+		lines.push("")
+		lines.push(`**${session.createdAt}** — outcome: ${session.outcome}${session.mode ? ` (mode: ${session.mode})` : ""}`)
+		lines.push(`Task: ${session.task}`)
+		lines.push(`Summary: ${session.summary}`)
+		if (session.filesTouched.length > 0) {
+			lines.push(`Files touched: ${session.filesTouched.join(", ")}`)
+		}
+		if (session.commandsRun.length > 0) {
+			lines.push(`Commands run: ${session.commandsRun.join("; ")}`)
+		}
+		if (session.facts.length > 0) {
+			lines.push("Key facts:")
+			for (const fact of session.facts) {
+				lines.push(`- [${fact.kind}] ${fact.content}`)
+			}
+		}
+	}
+	return lines.join("\n")
+}

package/src/memory/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Phase 3 memory subsystem — shared types + contracts.
+ *
+ * This module defines the harness's memory model: knowledge facts about a
+ * codebase (conventions, past decisions, things that didn't work), rolling
+ * session summaries, and the two abstractions the rest of the system depends
+ * on:
+ *
+ *   - `MemoryStore` — the persistence/recall contract. `LocalMemoryStore`
+ *     (src/memory/local.ts) is the fully working local implementation; a
+ *     future `UwUChatMemoryStore` (src/memory/uwuchat.ts) implements the SAME
+ *     interface against authenticated, per-project-scoped REST endpoints on
+ *     the AIRunner/UwUChat side (see docs/memory-uwuchat-contract.md).
+ *   - `Embedder` — the local-embedding abstraction, so a real local embedding
+ *     model can be swapped in behind the same interface later. Phase 3 ships
+ *     `createLocalEmbedder()` (src/memory/embed.ts), a zero-dependency,
+ *     deterministic lexical-hash stand-in.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * DATA ISOLATION — HARD REQUIREMENT
+ *
+ * The harness memory is knowledge about the harness's OWN codebase work
+ * ("facts about a codebase and its past decisions"), NOT tenant/user data.
+ * It MUST live in a schema/storage namespace dedicated to the harness and
+ * MUST NEVER be reachable through any customer tenant route, and customer
+ * tenant data MUST NEVER be written into it. Every record is scoped by
+ * `project` (a repo name — not a tenant, not a user). Implementations must:
+ *
+ *   1. Use a dedicated store (a dedicated memory root dir for the local
+ *      backend; a dedicated schema/service for the UwUChat backend) that is
+ *      never the same table/store any customer-facing route reads or writes.
+ *   2. Never route harness memory through a customer tenant path, and never
+ *      allow tenant-scoped queries to reach this store.
+ *   3. Never mix FHE/encryption/tenant-ownership semantics into this data —
+ *      it is an internal dev tool's knowledge, not customer data.
+ *
+ * See docs/memory-uwuchat-contract.md for the full isolation guarantee.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+/** A persisted knowledge fact about a project. */
+export interface MemoryFact {
+	/** Stable unique id (deterministic from content for local backend). */
+	id: string
+	/** Project scope (repo name). Memory is per-project, never per-tenant. */
+	project: string
+	/**
+	 * Fact category.
+	 * - `convention` — rules/always-do patterns ("always run tests first")
+	 * - `decision`   — recorded past decisions ("we chose X over Y because …")
+	 * - `failure`    — things that DIDN'T work ("never use X — it breaks Y")
+	 * - `knowledge`  — general facts about the codebase
+	 */
+	kind: "convention" | "decision" | "failure" | "knowledge"
+	content: string
+	tags: string[]
+	/** Provenance, e.g. `session:<summary-id>` or a manual note. */
+	source?: string
+	/** ISO timestamp. */
+	createdAt: string
+}
+
+/** Input for adding a fact (the store generates `id`/`project`/`createdAt`). */
+export interface FactInput {
+	kind: MemoryFact["kind"]
+	content: string
+	tags?: string[]
+	source?: string
+}
+
+/** A rolling record of one completed harness session (AgentMemory equivalent). */
+export interface SessionSummary {
+	id: string
+	project: string
+	task: string
+	mode?: string
+	/** outcome of the session: completed vs. bounded failure. */
+	outcome: "success" | "failure"
+	/** The session's final answer text (or the failure reason). */
+	summary: string
+	/** Facts extracted from this session (deterministic heuristics). */
+	facts: MemoryFact[]
+	filesTouched: string[]
+	commandsRun: string[]
+	createdAt: string
+}
+
+/** A fact annotated with a relevance score from `queryRecall`. */
+export interface ScoredFact extends MemoryFact {
+	/** Small relevance score (higher = more relevant). Absent = unscored. */
+	score?: number
+}
+
+/** A session summary annotated with a relevance score from `queryRecall`. */
+export interface ScoredSessionSummary extends SessionSummary {
+	/** Small relevance score (higher = more relevant). Absent = unscored. */
+	score?: number
+}
+
+/** Result of a recall query: top relevant facts + session summaries. */
+export interface RecallResult {
+	facts: ScoredFact[]
+	summaries: ScoredSessionSummary[]
+}
+
+/**
+ * The memory persistence contract — the UwUChat-backable boundary.
+ *
+ * Every method is project-scoped: callers pass the project (repo) name and
+ * implementations MUST guarantee that project A's data is never returned for
+ * project B. All methods are async (the future UwUChat backend is HTTP).
+ *
+ * A future `UwUChatMemoryStore` implements this EXACT interface against
+ * authenticated, per-project-scoped REST endpoints on the AIRunner/UwUChat
+ * side (endpoint contract documented in docs/memory-uwuchat-contract.md);
+ * `LocalMemoryStore` implements it today with plain fs + JSONL.
+ */
+export interface MemoryStore {
+	/** All facts stored for a project (append order). */
+	listFacts(project: string): Promise<MemoryFact[]>
+	/** Add a fact; MUST be idempotent (dedupe by content within a project). */
+	addFact(project: string, factInput: FactInput): Promise<MemoryFact>
+	/**
+	 * Semantic recall over facts + session summaries for a project.
+	 * Returns the top-`limit` most relevant facts and summaries, each with a
+	 * small relevance score, ordered deterministically (score desc, then
+	 * createdAt desc). Must work with an empty store (returns empty results).
+	 */
+	queryRecall(project: string, query: string, limit?: number): Promise<RecallResult>
+	/** Persist a completed session summary for a project. */
+	recordSession(project: string, summary: SessionSummary): Promise<void>
+	/** All session summaries stored for a project (append order). */
+	listSessions(project: string): Promise<SessionSummary[]>
+	/**
+	 * Optional: a compact rolling recap (markdown) of the last N sessions for
+	 * a project, so a session can carry context forward WITHOUT keeping the
+	 * full raw history. Implementations that provide it can be used directly
+	 * by the loop; otherwise the loop derives one from `queryRecall`.
+	 */
+	summarize?(project: string, options?: { maxEntries?: number }): Promise<string>
+}
+
+/**
+ * The local embedding abstraction.
+ *
+ * Phase 3 ships `createLocalEmbedder()` (a deterministic, dependency-free
+ * lexical-hash stand-in). A real local embedding model can be swapped in
+ * behind this same interface later without touching any caller.
+ */
+export interface Embedder {
+	/** Embed a text into a fixed-dimension L2-normalized vector. */
+	embed(text: string): number[]
+}