@oh-my-pi/pi-mnemopi 16.3.6 → 16.3.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [16.3.7] - 2026-07-05
+
+### Added
+
+- Added `RecallOptions.contentPreviewChars` to allow customizing or disabling the content preview cap (default is 500, set to 0 for full content).
+- Added `RecallResult.truncated` and `RecallResult.full_length` properties to easily identify clipped previews without parsing trailing markers.
+
+### Fixed
+
+- Fixed background LLM fact extraction to preserve specific extractor categories (`instructions`, `preferences`, `timelines`, and `kg` triples) in MEMORIA tables and graph triples instead of flattening them into generic `fact/entity` rows.
+- Improved recall previews and `factLine` context to append a trailing ellipsis (`…`) when content is clipped, preventing mid-word truncation without a marker.
+
 ## [16.3.5] - 2026-07-04
 
 ### Fixed

package/dist/types/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { BeamMemory } from "./core/beam";
+import { BeamMemory } from "./core/beam/index.js";
 export interface CliIo {
     write(data: string): void;
 }

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import { type Env, envBool, envDisabled, envFloat, envInt, envOneOf, envOptionalString, envString, envTruthy } from "./util/env";
+import { type Env, envBool, envDisabled, envFloat, envInt, envOneOf, envOptionalString, envString, envTruthy } from "./util/env.js";
 export type { Env };
 export { envBool, envDisabled, envFloat, envInt, envOneOf, envOptionalString, envString, envTruthy };
 export declare const DEFAULT_DATA_DIR: string;

package/dist/types/core/beam/consolidate.d.ts

