renor-engine 0.0.0-stage → 1.0.0

package/dist/retrieval/adviceLines.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADVICE_LINES_HEADER = exports.MAX_ADVICE_CANDIDATES = exports.MAX_ADVICE_LINES_PER_SESSION = exports.MAX_ADVICE_TOKENS = exports.MAX_ADVICE_LINES = void 0;
+exports.readerAdviceLinesEnabled = readerAdviceLinesEnabled;
+exports.isSelfStatement = isSelfStatement;
+exports.adviceLines = adviceLines;
+exports.withAdviceLines = withAdviceLines;
+const tokenizer_1 = require("../indexer/tokenizer");
+const adviceQuestion_1 = require("./adviceQuestion");
+const orchestrator_1 = require("./orchestrator");
+const readerEvents_1 = require("./readerEvents");
+const relativeTimeHints_1 = require("./relativeTimeHints");
+/**
+ * Advice lines: for a query that asks to be advised ("Can you recommend ...", "Any tips ...", "What should I ..."; adviceQuestion.ts),
+ * one block first with what the user has said about their own situation, tastes and habits that shares words with the request,
+ * quoted as they wrote it and dated by its conversation, oldest first. Opt-in (`RENOR_READER_ADVICE_LINES`, default off): with it
+ * unset, or set to anything but an on value, a reply is byte-identical, and so is the reply to any query that does not ask for advice.
+ *
+ * Why. On the 19 Oct best set with a Claude Haiku 5.5 reader (docs/evals/results/LEDGER.md section AG), 30 of the 61 misses are
+ * "I don't know" on a question that has an answer; 28 of those 30 pages hold every gold evidence turn, and the largest group of them
+ * is 10 requests for advice (preference questions), each wrong in all six arms on record whatever the page's layout or digests
+ * (docs/evals/results/idk-misses-20261019/). A request for advice has no stored answer: what memory holds is the user's earlier words
+ * about themselves ("I've been using Premiere Pro for my edits"), one sentence inside a long turn among dozens of excerpts. These
+ * lines put those sentences where a reader looks first and say what they are.
+ *
+ *  - A line is `<day>: "<sentence>"`, the sentence exactly as the user wrote it (one over MAX_QUOTE_CHARS is cut around its first
+ *    matching word, with "…" where it is cut), under the date of its conversation. Assistant turns are not quoted, and neither is a
+ *    question.
+ *  - Picked by the nouns and names the request holds, not by its advice words ("recommend", "tips") or its verbs: one of them is
+ *    enough. Every thing the request names gets its own line first, then the best-scoring of the rest (rarer words weigh more).
+ *  - Bounded: at most MAX_ADVICE_LINES lines, two per conversation, MAX_ADVICE_TOKENS tokens of lines; only conversations the page
+ *    already holds are read; no model call, no embedding.
+ *  - The excerpts stay in full below the lines, in the order the page gave them.
+ */
+/** Default off. `1` / `true` / `yes` / `on` places the advice lines first on the reply to a query that asks to be advised. */
+function readerAdviceLinesEnabled(env = process.env) {
+    const v = (env.RENOR_READER_ADVICE_LINES ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/** Most lines a reply carries. */
+exports.MAX_ADVICE_LINES = 6;
+/** Most tokens of lines (o200k) a reply carries, the header sentence excluded. */
+exports.MAX_ADVICE_TOKENS = 400;
+/** Most lines taken from one conversation. */
+exports.MAX_ADVICE_LINES_PER_SESSION = 2;
+/** Most sentences considered for one query: the cost of a reply is bounded whatever the page holds. */
+exports.MAX_ADVICE_CANDIDATES = 4000;
+exports.ADVICE_LINES_HEADER = 'Statements by the user about their own situation, tastes and habits that share words with this request, oldest first, each under the date of its conversation. The excerpts below are unchanged.';
+// The words a request for advice is framed with, not what it is about: they never select a sentence.
+const ADVICE_WORDS = new Set([
+    'recommend', 'recommendation', 'suggest', 'suggestion', 'advise', 'advice', 'tip', 'idea', 'thought', 'pointer', 'opinion', 'think',
+    'option', 'resource', 'good', 'great', 'best', 'better', 'nice', 'new', 'like', 'something', 'anything', 'thing', 'way', 'please',
+    'should', 'want', 'need', 'looking', 'help', 'know', 'let',
+].map(w => (0, readerEvents_1.stem)(w)));
+// A question to someone, not something the user says about themselves.
+const ASKS = /^(?:can|could|would|will|do|does|did|is|are|what|how|why|where|which|who|any)\b/i;
+/** Something the user says about themselves: first person, and not a question. */
+function isSelfStatement(sentence) {
+    const s = sentence.replace(/^["'“(\[]+/, '');
+    return !sentence.trimEnd().endsWith('?') && !ASKS.test(s) && readerEvents_1.FIRST_PERSON.test(s);
+}
+/** The conversation's own day, as its date is written (`2023/05/30 (Tue)` or `2023-05-30`), or null when it has none. */
+function dayOf(sessionDate) {
+    const ms = (0, orchestrator_1.sessionDateMs)(sessionDate);
+    if (!Number.isFinite(ms) || sessionDate === undefined)
+        return null;
+    return (0, relativeTimeHints_1.formatDay)(new Date(Math.floor(ms / 86_400_000) * 86_400_000), /^\d{4}\//.test(sessionDate));
+}
+/**
+ * The advice lines for one query, or null when the query does not ask to be advised or no statement of the user's shares a
+ * word with it. `hits` are the conversation hits of the page; `turnsOf` returns the stored chunks of a conversation note.
+ */
+function adviceLines(hits, query, turnsOf) {
+    if (!(0, adviceQuestion_1.asksForAdvice)(query))
+        return null;
+    const terms = new Set([...(0, readerEvents_1.questionTerms)(query)].filter(t => !ADVICE_WORDS.has(t)));
+    const aboutTerms = new Set([...terms].filter(t => !readerEvents_1.GENERIC_VERBS.has(t)));
+    if (aboutTerms.size === 0)
+        return null;
+    // One entry per conversation, in the order the page holds them: its date and a chunk of it, from whichever of its hits has them.
+    const sources = new Map();
+    for (const hit of hits) {
+        const had = sources.get(hit.notePath) ?? {};
+        sources.set(hit.notePath, { chunkId: had.chunkId ?? (hit.chunkId !== undefined && hit.chunkId > 0 ? hit.chunkId : undefined), sessionDate: had.sessionDate ?? hit.session_date });
+    }
+    const candidates = [];
+    let position = 0;
+    for (const [notePath, { chunkId, sessionDate }] of sources) {
+        if (notePath === '' || candidates.length >= exports.MAX_ADVICE_CANDIDATES)
+            continue;
+        for (const turn of turnsOf({ notePath, chunkId })) {
+            if (candidates.length >= exports.MAX_ADVICE_CANDIDATES)
+                break;
+            if (!(0, readerEvents_1.isUserTurn)(turn.headingPath))
+                continue;
+            for (const sentence of (0, readerEvents_1.sentencesOf)((0, readerEvents_1.stripHeading)(turn.text))) {
+                if (!isSelfStatement(sentence))
+                    continue;
+                candidates.push({ sentence, stems: new Set((0, readerEvents_1.wordsOf)(sentence).map(w => (0, readerEvents_1.stem)(w.replace(/['’]s$/, '')))), notePath, sessionDate, position: position++ });
+            }
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    // A term every sentence holds says little; one a few hold says what the request is about.
+    const df = new Map();
+    for (const c of candidates)
+        for (const t of aboutTerms)
+            if (c.stems.has(t))
+                df.set(t, (df.get(t) ?? 0) + 1);
+    const idf = (t) => Math.log(1 + candidates.length / (df.get(t) ?? 1));
+    // A preference is usually stated with one word of the request ("I like hotels near the beach" for "a hotel for my trip to Miami"),
+    // so one shared word is enough to be a candidate; the score and the bounds below decide which candidates are shown.
+    const scored = candidates.flatMap(candidate => {
+        let score = 0;
+        for (const t of aboutTerms)
+            if (candidate.stems.has(t))
+                score += idf(t);
+        return score > 0 ? [{ candidate, score }] : [];
+    });
+    if (scored.length === 0)
+        return null;
+    const chosen = [];
+    const perSession = new Map();
+    const seen = new Set();
+    let tokens = 0;
+    const take = (c) => {
+        const key = `${c.notePath}\0${c.sentence.toLowerCase()}`;
+        if (seen.has(key) || (perSession.get(c.notePath) ?? 0) >= exports.MAX_ADVICE_LINES_PER_SESSION)
+            return false;
+        const day = dayOf(c.sessionDate);
+        const quote = (0, readerEvents_1.quoteOf)(c.sentence, terms);
+        const line = day ? `- ${day}: "${quote}"` : `- "${quote}"`;
+        const cost = (0, tokenizer_1.encodeTokens)(line) + 1;
+        if (tokens + cost > exports.MAX_ADVICE_TOKENS)
+            return false;
+        tokens += cost;
+        seen.add(key);
+        perSession.set(c.notePath, (perSession.get(c.notePath) ?? 0) + 1);
+        chosen.push({ candidate: c, line });
+        return true;
+    };
+    // First every thing the request names gets its best line, the sentence that says most of what is still unsaid first; then the
+    // best-scoring sentences that are left, until a bound is reached.
+    const covered = new Set();
+    const refused = new Set();
+    while (chosen.length < exports.MAX_ADVICE_LINES) {
+        let pick = null;
+        let pickGain = 0;
+        for (const s of scored) {
+            if (refused.has(s.candidate))
+                continue;
+            let gain = 0;
+            for (const t of aboutTerms)
+                if (s.candidate.stems.has(t) && !covered.has(t))
+                    gain += idf(t);
+            if (gain > pickGain || (gain === pickGain && gain > 0 && pick !== null && s.score > pick.score)) {
+                pick = s;
+                pickGain = gain;
+            }
+        }
+        if (pick === null || pickGain === 0)
+            break;
+        if (take(pick.candidate))
+            for (const t of aboutTerms) {
+                if (pick.candidate.stems.has(t))
+                    covered.add(t);
+            }
+        refused.add(pick.candidate);
+    }
+    const rest = scored.filter(s => !refused.has(s.candidate))
+        .sort((a, b) => b.score - a.score || a.candidate.sentence.length - b.candidate.sentence.length || a.candidate.position - b.candidate.position);
+    for (const s of rest) {
+        if (chosen.length >= exports.MAX_ADVICE_LINES)
+            break;
+        take(s.candidate);
+    }
+    if (chosen.length === 0)
+        return null;
+    // Oldest first: the conversation's date, then the order of reading.
+    chosen.sort((a, b) => ((0, orchestrator_1.sessionDateMs)(a.candidate.sessionDate) - (0, orchestrator_1.sessionDateMs)(b.candidate.sessionDate)) || (a.candidate.position - b.candidate.position));
+    return [exports.ADVICE_LINES_HEADER, ...chosen.map(c => c.line)].join('\n');
+}
+/**
+ * The page with the advice lines first (reason "advice"), when the switch is on and the query asks to be advised. Otherwise the
+ * very array it was given.
+ */
+function withAdviceLines(hits, input, env = process.env) {
+    if (!readerAdviceLinesEnabled(env) || !(0, adviceQuestion_1.asksForAdvice)(input.query))
+        return hits;
+    const text = adviceLines(hits.filter(input.isSource), input.query, input.turnsOf());
+    if (text === null)
+        return hits;
+    return [{ notePath: '', text, score: 0, reason: 'advice' }, ...hits];
+}

package/dist/retrieval/adviceQuestion.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Does a search query ask to be advised: for a recommendation, a suggestion, a tip, an idea or an opinion on what to do?
+ * Told from the query's own words and nothing else (never a label of the question), because the query is all a search sees.
+ * Its one use is the opt-in exception to the reader layout (readerLayout.ts, RENOR_READER_LAYOUT_SKIP_ADVICE).
+ *
+ * Narrow on purpose, since a wrong yes takes the layout from a question that wants it:
+ *
+ *  - a request is one of a few plain frames ("Can you recommend ...", "Any tips ...", "What should I ...", "What do you
+ *    think"); a word such as "recommendations" inside a phrase that looks something up is not a request;
+ *  - a query that points back at what was said before ("what did you recommend last time", "remind me", "our previous
+ *    conversation") asks to recall an answer, not to be given one, and is not a request wherever the frame stands;
+ *  - only the last line is read for the frame: the benchmark runner puts "Question date: ..." above the question.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asksForAdvice = asksForAdvice;
+// "any" opens a clause ("Any tips?", "..., any suggestions?") or follows "do you have": "did I get any tips" looks something up.
+const ANY_ADVICE = String.raw `any\s+(?:[\w'’-]+\s+){0,3}(?:tips?|advice|suggestions?|recommendations?|ideas|thoughts|pointers)\b`;
+const REQUEST_FRAMES = [
+    /\b(?:can|could|would|will) you (?:please )?(?:recommend|suggest|advise)\b/i,
+    new RegExp(String.raw `(?:^|[,;:.!?]\s*|\bdo you have\s+)${ANY_ADVICE}`, 'i'),
+    /\bwhat should i\b/i,
+    /\b(?:what do you think|do you think|what would you (?:do|recommend|suggest))\b/i,
+];
+const POINTS_AT_THE_PAST = new RegExp([
+    String.raw `\byou (?:recommended|suggested|advised|told|said|mentioned|gave|provided|listed|named)\b`,
+    String.raw `\blast time\b`,
+    String.raw `\bearlier\b`,
+    String.raw `\bremind me\b`,
+    String.raw `\bwe (?:discussed|talked|chatted|spoke)\b`,
+    String.raw `\bour (?:previous|last|earlier|past) (?:chat|conversation|discussion)s?\b`,
+    String.raw `\bprevious(?:ly)?\b`,
+    String.raw `\bdid you\b`,
+].join('|'), 'i');
+function lastLine(query) {
+    const lines = query.split(/\r?\n/).map(line => line.trim()).filter(line => line !== '');
+    return lines.length > 0 ? lines[lines.length - 1] : '';
+}
+function asksForAdvice(query) {
+    if (POINTS_AT_THE_PAST.test(query))
+        return false;
+    const question = lastLine(query);
+    return REQUEST_FRAMES.some(frame => frame.test(question));
+}

package/dist/retrieval/conversationShape.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONVERSATION_MIN_TURNS = void 0;
+exports.isTurnLabel = isTurnLabel;
+exports.isConversationShaped = isConversationShaped;
+/**
+ * Is a note shaped like a conversation? Told from the note's own sections, never from a front-matter `kind`, a file
+ * name or a source: a chat somebody exported and a benchmark's sessions look the same, and a note the user wrote as a
+ * document does not.
+ *
+ * A conversation written as Markdown gives each turn its own heading, and the heading says who spoke or which turn it
+ * is and nothing else ("Turn 7 - User", "User", "### Assistant:", "Q3"). A document's headings name what the section
+ * is about. So a note is conversation-shaped when at least half of its distinct heading paths end in such a label.
+ *
+ * Why the session expansion asks (orchestrator.ts): its statement limit was measured on conversations only. A turn
+ * over 100 tokens is mostly an assistant's long answer, and the answer-bearing remark is short; in a document the
+ * paragraph that answers is often 100 to 200 tokens, which the same limit would leave out.
+ *
+ * The rule leans to "document". A note taken for a document keeps the former limit, which costs a saving and nothing
+ * else; a document taken for a conversation would lose paragraphs the limit was never measured on. So a label must be
+ * made of role words alone, a note needs at least `CONVERSATION_MIN_TURNS` of them, and they must be at least half of its paths.
+ */
+const TURN_WORDS = new Set([
+    'turn', 'user', 'assistant', 'human', 'ai', 'bot', 'me', 'you', 'system', 'claude', 'chatgpt', 'gpt', 'gemini',
+    'model', 'speaker', 'message', 'question', 'answer', 'reply', 'response', 'prompt', 'q', 'a',
+]);
+/** The fewest turn headings a note needs to count as a conversation (a one-exchange note is a document here). */
+exports.CONVERSATION_MIN_TURNS = 4;
+/** True when the heading is only a speaker or turn label: role words, digits, punctuation, symbols and spaces. */
+function isTurnLabel(heading) {
+    const words = heading.toLowerCase().replace(/[\p{N}\p{P}\p{S}\p{Z}]+/gu, ' ').trim().split(' ').filter(Boolean);
+    return words.length > 0 && words.every(word => TURN_WORDS.has(word));
+}
+/** `headingPaths`: the `heading_path` of every chunk of one note (a path is its headings joined by " > "). */
+function isConversationShaped(headingPaths) {
+    const distinct = new Set(headingPaths);
+    let turns = 0;
+    for (const headingPath of distinct) {
+        const last = headingPath.split(' > ').pop() ?? '';
+        if (isTurnLabel(last))
+            turns += 1;
+    }
+    return turns >= exports.CONVERSATION_MIN_TURNS && turns * 2 >= distinct.size;
+}

package/dist/retrieval/dailyEntryTime.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDailyEntryClock = createDailyEntryClock;
+const fs_1 = __importDefault(require("fs"));
+const dailyNote_1 = require("../memory/dailyNote");
+/**
+ * When the daily-note entry a hit is part of was saved.
+ *
+ * A daily note is ONE file holding one entry per statement, so the date of the note (when the file was last written)
+ * is the same for every entry of the day: a correction said later tied with what it corrects, and newest first could
+ * put the stale one on top (live dogfood, D3). Each entry is a memory of its own (the chunker cuts one per entry) and
+ * its header says when it was said: the day of its file, the time, and the offset of the clock it was stamped on. That
+ * is `entryInstant`, the moment the memory map shows for the entry; an entry filed under an earlier day is dated by
+ * that day.
+ *
+ * The offset is in the file only (readers get the user's own day and time without it), so the file is read, once per
+ * note however many of its entries are hits, and only for a hit in a daily note. A hit is the entry whose text holds
+ * it, as the index cut it. A hit that no entry holds, or that entries saved at different moments all hold (the file
+ * changed since it was indexed, text above the first entry, a passage repeated across entries), keeps its note's date.
+ */
+function createDailyEntryClock() {
+    const notes = new Map();
+    return async (hit) => {
+        const day = (0, dailyNote_1.dailyNoteDayName)(hit.notePath);
+        if (day === null)
+            return undefined;
+        let entries = notes.get(hit.notePath);
+        if (!entries)
+            notes.set(hit.notePath, (entries = entriesOf(hit.notePath, day)));
+        const at = new Set((await entries).filter(entry => entry.text.includes(hit.text)).map(entry => entry.at));
+        return at.size === 1 ? [...at][0] : undefined;
+    };
+}
+/** Every entry of a daily note, as readers get its text (its lines up to the next entry's), with the moment it was saved. */
+async function entriesOf(notePath, day) {
+    let stored;
+    try {
+        stored = await fs_1.default.promises.readFile(notePath, 'utf8');
+    }
+    catch {
+        return []; // gone since it was indexed: the hit keeps its note's date
+    }
+    // An entry starts where the stored text says one does (dailyEntryStarts), and its words are the decoded lines, which
+    // the decode changes in place, never adding or removing one.
+    const storedLines = stored.split('\n');
+    const lines = (0, dailyNote_1.decodeDailyNoteText)(stored).split('\n');
+    const starts = storedLines.flatMap((line, i) => ((0, dailyNote_1.parseEntryHeader)(line) ? [i] : []));
+    return starts.map((start, k) => ({
+        text: lines.slice(start, starts[k + 1] ?? lines.length).join('\n'),
+        at: (0, dailyNote_1.entryInstant)(day, (0, dailyNote_1.parseEntryHeader)(storedLines[start])),
+    }));
+}

package/dist/retrieval/entityLookup.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityScopeFilter = entityScopeFilter;
+exports.liveEntityFilter = liveEntityFilter;
+exports.lookupEntity = lookupEntity;
+const readCache_1 = require("../db/readCache");
+const statements_1 = require("../db/statements");
+const scope_1 = require("../mvp/scope");
+/** The note that owns the lifecycle entities, the subjects remembered facts are about (mirrors lifecycle.ts). */
+const LIFECYCLE_NOTE_PATH = '_mcp_';
+/**
+ * The entities that belong to `scope`, as a filter for `lookupEntity` and for counting entities. A lifecycle subject
+ * belongs to every scope one of its facts was saved in (under any spelling of it: savedScopeSqlPredicate), current or
+ * superseded, the rule retrieve_memory judges a subject's existence by: its source note is the reserved name `_mcp_`,
+ * not a path, and says nothing about scope (read as a path it would be global, so a global lookup would name subjects
+ * saved only in a named scope, and a named scope would find none of its own). Every other entity belongs to the scope
+ * its source note's path names.
+ */
+function entityScopeFilter(scope) {
+    const saved = (0, scope_1.savedScopeSqlPredicate)(scope, 'f.scope');
+    const path = (0, scope_1.scopeSqlPredicate)(scope, 'entities.source_note');
+    return {
+        sql: `CASE WHEN entities.source_note = ? THEN EXISTS (SELECT 1 FROM facts f WHERE f.subject_entity_id = entities.id AND ${saved.sql}) ELSE ${path.sql} END`,
+        params: [LIFECYCLE_NOTE_PATH, ...saved.params, ...path.params],
+    };
+}
+/**
+ * The entities of every scope, as a filter for `lookupEntity` and for counting entities: a lifecycle subject only while
+ * it has a fact that is not retired (memory/lifecycle.ts moves a retired fact out of `facts`), the rule
+ * entityScopeFilter applies within one scope; every other entity.
+ */
+function liveEntityFilter() {
+    return {
+        sql: `CASE WHEN entities.source_note = ? THEN EXISTS (SELECT 1 FROM facts f WHERE f.subject_entity_id = entities.id) ELSE 1 END`,
+        params: [LIFECYCLE_NOTE_PATH],
+    };
+}
+/**
+ * Of entities that match a name equally well, which one answers: a remembered fact's subject first, then by source
+ * note path, then the oldest. Left to SQLite, the first row read answers, which is the note indexing happened to
+ * write first, and concurrent indexing writes notes in no fixed order.
+ */
+function tieOrder(table = '') {
+    return `(${table}source_note = '${LIFECYCLE_NOTE_PATH}') DESC, ${table}source_note, ${table}id`;
+}
+/**
+ * The longest canonical name, alias and source path, in SQLite characters (one code point, not a JavaScript UTF-16
+ * unit). Read once until the next write. An alias list that cannot be read counts as unbounded, so that query still runs.
+ */
+function entityNameBounds(db) {
+    return (0, readCache_1.readUntilWrite)(db, 'entityLookupBounds', () => {
+        const row = (0, statements_1.prepareOnce)(db, `SELECT COALESCE(MAX(length(canonical_name)), 0) AS name, COALESCE(MAX(length(source_note)), 0) AS note FROM entities`).get();
+        let alias = Number.POSITIVE_INFINITY;
+        try {
+            alias = (0, statements_1.prepareOnce)(db, `SELECT COALESCE(MAX(length(alias.value)), 0) AS n FROM entities AS e, json_each(e.aliases_json) AS alias`).pluck().get();
+        }
+        catch { /* malformed aliases: do not skip the alias query */ }
+        return { name: Number(row.name), alias: Number(alias), note: Number(row.note) };
+    });
+}
+/**
+ * Resolve an entity by name or alias, then by substring of a canonical name,
+ * then by substring of its source note path.
+ *
+ * `filter`, when given, is applied inside every candidate query — the scope has
+ * to constrain the search, not the answer, or the search still reads the rows
+ * the caller may not see.
+ */
+function lookupEntity(db, name, filter) {
+    const where = filter ? ` AND (${filter.sql})` : '';
+    const params = filter ? filter.params : [];
+    // `lower` and NOCASE keep a string's length, and `instr` cannot match a needle longer than the haystack. The length
+    // is SQLite's: a JavaScript `.length` counts one code point above U+FFFF as two and would skip a real name.
+    const bounds = entityNameBounds(db);
+    const qlen = (0, statements_1.prepareOnce)(db, 'SELECT length(?) AS n').get(name).n;
+    const fits = (max) => qlen === null || qlen <= max;
+    if (!fits(bounds.name) && !fits(bounds.alias) && !fits(bounds.note))
+        return null;
+    if (fits(bounds.name)) {
+        const byName = (0, statements_1.prepareOnce)(db, `SELECT * FROM entities WHERE canonical_name = ? COLLATE NOCASE${where} ORDER BY ${tieOrder()} LIMIT 1`)
+            .get(name, ...params);
+        if (byName)
+            return toRow(byName);
+    }
+    // Unaliased, as in the other three queries, so a filter can name the row's own columns as `entities.<column>`.
+    if (fits(bounds.alias)) {
+        const byAlias = (0, statements_1.prepareOnce)(db, `SELECT entities.* FROM entities, json_each(entities.aliases_json) AS alias
+       WHERE lower(alias.value) = lower(?)${where}
+       ORDER BY ${tieOrder('entities.')}
+       LIMIT 1`)
+            .get(name, ...params);
+        if (byAlias)
+            return toRow(byAlias);
+    }
+    // Partial match: canonical_name contains the search term (e.g. "User" → "USER.md — About User")
+    if (fits(bounds.name)) {
+        const byPartial = (0, statements_1.prepareOnce)(db, `SELECT * FROM entities WHERE instr(lower(canonical_name), lower(?)) > 0${where} ORDER BY length(canonical_name) ASC, ${tieOrder()} LIMIT 1`)
+            .get(name, ...params);
+        if (byPartial)
+            return toRow(byPartial);
+    }
+    // Path match: source note path contains the search term (e.g. "Cora" → notes in .../Cora/...)
+    if (fits(bounds.note)) {
+        const byPath = (0, statements_1.prepareOnce)(db, `SELECT * FROM entities WHERE instr(lower(source_note), lower(?)) > 0${where} ORDER BY length(canonical_name) ASC, ${tieOrder()} LIMIT 1`)
+            .get(name, ...params);
+        if (byPath)
+            return toRow(byPath);
+    }
+    return null;
+}
+function toRow(r) {
+    return { id: r.id, type: r.type, canonicalName: r.canonical_name, aliases: JSON.parse(r.aliases_json ?? '[]'), sourceNote: r.source_note, confidence: r.confidence };
+}

package/dist/retrieval/factsFirst.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subjectsInQuery = subjectsInQuery;
+exports.factsFirstHits = factsFirstHits;
+exports.matchingCurrentFactHits = matchingCurrentFactHits;
+const lifecycle_1 = require("../memory/lifecycle");
+const queryHelpers_1 = require("./queryHelpers");
+const factTerms_1 = require("../memory/factTerms");
+const PREDICATE_CUES = {
+    current_project: [
+        'current project',
+        'currently building',
+        'currently working',
+        'working on',
+        'building now',
+        'what are you building',
+        'what am i building',
+    ],
+    dog_name: ['dog name', "dog's name", 'dog'],
+    full_name: ['full name', 'legal name', 'real name'],
+    preferred_name: ['preferred name', 'go by', 'called', "what's my name", 'what is my name'],
+    location: ['where do i live', 'where does he live', 'lives in', 'live in', 'based in'],
+    college_degree: ['college', 'degree', 'university'],
+    hackathon_count: ['hackathon'],
+    primary_goal: ['primary goal', 'main goal', 'his mission', 'my mission'],
+    passport_italian_received: ['passport', 'citizenship'],
+    cofounder: ['cofounder', 'co-founder', 'co founder'],
+};
+/** Owner-named question cues: `{n}` is each configured owner name, so the same phrasings work for any user. */
+const OWNER_CUES = {
+    current_project: ['what is {n} building', 'what is {n} currently'],
+    location: ['where does {n} live'],
+    preferred_name: ["{n}'s name"],
+};
+/** Letters and digits in any script: the boundary around a name, so `Al` is not found inside `also`. */
+const NAME_EDGE_BEFORE = '(?<![\\p{L}\\p{N}])';
+const NAME_EDGE_AFTER = '(?![\\p{L}\\p{N}])';
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** `phrase` as a whole word or phrase in `q`, in any script. */
+function hasPhrase(q, phrase) {
+    return new RegExp(`${NAME_EDGE_BEFORE}${escapeRegExp(phrase)}${NAME_EDGE_AFTER}`, 'u').test(q);
+}
+/** Broad "who is <owner> / who am I" — return a small current-fact card, not every fact. */
+const IDENTITY_CARD = new Set([
+    'current_project', 'preferred_name', 'full_name', 'location', 'primary_goal', 'dog_name',
+]);
+function fold(s) {
+    return s.trim().toLowerCase();
+}
+function firstPerson(query) {
+    return /\b(my|i'm|i am|i've|i'd|i|me)\b/i.test(query);
+}
+/** Subjects whose lifecycle facts should be considered for this query. */
+function subjectsInQuery(query) {
+    const q = fold(query);
+    const out = [];
+    const seen = new Set();
+    const add = (name) => {
+        const key = fold(name);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(name);
+    };
+    const owner = (0, queryHelpers_1.ownerNames)();
+    if (owner.length) {
+        if (owner.some(n => hasPhrase(q, fold(n))))
+            add(owner[0]);
+        if (firstPerson(query))
+            add(owner[0]);
+    }
+    return out;
+}
+function isIdentityCardQuery(query) {
+    const q = fold(query);
+    const owner = (0, queryHelpers_1.ownerNames)();
+    const named = owner.length ? owner.map(n => escapeRegExp(fold(n))).join('|') : '';
+    if (named && new RegExp(`${NAME_EDGE_BEFORE}who is (${named})['’]s${NAME_EDGE_AFTER}`, 'u').test(q))
+        return false;
+    if (hasPhrase(q, 'who am i') || hasPhrase(q, 'tell me about me'))
+        return true;
+    return !!named && new RegExp(`${NAME_EDGE_BEFORE}(who is|who['’]s|tell me about|what should i know about) (${named})${NAME_EDGE_AFTER}`, 'u').test(q);
+}
+function queryMatchesFact(query, predicate) {
+    const q = fold(query);
+    if (isIdentityCardQuery(query) && IDENTITY_CARD.has(predicate))
+        return true;
+    const cues = PREDICATE_CUES[predicate] ?? [];
+    if (cues.some(c => q.includes(c)))
+        return true;
+    const names = (0, queryHelpers_1.ownerNames)().map(fold);
+    if ((OWNER_CUES[predicate] ?? []).some(t => names.some(n => hasPhrase(q, t.replace('{n}', n)))))
+        return true;
+    const pred = fold(predicate).replace(/_/g, ' ');
+    if (pred.length >= 3 && q.includes(pred))
+        return true;
+    const words = pred.split(/\s+/).filter(w => w.length >= 4);
+    if (words.length >= 2 && words.filter(w => q.includes(w)).length >= 2)
+        return true;
+    return false;
+}
+function factText(subject, predicate, object) {
+    return `${subject}'s ${predicate} is ${object}.`;
+}
+/**
+ * Lifecycle facts that answer a who/what identity question, as retrieval hits.
+ * Empty when the query is not about a known subject or no fact matches.
+ * Given `keep`, only the hits it shows, judged before the limit.
+ */
+function factsFirstHits(db, query, limit = 3, keep) {
+    const subjects = subjectsInQuery(query);
+    if (subjects.length === 0)
+        return [];
+    const hits = [];
+    const seen = new Set();
+    for (const subject of subjects) {
+        const canonical = (0, queryHelpers_1.identityNames)(subject)[0] ?? subject;
+        const facts = (0, lifecycle_1.factsFor)(db, subject);
+        for (const f of facts) {
+            if (seen.has(f.id))
+                continue;
+            if (!queryMatchesFact(query, f.predicate))
+                continue;
+            seen.add(f.id);
+            hits.push({
+                notePath: f.source_path || '_mcp_',
+                // No chunk backs a fact: a negative id is the facts row, which mvp/readScope judges a scoped read by.
+                chunkId: -f.id,
+                headingPath: `${canonical} > ${f.predicate}`,
+                text: factText(canonical, f.predicate, f.object_text ?? ''),
+                score: 1.15,
+                reason: 'fact',
+                // Who saved the fact: the reader's view marks it (agentMemory, search tools), as it marks a fact read by its words.
+                author: f.author ?? null,
+            });
+        }
+    }
+    return (keep ? hits.filter(keep) : hits).slice(0, limit);
+}
+/**
+ * Query words that carry no subject or object, so a fact is never found by them alone: `what`, `is` and `the` are in
+ * nearly every fact's predicate or object, and a fact that shares only one of them is not an answer to the question.
+ * Deliberately small and English; a word is a stopword here only when no fact is about it.
+ */
+const FACT_STOPWORDS = new Set([
+    'a', 'about', 'all', 'an', 'and', 'any', 'are', 'as', 'at', 'be', 'been', 'but', 'by', 'can', 'could', 'did', 'do',
+    'does', 'for', 'from', 'had', 'has', 'have', 'how', 'i', 'if', 'in', 'into', 'is', 'it', 'its', 'me', 'my', 'no', 'not',
+    'of', 'on', 'or', 'our', 'out', 'so', 'some', 'tell', 'that', 'the', 'their', 'them', 'then', 'there', 'they', 'this',
+    'to', 'was', 'we', 'were', 'what', 'when', 'where', 'which', 'who', 'why', 'will', 'with', 'would', 'you', 'your',
+]);
+/** The fact-finding words of a query: its atoms without the stopwords. */
+function contentAtoms(query) {
+    return (0, factTerms_1.atoms)(query).filter(word => !FACT_STOPWORDS.has(word));
+}
+/**
+ * Current facts matched by the query's content words, best first. A fact is admitted only when a content word is one of
+ * its subject's or object's words: a predicate word alone (`dog` in `pet: dog`'s predicate) is not enough. Its score is
+ * the share of the query's content words it has, from 0.5 to 1, so a fact ranks among the note hits by how well it
+ * answers the query, and the caller merges the two lists by score.
+ */
+function matchingCurrentFactHits(db, query, limit = 3) {
+    const terms = contentAtoms(query);
+    if (terms.length === 0 || limit < 1)
+        return [];
+    // Predicate words are in the index with the subject and object, so the index can rank a fact by a predicate word
+    // alone and crowd out a real match: read more candidates than the cap, then keep the admitted ones.
+    const matched = (0, factTerms_1.findCurrentFacts)(db, { terms, match: 'any', limit: Math.max(limit * 20, 60) });
+    const hits = [];
+    for (const f of matched) {
+        const subjectObject = new Set((0, factTerms_1.atoms)(`${f.subject} ${f.object ?? ''}`));
+        if (!terms.some(term => subjectObject.has(term)))
+            continue;
+        hits.push({
+            notePath: '_mcp_',
+            chunkId: -f.id,
+            headingPath: `${f.subject} > ${f.predicate}`,
+            text: factText(f.subject, f.predicate, f.object ?? ''),
+            score: 0.5 + 0.5 * (f.shared / terms.length),
+            reason: 'fact',
+            author: f.author ?? null,
+        });
+        if (hits.length === limit)
+            break;
+    }
+    return hits;
+}