sessionmem 1.7.0 → 1.8.0

package/dist/cli/commands/promptSubmit.js

@@ -0,0 +1,58 @@
+import { createCliContext } from "../context.js";
+import { deriveProjectId } from "../projectId.js";
+/** Bounded hook input. Invalid input produces no context and never blocks a prompt. */
+export async function promptSubmitCommand(ctx, supplied) {
+    let context;
+    try {
+        let payload = supplied;
+        if (payload === undefined) {
+            payload = await new Promise(resolve => {
+                let text = "", finished = false;
+                const done = () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(timer);
+                    process.stdin.removeListener("data", data);
+                    process.stdin.removeListener("end", done);
+                    process.stdin.removeListener("error", done);
+                    process.stdin.pause();
+                    try {
+                        resolve(JSON.parse(text));
+                    }
+                    catch {
+                        resolve({});
+                    }
+                };
+                const data = (chunk) => { text += chunk; if (text.length > 65536) {
+                    text = "";
+                    done();
+                } };
+                const timer = setTimeout(done, 500);
+                timer.unref();
+                process.stdin.setEncoding("utf8");
+                process.stdin.on("data", data);
+                process.stdin.on("end", done);
+                process.stdin.on("error", done);
+            });
+        }
+        if (!payload || typeof payload !== "object")
+            return;
+        const { prompt, cwd } = payload;
+        if (typeof prompt !== "string" || !prompt.trim())
+            return;
+        context = ctx ?? createCliContext(typeof cwd === "string" ? { projectId: deriveProjectId(cwd) } : {});
+        const result = await context.service.call("retrieveMemories", {
+            projectId: context.projectId, query: prompt.slice(0, 1000), limit: 5, mode: "on-demand", depth: "default",
+        });
+        if (result.ok && result.startupInjection.trim())
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result.startupInjection },
+            }));
+    }
+    catch { /* Hook failures do not interrupt the host. Doctor diagnoses the setup. */ }
+    finally {
+        if (!ctx)
+            context?.db.close();
+    }
+}

package/dist/cli/commands/sessionStart.js

@@ -1,3 +1,4 @@
+import { sweepTranscripts } from "../transcriptSweep.js";
 import { createCliContext } from "../context.js";
 /**
  * Generic startup query. When few memories contain these literal tokens the
@@ -25,8 +26,15 @@ const STARTUP_QUERY = "session startup context recent decisions architecture war
  *    starts clean.
  */
 export async function sessionStartCommand(ctx) {
+    let context;
     try {
-        const context = ctx ?? createCliContext();
+        context = ctx ?? createCliContext();
+        if (!ctx) {
+            try {
+                await sweepTranscripts(context, {});
+            }
+            catch { /* Existing recall still works when transcript discovery fails. */ }
+        }
         const result = await context.service.call("retrieveMemories", {
             projectId: context.projectId,
             query: STARTUP_QUERY,
@@ -47,6 +55,10 @@ export async function sessionStartCommand(ctx) {
         }
     }
     catch {
-        // Never block session start — emit nothing on any failure.
+        // Never block session start.
+    }
+    finally {
+        if (!ctx)
+            context?.db.close();
     }
 }

package/dist/cli/index.js

@@ -3,6 +3,7 @@ import { autostartCommand } from "./commands/autostart.js";
 import { Command } from "commander";
 import { createRequire } from "node:module";
 import { runMcpServer } from "./commands/run.js";
+import { promptSubmitCommand } from "./commands/promptSubmit.js";
 import { sessionStartCommand } from "./commands/sessionStart.js";
 import { sessionEndCommand } from "./commands/sessionEnd.js";
 import { installCommand } from "./commands/install.js";
@@ -51,6 +52,7 @@ program
     .command("session-start")
     .description("Print prior memory context for the current project as Claude Code SessionStart hook output (invoked automatically by the hook installed during `sessionmem install`)")
     .action(() => sessionStartCommand());
+program.command("prompt-submit").description("Inject relevant context for a UserPromptSubmit hook").action(() => promptSubmitCommand());
 program
     .command("session-end")
     .description("Run the session-end pipeline (auto-summarize ingested session events + light retention prune) for the current project (invoked automatically by the SessionEnd hook installed during `sessionmem install`)")

package/dist/cli/projectId.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 /** Safety bound on the upward walk in {@link findProjectRoot}. */
 const MAX_PARENT_WALK = 64;
@@ -110,5 +110,20 @@ export function deriveProjectId(cwd = process.cwd()) {
             return sanitized;
         }
     }
-    return projectIdFromCwd(findProjectRoot(cwd) ?? cwd);
+    const canonical = canonicalDir(cwd);
+    return projectIdFromCwd(findProjectRoot(canonical) ?? canonical);
+}
+/**
+ * Resolve symlinks so the same directory hashes to one id however it is
+ * spelled. process.cwd() is already symlink-resolved, but a hook payload cwd is
+ * not (on macOS /var/... vs /private/var/...). Falls back to the input when the
+ * path does not exist.
+ */
+function canonicalDir(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
 }