@@ -1,4 +1,5 @@
-import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types";
+import { type ExtractedFactCategories } from "../extraction.js";
+import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types.js";
 type Row = Record<string, unknown>;
 type FactCounts = {
     metric: number;
@@ -18,7 +19,12 @@ type ConsolidateOptions = {
 };
 export declare function consolidateToEpisodic(beam: BeamMemoryState, summary: string, sourceWmIds: readonly string[], source?: string, importance?: number, options?: ConsolidateOptions): string;
 export declare function detectLanguage(_beam: BeamMemoryState, text: string): string;
-export declare function storeFactStrings(beam: BeamMemoryState, facts: readonly string[], messageIdx?: number, sourceMemoryId?: string | null, importance?: number): number;
+type StoreFactStringOptions = {
+    routeHeuristicCategories?: boolean;
+};
+export declare function storeFactStrings(beam: BeamMemoryState, facts: readonly string[], messageIdx?: number, sourceMemoryId?: string | null, importance?: number, options?: StoreFactStringOptions): number;
+/** Store category-preserving LLM extraction output in MEMORIA and KG tables. */
+export declare function storeExtractedFactCategories(beam: BeamMemoryState, extracted: ExtractedFactCategories, messageIdx?: number, sourceMemoryId?: string | null, importance?: number): number;
 export declare function extractAndStoreFacts(beam: BeamMemoryState, content: string, messageIdx?: number, sourceMemoryId?: string | null): FactCounts;
 export declare function memoriaRetrieve(beam: BeamMemoryState, query: string, ability?: string | null, topK?: number): MemoriaRetrieveResult;
 export declare function getEpisodicStats(beam: BeamMemoryState, authorId?: string | null, authorType?: string | null, channelId?: string | null): BeamStats;

package/dist/types/core/beam/helpers.d.ts

@@ -1,7 +1,7 @@
 import type { Database } from "bun:sqlite";
-import { sha256Hex16 } from "../../util/ids";
-import { cjkFtsTerms, containsSpacelessCjk, ftsQueryTerms, recallTokens } from "../../util/regex";
-import type { BeamMemoryState, Metadata } from "./types";
+import { sha256Hex16 } from "../../util/ids.js";
+import { cjkFtsTerms, containsSpacelessCjk, ftsQueryTerms, recallTokens } from "../../util/regex.js";
+import type { BeamMemoryState, Metadata } from "./types.js";
 export type Vector = number[];
 export type HybridWeights = readonly [vecWeight: number, ftsWeight: number, importanceWeight: number];
 export interface VectorDistanceResult {
@@ -48,7 +48,7 @@ export declare function normalizeMetadata(input: unknown): Metadata;
 export declare function metadataJson(input: unknown): string;
 export declare function detectLanguage(text: string): string;
 export declare function memoryRowMetadata(row: unknown): Metadata;
-export { cosineSimilarity, hammingDistance, informationTheoreticScore, maximallyInformativeBinarization, quantizeInt8, } from "../binary-vectors";
+export { cosineSimilarity, hammingDistance, informationTheoreticScore, maximallyInformativeBinarization, quantizeInt8, } from "../binary-vectors.js";
 export { cjkFtsTerms, containsSpacelessCjk, ftsQueryTerms, recallTokens, sha256Hex16 };
 /** Identifies one freshly stored memory whose embedding still needs to be derived. */
 export interface EmbedItem {

package/dist/types/core/beam/index.d.ts

@@ -1,7 +1,7 @@
 import type { Database } from "bun:sqlite";
-import type { BeamCaches, BeamConfig, BeamEvent, BeamMemoryOptions, BeamMemoryState, BeamStats, ImportStats, MemoriaRetrieveResult, Metadata, RecallEnhancedOptions, RecallOptions, RecallResult, RememberBatchItem, RememberBatchOptions, RememberOptions, SleepResult } from "./types";
-export { initBeam } from "./schema";
-export type * from "./types";
+import type { BeamCaches, BeamConfig, BeamEvent, BeamMemoryOptions, BeamMemoryState, BeamStats, ImportStats, MemoriaRetrieveResult, Metadata, RecallEnhancedOptions, RecallOptions, RecallResult, RememberBatchItem, RememberBatchOptions, RememberOptions, SleepResult } from "./types.js";
+export { initBeam } from "./schema.js";
+export type * from "./types.js";
 export declare class BeamMemory implements BeamMemoryState {
     #private;
     readonly db: Database;

package/dist/types/core/beam/recall.d.ts

@@ -1,4 +1,4 @@
-import type { BeamMemoryState, RecallEnhancedOptions, RecallOptions, RecallResult } from "./types";
+import type { BeamMemoryState, RecallEnhancedOptions, RecallOptions, RecallResult } from "./types.js";
 type RecallOptionsInternal = RecallOptions & {
     source?: string | null;
     topic?: string | null;
@@ -23,6 +23,26 @@ type FactRecallResult = RecallResult & {
     subject?: string;
     predicate?: string;
 };
+/**
+ * Default per-result content preview cap enforced by {@link recall}. Content
+ * longer than this is clipped and the last character replaced with `…` so
+ * callers see the truncation; the full row remains reachable via
+ * `Mnemopi.get()` (and, in the coding-agent, `memory://<id>`). Overridable per
+ * call via {@link RecallOptions.contentPreviewChars}.
+ */
+export declare const RECALL_CONTENT_PREVIEW_CHARS = 500;
+/**
+ * Clip `content` to at most `limit` characters, replacing the tail with `…`
+ * when truncated so agents can distinguish a preview from a full row. Returns
+ * the original string (and `truncated: false`) when the limit is 0/negative or
+ * the content already fits. The single `…` occupies one character of the cap,
+ * so a 500-char cap yields at most 499 real characters plus the marker.
+ */
+export declare function clipRecallContent(content: string, limit?: number): {
+    content: string;
+    truncated: boolean;
+    fullLength: number;
+};
 export declare function parseQueryTime(value: RecallOptionsInternal["queryTime"]): Date;
 export declare function temporalBoost(timestamp: unknown, queryTime: Date, halfLifeHours: number): number;
 export declare function recall(beam: BeamMemoryState, query: string, topK?: number, options?: RecallOptionsInternal): Promise<RecallResult[]>;

package/dist/types/core/beam/store.d.ts

@@ -1,4 +1,4 @@
-import type { BeamMemoryState, BeamStats, ImportStats, RememberBatchItem, RememberBatchOptions, RememberOptions } from "./types";
+import type { BeamMemoryState, BeamStats, ImportStats, RememberBatchItem, RememberBatchOptions, RememberOptions } from "./types.js";
 type Row = Record<string, unknown>;
 type StoreRememberOptions = RememberOptions & {
     memoryId?: string;

package/dist/types/core/beam/types.d.ts

@@ -148,6 +148,15 @@ export interface RecallOptions {
     useIntent?: boolean;
     useMmr?: boolean;
     mmrLambda?: number;
+    /**
+     * Maximum characters of `content` returned per {@link RecallResult}. When the
+     * stored content exceeds this, the preview is clipped and the trailing
+     * character is replaced with `…` so callers can see it was truncated. The
+     * full row is always reachable via {@link BeamMemoryState.get}. `0` or a
+     * negative value disables clipping. Defaults to
+     * {@link RECALL_CONTENT_PREVIEW_CHARS} (500).
+     */
+    contentPreviewChars?: number;
 }
 export interface RecallEnhancedOptions extends RecallOptions {
     useCache?: boolean;
@@ -206,6 +215,15 @@ export type RecallResult = RecallRowFields & {
     [key: string]: unknown;
     id: string;
     content: string;
+    /**
+     * True when {@link content} is a clipped preview of the stored row. The
+     * clip is capped at {@link RecallOptions.contentPreviewChars} (default 500)
+     * and the last character is replaced with `…`. Fetch the full row via
+     * `memory://<id>` (mnemopi backend) or the `Mnemopi.get(id)` API.
+     */
+    truncated?: boolean;
+    /** Original character count of `content` before {@link truncated} clipping. */
+    full_length?: number;
     score?: number;
     distance?: number;
     rank?: number;

package/dist/types/core/binary-vectors.d.ts

@@ -1,7 +1,7 @@
 import type { Database } from "bun:sqlite";
-import { type VecType } from "../config";
-import { type DatabasePath } from "../db";
-export { cosineSimilarity } from "./vector-math";
+import { type VecType } from "../config.js";
+import { type DatabasePath } from "../db.js";
+export { cosineSimilarity } from "./vector-math.js";
 export declare const BITS_PER_BYTE = 8;
 export declare const EMBEDDING_DIM: number;
 export declare const BYTES_PER_VECTOR: number;

package/dist/types/core/embeddings.d.ts

@@ -1,7 +1,7 @@
 import type { EmbeddingModel } from "fastembed";
-import { type EmbeddingOutput } from "./runtime-options";
-export type { EmbeddingOutput } from "./runtime-options";
-export { cosineSimilarity } from "./vector-math";
+import { type EmbeddingOutput } from "./runtime-options.js";
+export type { EmbeddingOutput } from "./runtime-options.js";
+export { cosineSimilarity } from "./vector-math.js";
 export type Vector = Float32Array;
 export type EmbeddingMatrix = Vector[];
 export interface EmbeddingProvider {

package/dist/types/core/episodic-graph.d.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { type DatabasePath } from "../db";
+import { type DatabasePath } from "../db.js";
 export interface Gist {
     readonly id: string;
     readonly text: string;

package/dist/types/core/extraction.d.ts

@@ -1,7 +1,34 @@
-import { type RemoteLlmOptions } from "./local-llm";
+import { type RemoteLlmOptions } from "./local-llm.js";
 export declare const EXTRACTION_PROMPT_TEMPLATE: string;
 export declare function buildExtractionPrompt(text: string, detectedLang?: string): string;
+/** Parsed knowledge-graph edge emitted by the extractor LLM. */
+export interface ExtractedKgTriple {
+    subject: string;
+    predicate: string;
+    object: string;
+}
+/** Category-preserving extraction result used by background memory routing. */
+export interface ExtractedFactCategories {
+    facts: string[];
+    instructions: string[];
+    preferences: string[];
+    timelines: string[];
+    kg: ExtractedKgTriple[];
+}
+/** Flatten extracted string categories for legacy fact callers. */
+export declare function flattenExtractedFactCategories(extracted: ExtractedFactCategories): string[];
+/** Count string facts plus KG triples in a category-preserving extraction result. */
+export declare function countExtractedFactCategories(extracted: ExtractedFactCategories): number;
+/** Parse extractor output without discarding MEMORIA categories or KG triples. */
+export declare function parseExtractedFactCategories(rawOutput: string | null | undefined): ExtractedFactCategories;
+/** Parse extractor output into the legacy flat string fact list. */
 export declare function parseFacts(rawOutput: string | null | undefined): string[];
 export declare function heuristicExtractFacts(text: string): string[];
+/** Extract fact categories from text using configured, host, local, or remote LLMs. */
+export declare function extractFactCategories(text: string | null | undefined, options?: RemoteLlmOptions): Promise<ExtractedFactCategories>;
+/** Extract legacy flat fact strings from text. */
 export declare function extractFacts(text: string | null | undefined, options?: RemoteLlmOptions): Promise<string[]>;
+/** Safely extract category-preserving facts, swallowing best-effort failures. */
+export declare function extractFactCategoriesSafe(text: string | null | undefined): Promise<ExtractedFactCategories>;
+/** Safely extract legacy flat fact strings, swallowing best-effort failures. */
 export declare function extractFactsSafe(text: string | null | undefined): Promise<string[]>;

package/dist/types/core/index.d.ts

@@ -1,6 +1,6 @@
-export { configureRecallFeatures, type RecallFeatureFlags } from "../config";
-export * from "./banks";
-export * from "./beam/index";
-export { type LocalEmbeddingModel, type LocalModelInitializer, type LocalModelInitOptions, type StandardEmbeddingModel, setLocalModelInitializer, } from "./embeddings";
-export * from "./memory";
-export { addMemory, forget, get, getBank, getContext, getDefaultInstance, getStats, Mnemopi, query, recall, recallEnhanced, remember, resetDefaultInstanceForTests, resetMemoryForTests, resetModuleStateForTests, saveMemory, scratchpadClear, scratchpadRead, scratchpadWrite, search, setBank, sleep, sleepAllSessions, storeMemory, update, } from "./memory";
+export { configureRecallFeatures, type RecallFeatureFlags } from "../config.js";
+export * from "./banks.js";
+export * from "./beam/index.js";
+export { type LocalEmbeddingModel, type LocalModelInitializer, type LocalModelInitOptions, type StandardEmbeddingModel, setLocalModelInitializer, } from "./embeddings.js";
+export * from "./memory.js";
+export { addMemory, forget, get, getBank, getContext, getDefaultInstance, getStats, Mnemopi, query, recall, recallEnhanced, remember, resetDefaultInstanceForTests, resetMemoryForTests, resetModuleStateForTests, saveMemory, scratchpadClear, scratchpadRead, scratchpadWrite, search, setBank, sleep, sleepAllSessions, storeMemory, update, } from "./memory.js";

package/dist/types/core/local-llm.d.ts

@@ -1,6 +1,6 @@
 import { type FetchImpl } from "@oh-my-pi/pi-ai";
-import { type CompleteOptions } from "./llm-backends";
-import { type MnemopiLlmCompleteOptions } from "./runtime-options";
+import { type CompleteOptions } from "./llm-backends.js";
+import { type MnemopiLlmCompleteOptions } from "./runtime-options.js";
 export interface RemoteLlmOptions {
     fetch?: FetchImpl;
 }

package/dist/types/core/memory.d.ts

@@ -1,9 +1,9 @@
 import type { Database } from "bun:sqlite";
 import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
-import type { MemoryInput, Metadata } from "../types";
-import { BeamMemory } from "./beam/index";
-import type { RecallEnhancedOptions, RecallOptions, RecallResult, SleepResult } from "./beam/types";
-import { type MnemopiEmbeddingRuntimeOptions, type MnemopiLlmCompletion, type MnemopiLlmRuntimeOptions, type ResolvedMnemopiRuntimeOptions } from "./runtime-options";
+import type { MemoryInput, Metadata } from "../types.js";
+import { BeamMemory } from "./beam/index.js";
+import type { RecallEnhancedOptions, RecallOptions, RecallResult, SleepResult } from "./beam/types.js";
+import { type MnemopiEmbeddingRuntimeOptions, type MnemopiLlmCompletion, type MnemopiLlmRuntimeOptions, type ResolvedMnemopiRuntimeOptions } from "./runtime-options.js";
 export interface MnemopiOptions {
     readonly db?: Database;
     readonly dbPath?: string;
@@ -182,5 +182,5 @@ export declare function query(query: string, topK?: number, options?: ModuleReca
 export declare function resetDefaultInstanceForTests(): void;
 export declare function resetMemoryForTests(): void;
 export declare function resetModuleStateForTests(): void;
-export type { MemoryInput, MemoryStats } from "../types";
+export type { MemoryInput, MemoryStats } from "../types.js";
 export default Mnemopi;

package/dist/types/core/migrations/e6-triplestore-split.d.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { type DatabasePath } from "../../db";
+import { type DatabasePath } from "../../db.js";
 export declare const ANNOTATION_KINDS: readonly ["mentions", "fact", "occurred_on", "has_source"];
 export type AnnotationKind = (typeof ANNOTATION_KINDS)[number];
 export interface MigrationOptions {

package/dist/types/core/migrations/index.d.ts

@@ -1 +1 @@
-export * from "./e6-triplestore-split";
+export * from "./e6-triplestore-split.js";

package/dist/types/core/orchestrator.d.ts

@@ -1,5 +1,5 @@
-import type { BeamMemoryState, RecallOptions, RecallResult } from "./beam/types";
-import { type PolyphonicMemoryResult, type PolyphonicRecallOptions } from "./polyphonic-recall";
+import type { BeamMemoryState, RecallOptions, RecallResult } from "./beam/types.js";
+import { type PolyphonicMemoryResult, type PolyphonicRecallOptions } from "./polyphonic-recall.js";
 export interface OrchestratorBeam extends BeamMemoryState {
     recall?: (query: string, topK?: number, options?: RecallOptions) => Promise<RecallResult[]>;
     recallEnhanced?: (query: string, topK?: number, options?: RecallOptions) => Promise<RecallResult[]>;

package/dist/types/core/polyphonic-recall.d.ts

@@ -1,9 +1,9 @@
 import type { Database } from "bun:sqlite";
-import { type Env } from "../config";
-import { type DatabasePath } from "../db";
-import type { BeamMemoryState, JsonValue, Metadata, RecallResult } from "./beam/types";
-import { EpisodicGraph } from "./episodic-graph";
-import { VeracityConsolidator } from "./veracity-consolidation";
+import { type Env } from "../config.js";
+import { type DatabasePath } from "../db.js";
+import type { BeamMemoryState, JsonValue, Metadata, RecallResult } from "./beam/types.js";
+import { EpisodicGraph } from "./episodic-graph.js";
+import { VeracityConsolidator } from "./veracity-consolidation.js";
 export type PolyphonicVoice = "vector" | "graph" | "fact" | "temporal";
 export interface VoiceRecallResult {
     readonly memoryId: string;

package/dist/types/core/query-cache.d.ts

@@ -1,4 +1,4 @@
-import { type Env } from "../config";
+import { type Env } from "../config.js";
 export type QueryCacheResult = Record<string, unknown>;
 export type QueryEmbedding = readonly number[];
 export interface QueryCacheOptions {

package/dist/types/core/shmr.d.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { cosineSimilarity } from "./vector-math";
+import { cosineSimilarity } from "./vector-math.js";
 export { cosineSimilarity };
 export declare const SHMR_BATCH_SIZE: number;
 export declare const SHMR_MAX_ITERATIONS: number;

package/dist/types/core/temporal-parser.d.ts

@@ -1,4 +1,4 @@
-import { type QueryTime } from "../util/datetime";
+import { type QueryTime } from "../util/datetime.js";
 export type DatePrecision = "day" | "week" | "month" | "year" | "relative" | "unknown";
 export type ParsedNaturalDate = [eventDate: Date, precision: Exclude<DatePrecision, "unknown">, temporalTags: string[]];
 export interface TemporalInfo {

package/dist/types/core/triples.d.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { type DatabasePath } from "../db";
+import { type DatabasePath } from "../db.js";
 export interface TripleRow {
     id: number;
     subject: string;

package/dist/types/core/veracity-consolidation.d.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { type DatabasePath } from "../db";
+import { type DatabasePath } from "../db.js";
 export declare const VERACITY_WEIGHTS: Readonly<{
     stated: 1;
     inferred: 0.7;

package/dist/types/dr/index.d.ts

@@ -1 +1 @@
-export * from "./recovery";
+export * from "./recovery.js";

package/dist/types/dr/recovery.d.ts

@@ -1,4 +1,4 @@
-import { type Env } from "../config";
+import { type Env } from "../config.js";
 export interface RecoveryPaths {
     readonly dataDir: string;
     readonly backupDir: string;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
-export { configureRecallFeatures, type RecallFeatureFlags } from "./config";
-export * from "./core/beam/index";
-export * from "./core/embeddings";
-export * from "./core/llm-backends";
-export * from "./core/memory";
-export { addMemory, flushExtractions, forget, get, getBank, getContext, getDefaultInstance, getStats, Mnemopi, query, recall, recallEnhanced, remember, resetDefaultInstanceForTests, resetMemoryForTests, resetModuleStateForTests, saveMemory, scratchpadClear, scratchpadRead, scratchpadWrite, search, setBank, sleep, sleepAllSessions, storeMemory, update, } from "./core/memory";
+export { configureRecallFeatures, type RecallFeatureFlags } from "./config.js";
+export * from "./core/beam/index.js";
+export * from "./core/embeddings.js";
+export * from "./core/llm-backends.js";
+export * from "./core/memory.js";
+export { addMemory, flushExtractions, forget, get, getBank, getContext, getDefaultInstance, getStats, Mnemopi, query, recall, recallEnhanced, remember, resetDefaultInstanceForTests, resetMemoryForTests, resetModuleStateForTests, saveMemory, scratchpadClear, scratchpadRead, scratchpadWrite, search, setBank, sleep, sleepAllSessions, storeMemory, update, } from "./core/memory.js";

package/dist/types/mcp-server.d.ts

@@ -1,4 +1,4 @@
-import { type ToolArguments, type ToolDefinition } from "./mcp-tools";
+import { type ToolArguments, type ToolDefinition } from "./mcp-tools.js";
 export interface JsonRpcRequest {
     readonly jsonrpc?: string;
     readonly id?: string | number | null;

package/dist/types/migrations/e6-triplestore-split.d.ts

@@ -1 +1 @@
-export * from "../core/migrations/e6-triplestore-split";
+export * from "../core/migrations/e6-triplestore-split.js";

package/dist/types/migrations/index.d.ts

@@ -1 +1 @@
-export * from "./e6-triplestore-split";
+export * from "./e6-triplestore-split.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-mnemopi",
-	"version": "16.3.6",
+	"version": "16.3.7",
 	"description": "Local SQLite memory engine for Oh My Pi agents",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -39,9 +39,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.3.6",
-		"@oh-my-pi/pi-catalog": "16.3.6",
-		"@oh-my-pi/pi-utils": "16.3.6",
+		"@oh-my-pi/pi-ai": "16.3.7",
+		"@oh-my-pi/pi-catalog": "16.3.7",
+		"@oh-my-pi/pi-utils": "16.3.7",
 		"lru-cache": "11.5.1"
 	},
 	"peerDependencies": {

package/src/core/beam/consolidate.ts

@@ -3,7 +3,7 @@ import { generateId, stableMemoryId } from "../../util/ids";
 import { aaakEncode } from "../aaak";
 import { REGEX_EXTRACTION_MAX_INPUT_CHARS } from "../entities";
 import { EpisodicGraph } from "../episodic-graph";
-import { heuristicExtractFacts } from "../extraction";
+import { type ExtractedFactCategories, heuristicExtractFacts } from "../extraction";
 import { clampVeracity } from "../veracity-consolidation";
 import { scheduleEmbedding } from "./helpers";
 import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types";
@@ -292,7 +292,7 @@ function insertFactRows(
 function insertTimeline(
 	beam: BeamMemoryState,
 	messageIdx: number,
-	date: string,
+	date: string | null,
 	description: string,
 	sourceMemoryId: string | null,
 ): void {
@@ -327,6 +327,38 @@ function insertKg(
 	});
 }
 
+function insertPreference(
+	beam: BeamMemoryState,
+	messageIdx: number,
+	preference: string,
+	topic: string | null,
+	sourceMemoryId: string | null,
+): void {
+	beam.db.run(
+		`INSERT INTO memoria_preferences (session_id, message_idx, preference, topic, evolution, context_snippet, source_memory_id)
+		 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		[sourceSession(beam), messageIdx, preference, topic, null, preference, sourceMemoryId],
+	);
+}
+
+function insertInstruction(
+	beam: BeamMemoryState,
+	messageIdx: number,
+	instruction: string,
+	context: string,
+	sourceMemoryId: string | null,
+): void {
+	beam.db.run(
+		`INSERT INTO memoria_instructions (session_id, message_idx, instruction, active, topic, context_snippet, source_memory_id)
+		 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		[sourceSession(beam), messageIdx, instruction, 1, null, context, sourceMemoryId],
+	);
+}
+
+function timelineDate(description: string): string | null {
+	return /\b\d{4}-\d{2}-\d{2}\b/.exec(description)?.[0] ?? null;
+}
+
 /**
  * Populate the episodic graph (gists, facts, edges) for a freshly consolidated
  * memory. The graph backs Polyphonic Recall's `graph` voice, which relies on
@@ -458,36 +490,68 @@ export function detectLanguage(_beam: BeamMemoryState, text: string): string {
 	}
 	return spanish >= 3 ? "es" : "en";
 }
+type StoreFactStringOptions = {
+	routeHeuristicCategories?: boolean;
+};
+
 export function storeFactStrings(
 	beam: BeamMemoryState,
 	facts: readonly string[],
 	messageIdx = 0,
 	sourceMemoryId: string | null = null,
 	importance = 0.7,
+	options: StoreFactStringOptions = {},
 ): number {
+	const routeHeuristicCategories = options.routeHeuristicCategories ?? true;
 	let stored = 0;
 	for (const fact of facts) {
 		insertFactRows(beam, messageIdx, "entity", "fact", fact, fact, importance, sourceMemoryId);
 		stored++;
+		if (!routeHeuristicCategories) continue;
 		const pref = /^The user (prefers|dislikes) (.+)$/i.exec(fact);
 		if (pref?.[2]) {
-			beam.db.run(
-				`INSERT INTO memoria_preferences (session_id, message_idx, preference, topic, evolution, context_snippet, source_memory_id)
-				 VALUES (?, ?, ?, ?, ?, ?, ?)`,
-				[sourceSession(beam), messageIdx, fact, pref[2], null, fact, sourceMemoryId],
-			);
+			insertPreference(beam, messageIdx, fact, pref[2], sourceMemoryId);
 		}
 		const instruction = /^Instruction: (.+)$/i.exec(fact);
 		if (instruction?.[1]) {
-			beam.db.run(
-				`INSERT INTO memoria_instructions (session_id, message_idx, instruction, active, topic, context_snippet, source_memory_id)
-				 VALUES (?, ?, ?, ?, ?, ?, ?)`,
-				[sourceSession(beam), messageIdx, instruction[1], 1, null, fact, sourceMemoryId],
-			);
+			insertInstruction(beam, messageIdx, instruction[1], fact, sourceMemoryId);
 		}
 	}
 	return stored;
 }
+
+/** Store category-preserving LLM extraction output in MEMORIA and KG tables. */
+export function storeExtractedFactCategories(
+	beam: BeamMemoryState,
+	extracted: ExtractedFactCategories,
+	messageIdx = 0,
+	sourceMemoryId: string | null = null,
+	importance = 0.7,
+): number {
+	let stored = storeFactStrings(beam, extracted.facts, messageIdx, sourceMemoryId, importance);
+	stored += storeFactStrings(beam, extracted.instructions, messageIdx, sourceMemoryId, importance, {
+		routeHeuristicCategories: false,
+	});
+	stored += storeFactStrings(beam, extracted.preferences, messageIdx, sourceMemoryId, importance, {
+		routeHeuristicCategories: false,
+	});
+	stored += storeFactStrings(beam, extracted.timelines, messageIdx, sourceMemoryId, importance, {
+		routeHeuristicCategories: false,
+	});
+	for (const instruction of extracted.instructions) {
+		insertInstruction(beam, messageIdx, instruction, instruction, sourceMemoryId);
+	}
+	for (const preference of extracted.preferences) {
+		insertPreference(beam, messageIdx, preference, null, sourceMemoryId);
+	}
+	for (const timeline of extracted.timelines) {
+		insertTimeline(beam, messageIdx, timelineDate(timeline), timeline, sourceMemoryId);
+	}
+	for (const triple of extracted.kg) {
+		insertKg(beam, messageIdx, triple.subject, triple.predicate, triple.object, sourceMemoryId);
+	}
+	return stored;
+}
 export function extractAndStoreFacts(
 	beam: BeamMemoryState,
 	content: string,

package/src/core/beam/recall.ts

@@ -69,6 +69,34 @@ const VERACITY_WEIGHTS: Record<string, number> = {
 	false: 0,
 };
 
+/**
+ * Default per-result content preview cap enforced by {@link recall}. Content
+ * longer than this is clipped and the last character replaced with `…` so
+ * callers see the truncation; the full row remains reachable via
+ * `Mnemopi.get()` (and, in the coding-agent, `memory://<id>`). Overridable per
+ * call via {@link RecallOptions.contentPreviewChars}.
+ */
+export const RECALL_CONTENT_PREVIEW_CHARS = 500;
+
+/**
+ * Clip `content` to at most `limit` characters, replacing the tail with `…`
+ * when truncated so agents can distinguish a preview from a full row. Returns
+ * the original string (and `truncated: false`) when the limit is 0/negative or
+ * the content already fits. The single `…` occupies one character of the cap,
+ * so a 500-char cap yields at most 499 real characters plus the marker.
+ */
+export function clipRecallContent(
+	content: string,
+	limit: number = RECALL_CONTENT_PREVIEW_CHARS,
+): { content: string; truncated: boolean; fullLength: number } {
+	const fullLength = content.length;
+	if (limit <= 0 || fullLength <= limit) {
+		return { content, truncated: false, fullLength };
+	}
+	const head = content.slice(0, Math.max(0, limit - 1));
+	return { content: `${head}…`, truncated: true, fullLength };
+}
+
 const DEFAULT_LIMIT = 500;
 const STOP_WORDS = new Set([
 	"a",
@@ -125,6 +153,7 @@ const FACT_QUERY_FILLER_WORDS = new Set([
 ]);
 
 const FACT_CLITIC_FRAGMENTS = new Set(["d", "ll", "m", "re", "s", "t", "ve"]);
+const FLAT_FACT_SEARCH_NOISE: Record<string, true> = { entity: true, fact: true };
 
 function nowIso(): string {
 	return new Date().toISOString();
@@ -736,10 +765,11 @@ function scoreCandidate(
 		score *= tierWeight;
 	}
 	score *= veracityWeight * currentContentAdjustment(searchableContent, options.currentSensitive === true);
+	const preview = clipRecallContent(content, options.contentPreviewChars ?? RECALL_CONTENT_PREVIEW_CHARS);
 	const result: RecallResult = {
 		...candidate.row,
 		id: asString(candidate.row.id),
-		content: content.slice(0, 500),
+		content: preview.content,
 		source: asNullableString(candidate.row.source),
 		timestamp: asNullableString(candidate.row.timestamp),
 		importance,
@@ -765,6 +795,8 @@ function scoreCandidate(
 			recency_decay: round4(decay),
 			temporal: round4(temporalScore),
 		},
+		truncated: preview.truncated,
+		full_length: preview.fullLength,
 	};
 	return result;
 }
@@ -1019,7 +1051,7 @@ export async function recallEnhanced(
 		updateRecallCounts: false,
 	});
 	if (options.includeFacts === true) {
-		const facts = factRecall(beam, query, Math.min(3, topK));
+		const facts = factRecall(beam, query, factRecallLimit(topK));
 		results.push(...facts);
 	}
 	results.sort((left, right) => (right.score ?? 0) - (left.score ?? 0));
@@ -1028,20 +1060,36 @@ export async function recallEnhanced(
 	return finalResults;
 }
 
+function factRecallLimit(topK: number): number {
+	const requested = Math.max(0, Math.floor(topK));
+	if (requested === 0) return 0;
+	return Math.min(requested, Math.max(3, Math.ceil(requested / 2)));
+}
+
 function sandwichOrder(results: readonly RecallResult[]): {
 	high: RecallResult[];
 	medium: RecallResult[];
 	closing: RecallResult[];
 } {
 	const scored = [...results].sort((left, right) => (right.score ?? 0) - (left.score ?? 0));
-	const high = scored.filter(r => (r.score ?? 0) > 0.7).slice(0, 3);
-	const medium = scored.filter(r => (r.score ?? 0) > 0.3 && (r.score ?? 0) <= 0.7).slice(0, 5);
-	const closing = scored.filter(r => !high.includes(r)).slice(0, 3);
-	return { high, medium, closing: closing.length > 0 ? closing : high.slice(0, 2) };
+	const highLimit = scored.length > 0 && scored.length < 4 ? 1 : 3;
+	const high = scored.slice(0, highLimit);
+	const medium = scored.slice(high.length, high.length + 5);
+	const closing = scored.slice(high.length + medium.length, high.length + medium.length + 3);
+	return { high, medium, closing };
+}
+function factSearchableText(subject: string, predicate: string, object: string): string {
+	const objectText = object.trim();
+	if (objectText.length === 0) return `${subject} ${predicate}`.trim();
+	const structuralParts = [subject, predicate].filter(part => {
+		const token = part.trim().toLowerCase();
+		return token.length > 0 && FLAT_FACT_SEARCH_NOISE[token] !== true;
+	});
+	return [...structuralParts, objectText].join(" ").trim();
 }
 
 function factLine(result: RecallResult): string {
-	const content = result.content.slice(0, 200).trim();
+	const content = clipRecallContent(result.content.trim(), 200).content;
 	const ts = typeof result.timestamp === "string" && result.timestamp.length > 0 ? result.timestamp.slice(0, 10) : "?";
 	const source = result.source ?? "unknown";
 	const score = result.score ?? result.importance ?? 0;
@@ -1140,7 +1188,7 @@ export function factRecall(beam: BeamMemoryState, query: string, topK = 30): Fac
 			const object = asString(row.object);
 			const confidence = asNumber(row.confidence, 0.5);
 			const content = object.length > 0 ? object : `${subject} ${predicate}`.trim();
-			const searchable = `${subject} ${predicate} ${object}`.trim();
+			const searchable = factSearchableText(subject, predicate, object);
 			const queryGroups = factExpandedTokenGroups(query, searchable);
 			const queryTokens = tokensFromGroups(queryGroups);
 			const lexical =
@@ -1171,6 +1219,7 @@ export function factRecall(beam: BeamMemoryState, query: string, topK = 30): Fac
 			};
 			return result;
 		})
+		.filter(result => (result.score ?? 0) > 0)
 		.sort((left, right) => (right.score ?? 0) - (left.score ?? 0))
 		.slice(0, topK);
 }

package/src/core/beam/store.ts

@@ -5,9 +5,9 @@ import { toUtcIso } from "../../util/datetime";
 import { generateId } from "../../util/ids";
 import { currentEmbeddingModel, embeddingsDisabled } from "../embeddings";
 import { EpisodicGraph } from "../episodic-graph";
-import { extractFactsSafe } from "../extraction";
+import { countExtractedFactCategories, extractFactCategoriesSafe } from "../extraction";
 import { getMnemopiRuntimeOptions, withMnemopiRuntimeOptions } from "../runtime-options";
-import { storeFactStrings } from "./consolidate";
+import { storeExtractedFactCategories } from "./consolidate";
 import { type EmbedItem, scheduleEmbedding, vecAvailable, vecInsert } from "./helpers";
 import type {
 	BeamEvent,
@@ -232,9 +232,9 @@ function proactiveLinkIfEnabled(
  */
 async function runFactExtraction(beam: BeamMemoryState, memoryId: string, content: string): Promise<void> {
 	try {
-		const facts = await extractFactsSafe(content);
-		if (facts.length === 0) return;
-		storeFactStrings(beam, facts, 0, memoryId);
+		const extracted = await extractFactCategoriesSafe(content);
+		if (countExtractedFactCategories(extracted) === 0) return;
+		storeExtractedFactCategories(beam, extracted, 0, memoryId);
 		invalidateCaches(beam);
 	} catch {
 		// Background fact extraction is best-effort and never surfaces to the caller.

package/src/core/beam/types.ts

@@ -172,6 +172,15 @@ export interface RecallOptions {
 	useIntent?: boolean;
 	useMmr?: boolean;
 	mmrLambda?: number;
+	/**
+	 * Maximum characters of `content` returned per {@link RecallResult}. When the
+	 * stored content exceeds this, the preview is clipped and the trailing
+	 * character is replaced with `…` so callers can see it was truncated. The
+	 * full row is always reachable via {@link BeamMemoryState.get}. `0` or a
+	 * negative value disables clipping. Defaults to
+	 * {@link RECALL_CONTENT_PREVIEW_CHARS} (500).
+	 */
+	contentPreviewChars?: number;
 }
 
 export interface RecallEnhancedOptions extends RecallOptions {
@@ -238,6 +247,15 @@ export type RecallResult = RecallRowFields & {
 	[key: string]: unknown;
 	id: string;
 	content: string;
+	/**
+	 * True when {@link content} is a clipped preview of the stored row. The
+	 * clip is capped at {@link RecallOptions.contentPreviewChars} (default 500)
+	 * and the last character is replaced with `…`. Fetch the full row via
+	 * `memory://<id>` (mnemopi backend) or the `Mnemopi.get(id)` API.
+	 */
+	truncated?: boolean;
+	/** Original character count of `content` before {@link truncated} clipping. */
+	full_length?: number;
 	score?: number;
 	distance?: number;
 	rank?: number;

package/src/core/extraction.ts

@@ -82,48 +82,146 @@ function stripFence(raw: string): string {
 	return s.trim();
 }
 
+const FLAT_FACT_LIMIT = 5;
+const STRUCTURED_CATEGORY_LIMIT = 5;
+const STRING_CATEGORY_KEYS = ["facts", "instructions", "preferences", "timelines"] as const;
+
+/** Parsed knowledge-graph edge emitted by the extractor LLM. */
+export interface ExtractedKgTriple {
+	subject: string;
+	predicate: string;
+	object: string;
+}
+
+/** Category-preserving extraction result used by background memory routing. */
+export interface ExtractedFactCategories {
+	facts: string[];
+	instructions: string[];
+	preferences: string[];
+	timelines: string[];
+	kg: ExtractedKgTriple[];
+}
+
+function emptyFactCategories(): ExtractedFactCategories {
+	return { facts: [], instructions: [], preferences: [], timelines: [], kg: [] };
+}
+
 function normalizeFact(fact: string): string {
 	const trimmed = fact.trim();
 	// Remove trailing sentence punctuation (. ! ?) if present
 	return trimmed.replace(/[.!?]+$/, "");
 }
-export function parseFacts(rawOutput: string | null | undefined): string[] {
-	if (rawOutput === null || rawOutput === undefined) {
+
+function normalizeFactArray(items: unknown): string[] {
+	if (!Array.isArray(items)) {
+		return [];
+	}
+	const out: string[] = [];
+	for (const item of items) {
+		if (item !== null && item !== undefined && String(item).trim() !== "") {
+			const normalized = normalizeFact(String(item));
+			if (normalized !== "") {
+				out.push(normalized);
+				if (out.length >= STRUCTURED_CATEGORY_LIMIT) break;
+			}
+		}
+	}
+	return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function triplePart(value: unknown): string {
+	return typeof value === "string" ? normalizeFact(value) : "";
+}
+
+function normalizeKgTriple(item: unknown): ExtractedKgTriple | null {
+	let subject = "";
+	let predicate = "";
+	let object = "";
+	if (isRecord(item)) {
+		subject = triplePart(item.subject);
+		predicate = triplePart(item.predicate);
+		object = triplePart(item.object);
+	} else if (Array.isArray(item)) {
+		subject = triplePart(item[0]);
+		predicate = triplePart(item[1]);
+		object = triplePart(item[2]);
+	}
+	return subject !== "" && predicate !== "" && object !== "" ? { subject, predicate, object } : null;
+}
+
+function normalizeKgArray(items: unknown): ExtractedKgTriple[] {
+	if (!Array.isArray(items)) {
 		return [];
 	}
+	const out: ExtractedKgTriple[] = [];
+	for (const item of items) {
+		const triple = normalizeKgTriple(item);
+		if (triple !== null) {
+			out.push(triple);
+			if (out.length >= STRUCTURED_CATEGORY_LIMIT) break;
+		}
+	}
+	return out;
+}
+
+/** Flatten extracted string categories for legacy fact callers. */
+export function flattenExtractedFactCategories(extracted: ExtractedFactCategories): string[] {
+	const out: string[] = [];
+	for (const category of STRING_CATEGORY_KEYS) {
+		for (const item of extracted[category]) {
+			out.push(item);
+		}
+	}
+	return out;
+}
+
+/** Count string facts plus KG triples in a category-preserving extraction result. */
+export function countExtractedFactCategories(extracted: ExtractedFactCategories): number {
+	return (
+		extracted.facts.length +
+		extracted.instructions.length +
+		extracted.preferences.length +
+		extracted.timelines.length +
+		extracted.kg.length
+	);
+}
+
+/** Parse extractor output without discarding MEMORIA categories or KG triples. */
+export function parseExtractedFactCategories(rawOutput: string | null | undefined): ExtractedFactCategories {
+	if (rawOutput === null || rawOutput === undefined) {
+		return emptyFactCategories();
+	}
 	const raw = rawOutput.trim();
 	if (raw === "" || raw.toUpperCase() === "NO_FACTS") {
-		return [];
+		return emptyFactCategories();
 	}
 	const rawClean = stripFence(raw);
 	if (rawClean.startsWith("{")) {
 		try {
-			const parsed = JSON.parse(rawClean) as unknown;
-			if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-				const obj = parsed as Record<string, unknown>;
-				const out: string[] = [];
-				for (const category of ["facts", "instructions", "preferences", "timelines"] as const) {
-					const items = obj[category];
-					if (Array.isArray(items)) {
-						for (const item of items) {
-							if (item !== null && item !== undefined && String(item).trim() !== "") {
-								const normalized = normalizeFact(String(item));
-								if (normalized !== "") {
-									out.push(normalized);
-								}
-							}
-						}
-					}
-				}
-				return out.slice(0, 5);
+			const parsed: unknown = JSON.parse(rawClean);
+			if (isRecord(parsed)) {
+				return {
+					facts: normalizeFactArray(parsed.facts),
+					instructions: normalizeFactArray(parsed.instructions),
+					preferences: normalizeFactArray(parsed.preferences),
+					timelines: normalizeFactArray(parsed.timelines),
+					kg: normalizeKgArray(parsed.kg),
+				};
 			}
 		} catch {
 			const matches = [...raw.matchAll(/"([^"]{10,})"/g)].map(m => m[1]).filter((v): v is string => v !== undefined);
 			if (matches.length > 0) {
-				return matches
-					.map(normalizeFact)
-					.filter(f => f !== "")
-					.slice(0, 5);
+				return {
+					...emptyFactCategories(),
+					facts: matches
+						.map(normalizeFact)
+						.filter(f => f !== "")
+						.slice(0, FLAT_FACT_LIMIT),
+				};
 			}
 		}
 	}
@@ -136,8 +234,14 @@ export function parseFacts(rawOutput: string | null | undefined): string[] {
 				cleaned.push(normalized);
 			}
 		}
+		if (cleaned.length >= FLAT_FACT_LIMIT) break;
 	}
-	return cleaned.slice(0, 5);
+	return { ...emptyFactCategories(), facts: cleaned };
+}
+
+/** Parse extractor output into the legacy flat string fact list. */
+export function parseFacts(rawOutput: string | null | undefined): string[] {
+	return flattenExtractedFactCategories(parseExtractedFactCategories(rawOutput)).slice(0, FLAT_FACT_LIMIT);
 }
 function sentenceCase(value: string): string {
 	const trimmed = value.trim().replace(/[.!?]+$/, "");
@@ -205,39 +309,48 @@ async function tryHostExtraction(prompt: string): Promise<[boolean, string | nul
 	return [true, text === "" ? null : text];
 }
 
-async function localFallback(prompt: string, sourceText: string, diag = getDiagnostics()): Promise<string[]> {
+async function localFallback(
+	prompt: string,
+	sourceText: string,
+	diag = getDiagnostics(),
+): Promise<ExtractedFactCategories> {
 	diag.recordAttempt("local");
 	try {
 		const raw = await callLocalLlm(prompt);
 		if (raw !== null) {
-			const facts = parseFacts(cleanOutput(raw));
-			if (facts.length > 0) {
-				diag.recordSuccess("local", facts.length);
+			const extracted = parseExtractedFactCategories(cleanOutput(raw));
+			const count = countExtractedFactCategories(extracted);
+			if (count > 0) {
+				diag.recordSuccess("local", count);
 				diag.recordCall({ succeeded: true });
-				return facts;
+				return extracted;
 			}
 			diag.recordNoOutput("local");
 		}
 	} catch (exc) {
 		diag.recordFailure("local", exc, "local_llm_raised");
 		diag.recordCall({ succeeded: false });
-		return [];
+		return emptyFactCategories();
 	}
 	diag.recordFailure("local", undefined, "model_not_loaded");
 	const heuristic = heuristicExtractFacts(sourceText);
 	if (heuristic.length > 0) {
 		diag.recordSuccess("local", heuristic.length);
 		diag.recordCall({ succeeded: true });
-		return heuristic;
+		return { ...emptyFactCategories(), facts: heuristic };
 	}
 	diag.recordCall({ succeeded: false, allEmpty: true });
-	return [];
+	return emptyFactCategories();
 }
 
-export async function extractFacts(text: string | null | undefined, options: RemoteLlmOptions = {}): Promise<string[]> {
+/** Extract fact categories from text using configured, host, local, or remote LLMs. */
+export async function extractFactCategories(
+	text: string | null | undefined,
+	options: RemoteLlmOptions = {},
+): Promise<ExtractedFactCategories> {
 	const diag = getDiagnostics();
 	if (typeof text !== "string" || text.trim() === "") {
-		return [];
+		return emptyFactCategories();
 	}
 	const prompt = buildExtractionPrompt(text);
 
@@ -250,11 +363,12 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 		try {
 			const raw = await callConfiguredCompletion(prompt, 0, { maxTokens: llmMaxTokens() });
 			if (typeof raw === "string" && raw.trim() !== "") {
-				const facts = parseFacts(raw);
-				if (facts.length > 0) {
-					diag.recordSuccess("host", facts.length);
+				const extracted = parseExtractedFactCategories(raw);
+				const count = countExtractedFactCategories(extracted);
+				if (count > 0) {
+					diag.recordSuccess("host", count);
 					diag.recordCall({ succeeded: true });
-					return facts;
+					return extracted;
 				}
 			}
 			diag.recordNoOutput("host");
@@ -262,7 +376,7 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 			diag.recordFailure("host", exc, "configured_completion_raised");
 			diag.recordCall({ succeeded: false });
 			console.warn(`extractFacts: configured completion raised: ${safeForLog(exc)}`);
-			return [];
+			return emptyFactCategories();
 		}
 		return localFallback(prompt, text, diag);
 	}
@@ -272,11 +386,12 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 		if (attempted) {
 			diag.recordAttempt("host");
 			if (hostText !== null) {
-				const facts = parseFacts(hostText);
-				if (facts.length > 0) {
-					diag.recordSuccess("host", facts.length);
+				const extracted = parseExtractedFactCategories(hostText);
+				const count = countExtractedFactCategories(extracted);
+				if (count > 0) {
+					diag.recordSuccess("host", count);
 					diag.recordCall({ succeeded: true });
-					return facts;
+					return extracted;
 				}
 			}
 			diag.recordNoOutput("host");
@@ -287,7 +402,7 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 		diag.recordFailure("host", exc, "host_adapter_raised");
 		diag.recordCall({ succeeded: false });
 		console.warn(`extractFacts: host LLM adapter raised: ${safeForLog(exc)}`);
-		return [];
+		return emptyFactCategories();
 	}
 
 	if (!llmAvailable()) {
@@ -296,22 +411,23 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 		if (heuristic.length > 0) {
 			diag.recordSuccess("local", heuristic.length);
 			diag.recordCall({ succeeded: true });
-			return heuristic;
+			return { ...emptyFactCategories(), facts: heuristic };
 		}
 		diag.recordFailure("local", undefined, "llm_unavailable_at_call_site");
 		diag.recordCall({ succeeded: false });
-		return [];
+		return emptyFactCategories();
 	}
 
 	diag.recordAttempt("remote");
 	try {
 		const raw = await callRemoteLlm(prompt, 0, options);
 		if (raw !== null) {
-			const facts = parseFacts(cleanOutput(raw));
-			if (facts.length > 0) {
-				diag.recordSuccess("remote", facts.length);
+			const extracted = parseExtractedFactCategories(cleanOutput(raw));
+			const count = countExtractedFactCategories(extracted);
+			if (count > 0) {
+				diag.recordSuccess("remote", count);
 				diag.recordCall({ succeeded: true });
-				return facts;
+				return extracted;
 			}
 		}
 		diag.recordNoOutput("remote");
@@ -323,14 +439,27 @@ export async function extractFacts(text: string | null | undefined, options: Rem
 	return localFallback(prompt, text, diag);
 }
 
-export async function extractFactsSafe(text: string | null | undefined): Promise<string[]> {
+/** Extract legacy flat fact strings from text. */
+export async function extractFacts(text: string | null | undefined, options: RemoteLlmOptions = {}): Promise<string[]> {
+	const extracted = await extractFactCategories(text, options);
+	return flattenExtractedFactCategories(extracted).slice(0, FLAT_FACT_LIMIT);
+}
+
+/** Safely extract category-preserving facts, swallowing best-effort failures. */
+export async function extractFactCategoriesSafe(text: string | null | undefined): Promise<ExtractedFactCategories> {
 	try {
-		return await extractFacts(text);
+		return await extractFactCategories(text);
 	} catch (exc) {
 		const diag = getDiagnostics();
 		diag.recordFailure("wrapper", exc, "outer_wrapper_caught");
 		diag.recordCall({ succeeded: false });
 		console.warn(`extractFactsSafe: extractFacts() raised: ${safeForLog(exc)}`);
-		return [];
+		return emptyFactCategories();
 	}
 }
+
+/** Safely extract legacy flat fact strings, swallowing best-effort failures. */
+export async function extractFactsSafe(text: string | null | undefined): Promise<string[]> {
+	const extracted = await extractFactCategoriesSafe(text);
+	return flattenExtractedFactCategories(extracted).slice(0, FLAT_FACT_LIMIT);
+}

package/src/core/memory.ts

@@ -319,6 +319,7 @@ function toRecallOptions(options: RecallFacadeOptions): BeamRecallFacadeOptions
 		vecWeight: options.vecWeight ?? options.vec_weight ?? undefined,
 		ftsWeight: options.ftsWeight ?? options.fts_weight ?? undefined,
 		importanceWeight: options.importanceWeight ?? options.importance_weight ?? undefined,
+		contentPreviewChars: options.contentPreviewChars,
 	};
 	// Preserve the three-state semantics (`undefined` = auto-derive, `null` = explicitly
 	// FTS-only, `number[]` = caller-supplied) so callers can opt out of `recall()`'s