package/dist/core/api/contracts.js

@@ -179,6 +179,25 @@ export const getMemoryRequestSchema = z.object({
     projectId: z.string().min(1),
     memoryId: z.string().min(1).max(200),
 });
+export const searchMemoryIndexRequestSchema = retrieveMemoriesRequestSchema
+    .pick({ projectId: true, query: true, includeHistory: true, tags: true })
+    .extend({ limit: z.number().int().min(1).max(50).default(10) });
+export const memoryTimelineRequestSchema = z.object({
+    projectId: z.string().min(1),
+    memoryId: z.string().min(1).max(200).optional(),
+    fromDate: z.iso.datetime().optional(),
+    toDate: z.iso.datetime().optional(),
+    includeHistory: z.boolean().default(true),
+    limit: z.number().int().min(1).max(50).default(10),
+}).refine(value => value.memoryId !== undefined
+    ? value.fromDate === undefined && value.toDate === undefined
+    : value.fromDate !== undefined && value.toDate !== undefined && Date.parse(value.fromDate) <= Date.parse(value.toDate), { message: "Provide memoryId alone, or fromDate and toDate in chronological order" });
+export const memoryIndexItemSchema = z.object({
+    id: z.string(), summary: z.string().max(160), kind: z.string(), date: z.string(), score: z.number().nullable(),
+});
+export const memoryIndexResponseSchema = z.object({
+    ok: z.literal(true), memories: z.array(memoryIndexItemSchema), hasMore: z.boolean(),
+});
 export const forgetMemoryRequestSchema = z.object({
     projectId: z.string().min(1),
     memoryId: z.string().min(1).max(200),

package/dist/core/api/memoryCoreService.js

@@ -3,6 +3,9 @@ import { ZodError } from "zod";
 import { deterministicEmbed } from "../embed/deterministicEmbed.js";
 import { loadLocalSemanticEmbedder } from "../embed/localSemanticEmbedder.js";
 import { indexSemanticMemories, searchSemanticMemories } from "../storage/semanticSearchRepo.js";
+import { detectTemporalIntent } from "../retrieve/temporalIntent.js";
+import { memoryIndexItem } from "../retrieve/memoryIndex.js";
+import { memoryTimeline } from "../storage/timelineRepo.js";
 import { retrieveMemories } from "../retrieve/retrieveMemories.js";
 import { computeEffectiveImportance } from "../retrieve/score.js";
 import { formatStartupInjection } from "../injection/formatStartupInjection.js";
@@ -11,7 +14,7 @@ import { countAllMemoriesByProject, countMemoriesBySession, countMemoriesOlderTh
 import { SESSION_WRITE_SOFT_LIMIT, configFilePath, DEEP_MODE_RETRIEVAL_CAP, readPolicyConfig, resolvePolicySettings, } from "../config/policyConfig.js";
 import { insertMemoryFeedbackEvent } from "../storage/memoryFeedbackRepo.js";
 import { countAllSessionEvents, insertSessionEvent, nextSessionEventIndex, } from "../storage/sessionEventsRepo.js";
-import { batchStoreMemoryItemSchema, batchStoreMemoryRequestSchema, exportMemoriesRequestSchema, forgetMemoryRequestSchema, getMemoryRequestSchema, handleSessionEndRequestSchema, importMemoriesRequestSchema, pullMemoriesRequestSchema, ingestSessionEventsRequestSchema, LIST_MEMORIES_DEFAULT_LIMIT, listMemoriesRequestSchema, pruneMemoriesRequestSchema, redactExistingRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, statsRequestSchema, storeMemoryRequestSchema, summarizeSessionToMemoryRequestSchema, } from "./contracts.js";
+import { batchStoreMemoryItemSchema, batchStoreMemoryRequestSchema, exportMemoriesRequestSchema, forgetMemoryRequestSchema, getMemoryRequestSchema, handleSessionEndRequestSchema, importMemoriesRequestSchema, pullMemoriesRequestSchema, ingestSessionEventsRequestSchema, LIST_MEMORIES_DEFAULT_LIMIT, listMemoriesRequestSchema, pruneMemoriesRequestSchema, redactExistingRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, searchMemoryIndexRequestSchema, memoryTimelineRequestSchema, statsRequestSchema, storeMemoryRequestSchema, summarizeSessionToMemoryRequestSchema, } from "./contracts.js";
 import { DomainError, toErrorEnvelope } from "./errors.js";
 import { assertLocalOnlyPolicy, } from "./localOnlyPolicy.js";
 import { createSessionLifecycleService } from "./sessionLifecycleService.js";
@@ -189,6 +192,48 @@ export function createMemoryCoreService(deps) {
         now: deps.now,
         deleteOldMemories: deps.deleteOldMemories,
     });
+    async function rankMemories(parsed, limit) {
+        const now = deps.now?.() ?? new Date();
+        const config = readPolicyConfig(policyConfigPath);
+        const intent = config.temporalRetrieval ? detectTemporalIntent(parsed.query, now) : { kind: "none" };
+        const includeHistory = parsed.includeHistory ?? intent.kind === "past";
+        let semanticCandidates;
+        try {
+            const embedder = await semanticEmbedder();
+            if (embedder)
+                semanticCandidates = await searchSemanticMemories(db, parsed.projectId, parsed.query, now, includeHistory, embedder);
+        }
+        catch {
+            semanticWarning();
+        }
+        const rankedAll = retrieveMemories({
+            db,
+            projectId: parsed.projectId,
+            queryText: parsed.query,
+            includeHistory,
+            temporalRetrieval: config.temporalRetrieval,
+            // Measured mode-specific default: coverage helps BM25, but regresses
+            // MiniLM recall. An explicit override always wins, including false.
+            entityLinkBoost: config.entityLinkBoost ?? (!semanticCandidates?.length && (!config.retrievalRanking || config.retrievalRanking === "legacy")),
+            ranking: config.retrievalRanking,
+            limit,
+            now,
+            semanticCandidates,
+        });
+        // Optional tag filter: keep a memory only when its stored tags contain ALL
+        // requested tags. The semantic candidate projection omits tags, so re-read
+        // each row's tags by id (this is an explicit, infrequent filter path).
+        const ranked = parsed.tags && parsed.tags.length > 0
+            ? rankedAll.filter((m) => {
+                const rec = getMemoryRecordById(db, parsed.projectId, m.id);
+                const recTags = rec?.tags
+                    ? JSON.parse(rec.tags)
+                    : [];
+                return parsed.tags.every((t) => recTags.includes(t));
+            })
+            : rankedAll;
+        return ranked.slice(0, limit);
+    }
     const methods = {
         async ingestSessionEvents(request) {
             const parsed = parseRequest(ingestSessionEventsRequestSchema, request);
@@ -340,36 +385,7 @@ export function createMemoryCoreService(deps) {
         async retrieveMemories(request) {
             const parsed = parseRequest(retrieveMemoriesRequestSchema, request);
             const limit = parsed.depth === "deep" ? Math.min(parsed.limit * 2, DEEP_MODE_RETRIEVAL_CAP) : parsed.limit;
-            let semanticCandidates;
-            try {
-                const embedder = await semanticEmbedder();
-                if (embedder)
-                    semanticCandidates = await searchSemanticMemories(db, parsed.projectId, parsed.query, deps.now?.() ?? new Date(), parsed.includeHistory ?? false, embedder);
-            }
-            catch {
-                semanticWarning();
-            }
-            const rankedAll = retrieveMemories({
-                db,
-                projectId: parsed.projectId,
-                queryText: parsed.query,
-                includeHistory: parsed.includeHistory,
-                limit,
-                now: deps.now?.(),
-                semanticCandidates,
-            });
-            // Optional tag filter: keep a memory only when its stored tags contain ALL
-            // requested tags. The semantic candidate projection omits tags, so re-read
-            // each row's tags by id (this is an explicit, infrequent filter path).
-            const ranked = parsed.tags && parsed.tags.length > 0
-                ? rankedAll.filter((m) => {
-                    const rec = getMemoryRecordById(db, parsed.projectId, m.id);
-                    const recTags = rec?.tags
-                        ? JSON.parse(rec.tags)
-                        : [];
-                    return parsed.tags.every((t) => recTags.includes(t));
-                })
-                : rankedAll;
+            const ranked = await rankMemories(parsed, limit);
             if (ranked.length > 0 && parsed.mode !== "on-demand") {
                 // Only boost access counts for startup injection (mode='auto'), not for
                 // explicit on-demand retrieval, so a mid-session lookup does not inflate
@@ -389,6 +405,17 @@ export function createMemoryCoreService(deps) {
                 }),
             };
         },
+        async searchMemoryIndex(request) {
+            const parsed = parseRequest(searchMemoryIndexRequestSchema, request);
+            const ranked = await rankMemories(parsed, parsed.limit + 1);
+            return { ok: true, memories: ranked.slice(0, parsed.limit).map(row => memoryIndexItem(row, row.score.total)),
+                hasMore: ranked.length > parsed.limit };
+        },
+        async memoryTimeline(request) {
+            const parsed = parseRequest(memoryTimelineRequestSchema, request);
+            const { rows, hasMore } = memoryTimeline(db, parsed, deps.now?.() ?? new Date());
+            return { ok: true, memories: rows.map(row => memoryIndexItem(row)), hasMore };
+        },
         async listMemories(request) {
             const parsed = parseRequest(listMemoriesRequestSchema, request);
             const all = listMemoriesByProject(db, parsed.projectId);

package/dist/core/config/policyConfig.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { RETRIEVAL_RANKINGS } from "../retrieve/signalFusion.js";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { mkdirSync, readFileSync, writeFileSync, renameSync } from "fs";
@@ -54,6 +55,9 @@ const policyConfigShape = {
     // `savings` analytics. Omitted by default so existing configs keep the default.
     injectionCap: z.number().int().min(100).max(10000).optional(),
     semanticSearch: z.boolean().optional(),
+    temporalRetrieval: z.boolean().optional(),
+    entityLinkBoost: z.boolean().optional(),
+    retrievalRanking: z.enum(RETRIEVAL_RANKINGS).optional(),
     team: teamConfigShape.default({ enabled: false }),
 };
 /**
@@ -109,12 +113,18 @@ export function readPolicyConfig(filePath) {
     const re = s.redactionEnabled.safeParse(obj.redactionEnabled);
     const ic = s.injectionCap.safeParse(obj.injectionCap);
     const ss = s.semanticSearch.safeParse(obj.semanticSearch);
+    const tr = s.temporalRetrieval.safeParse(obj.temporalRetrieval);
+    const el = s.entityLinkBoost.safeParse(obj.entityLinkBoost);
+    const rr = s.retrievalRanking.safeParse(obj.retrievalRanking);
     const tm = s.team.safeParse(obj.team);
     return {
         retentionDays: rd.success ? rd.data : DEFAULT_POLICY_CONFIG.retentionDays,
         redactionEnabled: re.success ? re.data : DEFAULT_POLICY_CONFIG.redactionEnabled,
         injectionCap: ic.success ? ic.data : undefined,
         semanticSearch: ss.success ? ss.data : undefined,
+        temporalRetrieval: tr.success ? tr.data : undefined,
+        entityLinkBoost: el.success ? el.data : undefined,
+        retrievalRanking: rr.success ? rr.data : undefined,
         team: tm.success ? tm.data : { ...DEFAULT_POLICY_CONFIG.team },
     };
 }

package/dist/core/retrieve/memoryIndex.js

@@ -0,0 +1,6 @@
+/** Extractive preview only. No generated summary or extra inference. */
+export function memoryIndexItem(memory, score = null) {
+    const text = memory.content.replace(/\s+/g, " ").trim();
+    return { id: memory.id, summary: text.length > 160 ? `${text.slice(0, 157)}...` : text,
+        kind: memory.kind, date: memory.created_at, score: score === null ? null : Math.round(score * 10000) / 10000 };
+}

package/dist/core/retrieve/retrieveMemories.js

@@ -1,8 +1,12 @@
 import { entityOverlap } from "../storage/knowledgeRepo.js";
+import { linkedEntityScores } from "../storage/entityLinkRepo.js";
+import { memoryTemporalMetadata } from "../storage/temporalRepo.js";
+import { adaptiveLexicalScore, additiveRelevance, SEMANTIC_GATE } from "./signalFusion.js";
+import { detectTemporalIntent, temporalRelevance } from "./temporalIntent.js";
 import { deterministicEmbed } from "../embed/deterministicEmbed.js";
 import { decayOldBoosts } from "./decay.js";
 import { scoreMemoryCandidate, } from "./score.js";
-import { searchMemoryCandidatesFTS, } from "../storage/memorySearchRepo.js";
+import { searchMemoryCandidatesFTS, searchMemoryCandidatesByIds, } from "../storage/memorySearchRepo.js";
 const DEFAULT_EMBEDDING_DIMENSION = 32;
 // Small, fixed contribution inside the existing relevance component. Keep the
 // public score shape/outer recency and importance weights unchanged.
@@ -45,11 +49,25 @@ export function retrieveMemories(input) {
     }
     const topK = input.topK ?? input.limit ?? 20;
     const now = input.now ?? new Date();
+    const ranking = input.ranking ?? "legacy";
+    const additive = ranking === "hub-additive" || ranking === "adaptive-hub-additive";
+    const adaptive = ranking === "adaptive-bm25" || ranking === "adaptive-hub-additive";
+    const intent = input.temporalRetrieval ? detectTemporalIntent(queryText, now) : { kind: "none" };
+    const includeHistory = input.includeHistory ?? intent.kind === "past";
     // FTS5 retrieves up to 50 BM25 matches; sparse matches retain the existing
     // recency/importance fallback. The public request schema validates queryText.
-    const lexicalCandidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now, input.includeHistory);
+    const lexicalCandidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now, includeHistory);
     const candidates = [...lexicalCandidates];
     const ids = new Set(candidates.map(c => c.id));
+    const linked = input.entityLinkBoost || additive
+        ? linkedEntityScores(input.db, input.projectId, queryText, now, includeHistory, additive)
+        : new Map();
+    for (const candidate of searchMemoryCandidatesByIds(input.db, input.projectId, [...linked.keys()].slice(0, 50), now, includeHistory)) {
+        if (!ids.has(candidate.id)) {
+            candidates.push(candidate);
+            ids.add(candidate.id);
+        }
+    }
     for (const { candidate } of input.semanticCandidates ?? []) {
         if (!ids.has(candidate.id)) {
             candidates.push(candidate);
@@ -61,10 +79,12 @@ export function retrieveMemories(input) {
     const dimension = resolveEmbeddingDimension(candidates);
     const queryVector = deterministicEmbed(queryText, dimension).vector;
     const overlap = entityOverlap(input.db, input.projectId, queryText, now);
+    const temporal = intent.kind !== "none" ? memoryTemporalMetadata(input.db, input.projectId, candidates.map(c => c.id)) : new Map();
     // FTS5 returns negative BM25 ranks; storage converts them to positive scores.
     // Normalize within this query so BM25 fits the existing relevance weight.
     const maxLexicalScore = candidates.reduce((max, candidate) => Math.max(max, candidate.lexical_score), 0);
     const ranked = decayedCandidates
+        .filter(candidate => !additive || !input.semanticCandidates?.length || (dense.get(candidate.id) ?? 0) >= SEMANTIC_GATE)
         .map((candidate) => {
         // When embedding is null (version mismatch or missing), use a neutral
         // score of 0.5 so the memory is neither penalized nor boosted. A non-null
@@ -78,7 +98,7 @@ export function retrieveMemories(input) {
         // Hash cosine is useful for identical text, but adds noise to lexical
         // matches. Keep it as a diagnostic and as the no-match fallback only.
         const lexicalRelevance = maxLexicalScore > 0
-            ? candidate.lexical_score / maxLexicalScore
+            ? adaptive ? adaptiveLexicalScore(candidate.lexical_score, queryText) : candidate.lexical_score / maxLexicalScore
             : semantic;
         // The local dense variant was weaker alone. Preserve lexical dominance
         // while admitting candidates absent from FTS, using a fixed 2:1 blend.
@@ -87,15 +107,27 @@ export function retrieveMemories(input) {
                 ? (2 * lexicalRelevance + Math.max(0, dense.get(candidate.id) ?? 0)) / 3
                 : Math.max(0, dense.get(candidate.id) ?? 0)
             : lexicalRelevance;
-        const relevance = overlap.size > 0
-            ? (1 - ENTITY_RELEVANCE_WEIGHT) * baseRelevance + ENTITY_RELEVANCE_WEIGHT * (overlap.get(candidate.id) ?? 0)
-            : baseRelevance;
+        const fused = additive ? additiveRelevance({
+            lexical: maxLexicalScore > 0 ? lexicalRelevance : undefined,
+            dense: input.semanticCandidates?.length ? Math.max(0, dense.get(candidate.id) ?? 0) : undefined,
+            entity: linked.size > 0 ? linked.get(candidate.id) ?? 0 : undefined,
+        }) : null;
+        const entityRelevance = additive && fused !== null ? fused : linked.size > 0
+            ? 0.8 * baseRelevance + 0.2 * (linked.get(candidate.id) ?? 0)
+            : overlap.size > 0
+                ? (1 - ENTITY_RELEVANCE_WEIGHT) * baseRelevance + ENTITY_RELEVANCE_WEIGHT * (overlap.get(candidate.id) ?? 0)
+                : baseRelevance;
+        const metadata = temporal.get(candidate.id);
+        const relevance = metadata
+            ? 0.9 * entityRelevance + 0.1 * temporalRelevance(intent, metadata.timestamp, metadata.supersededFraction, now)
+            : entityRelevance;
         const score = scoreMemoryCandidate({
             semantic: relevance,
-            updated_at: candidate.updated_at,
+            // Historical lookup should not lose evidence merely because it is old.
+            updated_at: intent.kind === "past" ? now.toISOString() : candidate.updated_at,
             importance: candidate.importance,
             access_count: candidate.access_count,
-            decayedImportance: candidate.decayedImportance,
+            decayedImportance: intent.kind === "past" ? candidate.importance : candidate.decayedImportance,
         }, now);
         return {
             id: candidate.id,

package/dist/core/retrieve/signalFusion.js

@@ -0,0 +1,21 @@
+import { lexicalQueryTerms } from "../storage/memorySearchRepo.js";
+export const RETRIEVAL_RANKINGS = ["legacy", "adaptive-bm25", "hub-additive", "adaptive-hub-additive"];
+/** Fixed hypotheses from the requested public-source audit, independently implemented. */
+export function adaptiveLexicalScore(raw, query) {
+    if (raw <= 0 || !Number.isFinite(raw))
+        return 0;
+    const count = lexicalQueryTerms(query).length;
+    const bands = [[3, 5, 0.7], [6, 7, 0.6], [9, 9, 0.5], [15, 10, 0.5], [Infinity, 12, 0.5]];
+    const [, midpoint, steepness] = bands.find(([ceiling]) => count <= ceiling);
+    return 1 / (1 + Math.exp(steepness * (midpoint - raw)));
+}
+export const SEMANTIC_GATE = 0.2;
+export function additiveRelevance(signals) {
+    if (signals.dense !== undefined && signals.dense < SEMANTIC_GATE)
+        return null;
+    const capacity = Number(signals.lexical !== undefined) + Number(signals.dense !== undefined) + 0.5 * Number(signals.entity !== undefined);
+    if (!capacity)
+        return 0;
+    const sum = (signals.lexical ?? 0) + (signals.dense ?? 0) + (signals.entity ?? 0);
+    return Math.max(0, Math.min(1, sum / capacity));
+}

package/dist/core/retrieve/temporalIntent.js

@@ -0,0 +1,59 @@
+const DAY = 86_400_000;
+function range(start, end) {
+    return { kind: "past", start, end };
+}
+export function detectTemporalIntent(query, now) {
+    const text = query.normalize("NFKC").toLowerCase();
+    // A dated or historical clause takes precedence over a current-state cue.
+    const iso = /\b(\d{4})-(\d{2})(?:-(\d{2}))?\b/.exec(text);
+    if (iso) {
+        const year = Number(iso[1]), month = Number(iso[2]) - 1, day = Number(iso[3] ?? 1);
+        const start = Date.UTC(year, month, day);
+        const date = new Date(start);
+        if (date.getUTCFullYear() === year && date.getUTCMonth() === month && date.getUTCDate() === day) {
+            return range(start, iso[3] ? start + DAY : Date.UTC(year, month + 1, 1));
+        }
+    }
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    if (/\byesterday\b/.test(text))
+        return range(today - DAY, today);
+    const relative = /\b(?:last|previous) (week|month|year)\b/.exec(text);
+    if (relative) {
+        const year = now.getUTCFullYear(), month = now.getUTCMonth();
+        if (relative[1] === "month")
+            return range(Date.UTC(year, month - 1, 1), Date.UTC(year, month, 1));
+        if (relative[1] === "year")
+            return range(Date.UTC(year - 1, 0, 1), Date.UTC(year, 0, 1));
+        // Calendar weeks start on Monday, in UTC.
+        const monday = today - ((now.getUTCDay() + 6) % 7) * DAY;
+        return range(monday - 7 * DAY, monday);
+    }
+    const ago = /\b(\d{1,3}) (day|week)s? ago\b/.exec(text);
+    if (ago) {
+        const start = today - Number(ago[1]) * (ago[2] === "week" ? 7 : 1) * DAY;
+        return range(start, start + (ago[2] === "week" ? 7 : 1) * DAY);
+    }
+    const year = /\b(?:in|during) ((?:19|20)\d{2})\b/.exec(text);
+    if (year)
+        return range(Date.UTC(Number(year[1]), 0, 1), Date.UTC(Number(year[1]) + 1, 0, 1));
+    if (/\b(before|previously|formerly|prior|used to|no longer)\b/.test(text))
+        return { kind: "past", previous: true };
+    if (/\b(when (?:did|was|were)|in the past|historical|history)\b/.test(text))
+        return { kind: "past" };
+    if (/\b(current|currently|now|latest|today|at present)\b/.test(text))
+        return { kind: "current" };
+    return { kind: "none" };
+}
+/** A bounded signal, separate from lexical relevance. Missing dates stay neutral. */
+export function temporalRelevance(intent, timestamp, supersededFraction, now) {
+    const time = Date.parse(timestamp);
+    if (intent.kind === "current") {
+        const freshness = Number.isFinite(time) ? 1 / (1 + Math.max(0, now.getTime() - time) / (30 * DAY)) : 0.5;
+        return (1 - supersededFraction + freshness) / 2;
+    }
+    if (intent.start !== undefined && intent.end !== undefined && Number.isFinite(time)) {
+        const distance = time < intent.start ? intent.start - time : time >= intent.end ? time - intent.end + 1 : 0;
+        return 1 / (1 + distance / (30 * DAY));
+    }
+    return intent.previous ? supersededFraction : 0.5;
+}

package/dist/core/storage/entityLinkRepo.js

@@ -0,0 +1,47 @@
+import { queryEntityNames } from "../extract/knowledge.js";
+// Explicit spelling aliases only. No fuzzy matching or inferred coreference.
+const ALIASES = [["postgres", "postgresql"], ["node", "node.js"], ["k8s", "kubernetes"]];
+/** Link literal query names to existing entities, then weight rare names more. */
+export function linkedEntityScores(db, projectId, query, now, includeHistory, hubDamping = false) {
+    const names = new Set(queryEntityNames(query));
+    for (const group of ALIASES)
+        if (group.some(name => names.has(name)))
+            for (const name of group)
+                names.add(name);
+    const rows = db.prepare(`SELECT DISTINCT e.memory_id, e.kind, e.name FROM memory_entities e
+    JOIN memories m ON m.id = e.memory_id
+    WHERE m.project_id = ? AND (m.expires_at IS NULL OR m.expires_at > ?)
+      AND (? = 1 OR m.id NOT IN (SELECT memory_id FROM superseded_memories))
+      AND e.name IN (SELECT value FROM json_each(?)) ORDER BY e.kind, e.name, e.memory_id`)
+        .all(projectId, now.toISOString(), Number(includeHistory), JSON.stringify([...names]));
+    const frequencies = new Map();
+    const key = (row) => `${row.kind}:${row.name}`;
+    for (const row of rows)
+        frequencies.set(key(row), (frequencies.get(key(row)) ?? 0) + 1);
+    if (hubDamping) {
+        // Match at most eight stored names, preferring specific spans. Exact and
+        // explicit alias matches have similarity 1; no entity model is implied.
+        const selected = new Set([...new Set(rows.map(row => row.name))]
+            .sort((a, b) => b.length - a.length || a.localeCompare(b)).slice(0, 8));
+        const boosts = new Map();
+        for (const row of rows) {
+            if (!selected.has(row.name))
+                continue;
+            const degree = frequencies.get(key(row));
+            const boost = 0.5 / (1 + 0.001 * (degree - 1) ** 2);
+            boosts.set(row.memory_id, Math.max(boosts.get(row.memory_id) ?? 0, boost));
+        }
+        return new Map([...boosts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+    }
+    const total = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE project_id = ?
+    AND (expires_at IS NULL OR expires_at > ?)
+    AND (? = 1 OR id NOT IN (SELECT memory_id FROM superseded_memories))`)
+        .get(projectId, now.toISOString(), Number(includeHistory)).n;
+    const weights = new Map([...frequencies].map(([name, count]) => [name, 1 + Math.log((total + 1) / (count + 1))]));
+    const denominator = [...weights.values()].reduce((a, b) => a + b, 0);
+    const scores = new Map();
+    for (const row of rows)
+        scores.set(row.memory_id, (scores.get(row.memory_id) ?? 0) + weights.get(key(row)) / denominator);
+    // Keep scores for all existing lexical/dense candidates. Only admission is capped.
+    return new Map([...scores].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+}

package/dist/core/storage/memorySearchRepo.js

@@ -118,13 +118,15 @@ const QUERY_STOP_WORDS = new Set(("a an and are as at be been being but by can c
     "where which who whom why will with would you your yours yourself yourselves " +
     "s t don doesn didn isn wasn weren won wouldn couldn shouldn").split(" "));
 /** Match any meaningful query term; question grammar must not exclude evidence. */
-function sanitizeFtsQuery(queryText) {
+export function lexicalQueryTerms(queryText) {
     const tokens = [...new Set(queryText.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])];
     const terms = tokens.filter((token) => !QUERY_STOP_WORDS.has(token));
     // Preserve literal searches consisting entirely of stop words. Tokens contain
     // only letters/numbers, so FTS operators and punctuation cannot become syntax.
-    return (terms.length ? terms : tokens)
-        .slice(0, 64)
+    return (terms.length ? terms : tokens).slice(0, 64);
+}
+function sanitizeFtsQuery(queryText) {
+    return lexicalQueryTerms(queryText)
         .map((token) => `"${token}"`)
         .join(" OR ");
 }

package/dist/core/storage/temporalRepo.js

@@ -0,0 +1,13 @@
+/** Use claim observation times when available, otherwise the original capture time. */
+export function memoryTemporalMetadata(db, projectId, ids) {
+    const rows = db.prepare(`SELECT m.id, m.created_at, MAX(c.observed_at) AS observed_at,
+    COUNT(c.claim_key) AS claims, COUNT(s.claim_key) AS superseded
+    FROM memories m LEFT JOIN memory_claims c ON c.memory_id = m.id
+    LEFT JOIN memory_supersessions s ON s.supersedes = c.memory_id AND s.claim_key = c.claim_key
+    WHERE m.project_id = ? AND m.id IN (SELECT value FROM json_each(?)) GROUP BY m.id`)
+        .all(projectId, JSON.stringify(ids));
+    return new Map(rows.map(row => [row.id, {
+            timestamp: row.observed_at ?? row.created_at,
+            supersededFraction: row.claims ? row.superseded / row.claims : 0,
+        }]));
+}

package/dist/core/storage/timelineRepo.js

@@ -0,0 +1,27 @@
+import { DomainError } from "../api/errors.js";
+/** Small SQL projections, stable ordering, and no access-count writes. */
+export function memoryTimeline(db, input, now) {
+    const visible = `project_id = @projectId AND (expires_at IS NULL OR expires_at > @now)
+    AND (@history = 1 OR id NOT IN (SELECT memory_id FROM superseded_memories))`;
+    const bindings = { projectId: input.projectId, now: now.toISOString(), history: Number(input.includeHistory) };
+    // Project only enough text for the one-line summary, never embeddings or bodies.
+    const select = `SELECT id, substr(content, 1, 1000) AS content, kind, created_at FROM memories WHERE ${visible}`;
+    if (!input.memoryId) {
+        const rows = db.prepare(`${select} AND created_at >= @fromDate AND created_at <= @toDate
+      ORDER BY created_at, id LIMIT @limit`).all({ ...bindings,
+            fromDate: new Date(input.fromDate).toISOString(), toDate: new Date(input.toDate).toISOString(), limit: input.limit + 1, });
+        return { rows: rows.slice(0, input.limit), hasMore: rows.length > input.limit };
+    }
+    const anchor = db.prepare(`${select} AND id = @memoryId`).get({ ...bindings, memoryId: input.memoryId });
+    if (!anchor)
+        throw new DomainError("NOT_FOUND", `Memory not found: ${input.memoryId}`);
+    const params = { ...bindings, date: anchor.created_at, id: anchor.id, limit: input.limit + 1 };
+    const before = db.prepare(`${select} AND (created_at < @date OR (created_at = @date AND id < @id))
+    ORDER BY created_at DESC, id DESC LIMIT @limit`).all(params);
+    const after = db.prepare(`${select} AND (created_at > @date OR (created_at = @date AND id > @id))
+    ORDER BY created_at, id LIMIT @limit`).all(params);
+    const left = Math.min(before.length, Math.max(Math.floor((input.limit - 1) / 2), input.limit - 1 - after.length));
+    const right = Math.min(after.length, input.limit - 1 - left);
+    return { rows: [...before.slice(0, left).reverse(), anchor, ...after.slice(0, right)],
+        hasMore: before.length + after.length + 1 > input.limit };
+}