@linxiraos/pi-mnemopi 1.1.23 → 1.1.25

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## [Unreleased]
 
-## [1.1.23] - 2026-10-01
+## [1.1.25] - 2026-10-03
+
+- 版本线推进至 1.1.25；本版无独立用户可见变化。
+
+## [1.1.24] - 2026-10-03
+
+- 上游 v18.4.11 集成；本轮无用户可见变更。
 
 ## [1.1.22] - 2026-09-30
 

package/THIRD-PARTY-NOTICES.txt

@@ -1,7 +1,7 @@
-OMP THIRD-PARTY NOTICES
+ZETA THIRD-PARTY NOTICES
 =======================
 
-This generated, self-contained aggregate accompanies OMP release artifacts.
+This generated, self-contained aggregate accompanies Zeta release artifacts.
 It does not replace package-level license files. First-party licensing grants
 no rights in third-party code, fonts, data, or marks identified below.
 
@@ -1046,7 +1046,7 @@ These packages participate only in generation/web build tooling and are not ship
 
 SCOPED NON-PERMISSIVE PACKAGES
 ------------------------------
-The exact @img/sharp-libvips-* 1.2.4 all-target family is LGPL-3.0-or-later. It is not distributed in OMP npm bundles or standalone assets: @huggingface/transformers is always external, installed into a user-side versioned runtime on demand, and sharp is stubbed for speech/text. The dynamically loaded native library remains replaceable. Corresponding source is available from https://github.com/lovell/sharp-libvips.git and upstream libvips sources.
+The exact @img/sharp-libvips-* 1.2.4 all-target family is LGPL-3.0-or-later. It is not distributed in Zeta npm bundles or standalone assets: @huggingface/transformers is always external, installed into a user-side versioned runtime on demand, and sharp is stubbed for speech/text. The dynamically loaded native library remains replaceable. Corresponding source is available from https://github.com/lovell/sharp-libvips.git and upstream libvips sources.
 
 lightningcss 1.32.0 and its exact target leaves are MPL-2.0 build-only dependencies. MPL is not globally allowed and these packages are absent from runtime artifacts.
 

package/dist/types/config.d.ts

@@ -80,16 +80,25 @@ export interface RecallFeatureFlags {
     proactiveLinking?: boolean;
 }
 /**
- * Sets process-wide defaults for the env-gated recall features. Host configuration
- * (e.g. the coding-agent `mnemopi.polyphonicRecall` / `mnemopi.enhancedRecall` /
- * `mnemopi.proactiveLinking` settings) lands here; the `MNEMOPI_POLYPHONIC_RECALL` /
- * `MNEMOPI_ENHANCED_RECALL` / `MNEMOPI_PROACTIVE_LINKING` environment variables still
- * win whenever they are set.
+ * Sets process-wide defaults for the env-gated recall features. Hosts that open
+ * several memories with different policies should pass the per-instance
+ * `polyphonicRecall` / `enhancedRecall` / `proactiveLinking` options instead
+ * (`Mnemopi` / `BeamMemory` constructors), which take precedence over these
+ * defaults. The `MNEMOPI_POLYPHONIC_RECALL` / `MNEMOPI_ENHANCED_RECALL` /
+ * `MNEMOPI_PROACTIVE_LINKING` environment variables still win whenever they are set.
  */
 export declare function configureRecallFeatures(flags: RecallFeatureFlags): void;
-export declare function polyphonicRecallEnabled(env?: Env): boolean;
+/**
+ * Resolves the polyphonic recall gate: the env var wins when set, then the
+ * per-instance `configured` value, then the process-wide default.
+ */
+export declare function polyphonicRecallEnabled(env?: Env, configured?: boolean): boolean;
 export declare function temporalHalflifeHours(env?: Env): number;
-export declare function enhancedRecallEnabled(env?: Env): boolean;
+/**
+ * Resolves the enhanced recall (query result cache) gate: the env var wins when
+ * set, then the per-instance `configured` value, then the process-wide default.
+ */
+export declare function enhancedRecallEnabled(env?: Env, configured?: boolean): boolean;
 export declare function proactiveLinkingEnabled(env?: Env): boolean;
 export declare function llmEnabled(env?: Env): boolean;
 export declare function llmMaxTokens(env?: Env): number;

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

@@ -1,4 +1,5 @@
 import { type ExtractedFactCategories } from "../extraction.js";
+import { VeracityConsolidator } from "../veracity-consolidation.js";
 import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types.js";
 type Row = Record<string, unknown>;
 type FactCounts = {
@@ -17,6 +18,18 @@ type ConsolidateOptions = {
     scope?: string;
     veracity?: string | null;
 };
+/**
+ * This beam's veracity consolidator, created on first use so `consolidated_facts` /
+ * `conflicts` DDL only runs once polyphonic recall needs them.
+ */
+export declare function ensureVeracityConsolidator(beam: BeamMemoryState): VeracityConsolidator;
+/**
+ * Consolidate every extracted KG fact (`memoria_kg`) whose source memory is not yet
+ * among that fact's `consolidated_facts` sources, e.g. facts written while polyphonic
+ * recall was off. Idempotent: a (fact, source) pair is only ever counted once.
+ * Facts without a source memory are skipped; the fact voice could not return them.
+ */
+export declare function backfillConsolidatedFacts(beam: BeamMemoryState, consolidator: VeracityConsolidator): number;
 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;
 type StoreFactStringOptions = {

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

@@ -1,4 +1,5 @@
 import type { Database } from "bun:sqlite";
+import type { VeracityConsolidator } from "../veracity-consolidation.js";
 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";
@@ -16,7 +17,8 @@ export declare class BeamMemory implements BeamMemoryState {
     readonly annotations: BeamMemoryState["annotations"];
     readonly triples: BeamMemoryState["triples"];
     readonly episodicGraph: unknown | null;
-    readonly veracityConsolidator: unknown | null;
+    /** Created on first polyphonic use (see `ensureVeracityConsolidator`); `null` until then. */
+    veracityConsolidator: VeracityConsolidator | null;
     readonly caches: BeamCaches;
     readonly config: BeamConfig;
     readonly pendingExtractions: Set<Promise<void>>;

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

@@ -46,6 +46,18 @@ export declare function clipRecallContent(content: string, limit?: 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[]>;
+/**
+ * Enhanced recall: linear hybrid recall with synonyms, intent weighting and MMR,
+ * optionally merged with extracted facts.
+ *
+ * Two opt-in layers sit on top, each gated per instance (`BeamConfig`) with the
+ * `MNEMOPI_POLYPHONIC_RECALL` / `MNEMOPI_ENHANCED_RECALL` env vars winning:
+ * - polyphonic recall fuses this ranking with the vector, graph, fact and temporal
+ *   voices (see {@link orchestrateRecall});
+ * - the enhanced recall cache serves repeated or similar queries whose options all
+ *   match, and is dropped by any database write.
+ * With both off the linear path runs unchanged.
+ */
 export declare function recallEnhanced(beam: BeamMemoryState, query: string, topK?: number, options?: RecallEnhancedOptions & RecallOptionsInternal): Promise<RecallResult[]>;
 export declare function formatContext(beam: BeamMemoryState, results: readonly RecallResult[], format?: string): string;
 export declare function factRecall(beam: BeamMemoryState, query: string, topK?: number): FactRecallResult[];

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

@@ -1,4 +1,5 @@
 import type { Database } from "bun:sqlite";
+import type { QueryCache } from "../query-cache.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
@@ -27,6 +28,13 @@ export interface BeamCaches {
     polyphonicEngine?: unknown;
     extractionClient?: unknown;
     extractionBuffer: unknown[];
+    /** Enhanced-recall result cache; installed lazily while `enhancedRecall` is enabled. */
+    queryCache?: QueryCache<RecallResult>;
+    /**
+     * SQLite write token (`data_version` + `total_changes()`) the cached entries were
+     * computed against; any other write to the database drops the cache.
+     */
+    queryCacheToken?: string;
     [key: string]: unknown;
 }
 export interface BeamConfig {
@@ -40,6 +48,10 @@ export interface BeamConfig {
     localLlmEnabled: boolean;
     maxEpisodeChars: number;
     proactiveLinking?: boolean;
+    /** Per-instance polyphonic recall gate; `undefined` defers to the process-wide default. */
+    polyphonicRecall?: boolean;
+    /** Per-instance enhanced recall (query cache) gate; `undefined` defers to the process-wide default. */
+    enhancedRecall?: boolean;
 }
 export interface BeamMemoryOptions {
     sessionId?: string;
@@ -49,6 +61,10 @@ export interface BeamMemoryOptions {
     channelId?: string | null;
     useCloud?: boolean;
     proactiveLinking?: boolean;
+    /** Route `recallEnhanced` through polyphonic recall. `MNEMOPI_POLYPHONIC_RECALL` wins when set. */
+    polyphonicRecall?: boolean;
+    /** Cache `recallEnhanced` results per query and options. `MNEMOPI_ENHANCED_RECALL` wins when set. */
+    enhancedRecall?: boolean;
     eventEmitter?: (event: BeamEvent) => void;
     pluginManager?: BeamPluginManager | null;
     annotations?: AnnotationStoreLike | null;
@@ -159,6 +175,7 @@ export interface RecallOptions {
     contentPreviewChars?: number;
 }
 export interface RecallEnhancedOptions extends RecallOptions {
+    /** Set `false` to bypass the enhanced-recall result cache for this call. */
     useCache?: boolean;
     includeFacts?: boolean;
 }

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

@@ -17,6 +17,8 @@ export interface Fact {
     readonly timestamp: string;
     readonly confidence: number;
     readonly temporalQualifier?: string | null;
+    /** Memory the fact was extracted from (`facts.source_msg_id`), when stored. */
+    readonly memoryId?: string | null;
 }
 export interface GraphEdge {
     readonly source: string;
@@ -68,6 +70,12 @@ export declare class EpisodicGraph {
     addEdge(edge: GraphEdge): void;
     getEdges(source?: string | null): GraphEdge[];
     findRelatedMemories(memoryId: string, depth?: number, edgeType?: string, minWeight?: number): RelatedMemory[];
+    /**
+     * Edges touching any of `nodeIds` in one query, strongest first, at most `limit` rows.
+     * Batched frontier expansion for bounded traversals; see {@link findRelatedMemories}
+     * for the per-node walk.
+     */
+    findEdgesTouching(nodeIds: readonly string[], edgeType: string, minWeight: number, limit: number): GraphEdge[];
     findFactsBySubject(subject: string): Fact[];
     findGistsByParticipant(participant: string): Gist[];
     scoreMemoryLink(sourceMemoryId: string, targetMemoryId: string): number;

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

@@ -28,6 +28,16 @@ export interface MnemopiOptions {
     readonly llmModel?: string | Model<Api>;
     readonly llm?: false | MnemopiLlmRuntimeOptions | Model<Api> | MnemopiLlmCompletion;
     readonly proactiveLinking?: boolean;
+    /**
+     * Route `recallEnhanced` through polyphonic recall for this instance. Unset
+     * defers to `configureRecallFeatures`; `MNEMOPI_POLYPHONIC_RECALL` wins when set.
+     */
+    readonly polyphonicRecall?: boolean;
+    /**
+     * Cache `recallEnhanced` results for this instance. Unset defers to
+     * `configureRecallFeatures`; `MNEMOPI_ENHANCED_RECALL` wins when set.
+     */
+    readonly enhancedRecall?: boolean;
     /** Escalate best-effort failure logs (embedding pipeline) from debug to warn. */
     readonly debug?: boolean;
     /**

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

@@ -4,17 +4,20 @@ export interface OrchestratorBeam extends BeamMemoryState {
     recall?: (query: string, topK?: number, options?: RecallOptions) => Promise<RecallResult[]>;
     recallEnhanced?: (query: string, topK?: number, options?: RecallOptions) => Promise<RecallResult[]>;
 }
-export interface OrchestrateRecallOptions extends Omit<RecallOptions, "queryEmbedding">, Omit<PolyphonicRecallOptions, "queryEmbedding"> {
+export interface OrchestrateRecallOptions extends Omit<RecallOptions, "queryEmbedding">, Omit<PolyphonicRecallOptions, "queryEmbedding" | "channelId" | "queryTime"> {
     readonly queryEmbedding?: readonly number[] | Float32Array | null;
     readonly enhanced?: boolean;
     readonly forcePolyphonic?: boolean;
     readonly forceLinear?: boolean;
 }
-export interface OrchestratedRecallResult extends Omit<RecallResult, "metadata" | "score" | "tier"> {
-    score?: number;
-    metadata?: RecallResult["metadata"];
-    tier?: RecallResult["tier"] | PolyphonicMemoryResult["tier"];
+/** Linear recall rows, or polyphonic rows that also carry `combined_score`. */
+export interface OrchestratedRecallResult extends RecallResult {
     combined_score?: PolyphonicMemoryResult["combined_score"];
-    voice_scores?: PolyphonicMemoryResult["voice_scores"];
 }
+/**
+ * Pick the recall path for one query. Polyphonic recall runs when forced or when
+ * the gate is on for this beam (`MNEMOPI_POLYPHONIC_RECALL`, then the beam's
+ * `polyphonicRecall` config, then the process-wide default); otherwise the beam's
+ * linear `recall` / `recallEnhanced` surface answers.
+ */
 export declare function orchestrateRecall(beam: OrchestratorBeam, query: string, topK?: number, options?: OrchestrateRecallOptions): Promise<OrchestratedRecallResult[]>;

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

@@ -1,10 +1,10 @@
 import type { Database } from "bun:sqlite";
 import { type Env } from "../config.js";
 import { type DatabasePath } from "../db.js";
-import type { BeamMemoryState, JsonValue, Metadata, RecallResult } from "./beam/types.js";
+import type { BeamMemoryState, JsonValue, Metadata, RecallResult, RecallTierLabel } from "./beam/types.js";
 import { EpisodicGraph } from "./episodic-graph.js";
 import { VeracityConsolidator } from "./veracity-consolidation.js";
-export type PolyphonicVoice = "vector" | "graph" | "fact" | "temporal";
+export type PolyphonicVoice = "hybrid" | "vector" | "graph" | "fact" | "temporal";
 export interface VoiceRecallResult {
     readonly memoryId: string;
     readonly score: number;
@@ -17,15 +17,37 @@ export interface PolyphonicResult {
     readonly voiceScores: Partial<Record<PolyphonicVoice, number>>;
     readonly metadata: Metadata;
 }
-export interface PolyphonicMemoryResult extends Omit<RecallResult, "metadata" | "score" | "tier"> {
+/** A hydrated recall row with its fused score and per-voice RRF contributions. */
+export interface PolyphonicMemoryResult extends RecallResult {
     score: number;
     combined_score: number;
     voice_scores: Partial<Record<PolyphonicVoice, number>>;
     metadata: Metadata;
-    tier: "working" | "episodic";
+    tier: RecallTierLabel;
 }
-export interface PolyphonicRecallOptions {
+/** Per-call options that shape which memories the voices may surface. */
+export interface PolyphonicCallOptions {
+    /**
+     * Extra visibility channel, mirroring linear recall: rows are visible when they
+     * belong to the engine session, are `global`, or carry this `channel_id`.
+     */
+    readonly channelId?: string | null;
+    /** Anchor for the temporal voice ("recent" is measured back from this instant). */
+    readonly queryTime?: string | Date | null;
+    /** Keep non-memory rows (extracted facts) contributed by the `hybrid` voice. */
+    readonly includeFacts?: boolean;
+    /**
+     * Ranked results of the standard (linear) recall for the same query. They form
+     * the `hybrid` voice and are reused verbatim when a fused hit is one of them.
+     */
+    readonly baseline?: readonly RecallResult[];
+}
+export interface PolyphonicRecallOptions extends PolyphonicCallOptions {
     readonly queryEmbedding?: readonly number[] | Float32Array | null;
+    /**
+     * Approximate token budget for the returned rows (default 4000); rows past it are
+     * dropped even below `topK`. `Infinity` disables the budget.
+     */
     readonly contextBudget?: number;
 }
 interface PolyphonicEngineOptions {
@@ -36,8 +58,31 @@ interface PolyphonicEngineOptions {
     readonly sessionId?: string | null;
     readonly channelId?: string | null;
 }
-export declare function polyphonicRecallIsEnabled(env?: Env): boolean;
+/** Reciprocal rank fusion constant: a voice's rank-`r` hit contributes `1 / (RRF_K + r)`. */
+export declare const POLYPHONIC_RRF_K = 60;
+export declare const POLYPHONIC_VOICES: readonly PolyphonicVoice[];
+/** Highest possible fused score: rank 1 in every voice. */
+export declare const POLYPHONIC_MAX_COMBINED_SCORE: number;
+/**
+ * Graph voice bounds. Proactive linking makes banks dense (every memory sharing an
+ * entity links to every other), so an unbounded walk grows with the cube of the bank.
+ * The voice reports at most `MAX_DIRECT` entity matches, expands the `MAX_SEEDS`
+ * strongest of them and at most `MAX_FRONTIER` nodes per later hop, reads at most
+ * `MAX_EDGE_ROWS` edges per hop, and reports at most `MAX_RESULTS` memories in total.
+ */
+export declare const GRAPH_VOICE_MAX_DEPTH = 2;
+export declare const GRAPH_VOICE_MAX_DIRECT = 32;
+export declare const GRAPH_VOICE_MAX_SEEDS = 16;
+export declare const GRAPH_VOICE_MAX_FRONTIER = 32;
+export declare const GRAPH_VOICE_MAX_EDGE_ROWS = 512;
+export declare const GRAPH_VOICE_MAX_RESULTS = 64;
+/**
+ * Polyphonic recall gate: `MNEMOPI_POLYPHONIC_RECALL` wins when set, then the
+ * per-instance `configured` flag, then the process-wide default.
+ */
+export declare function polyphonicRecallIsEnabled(env?: Env, configured?: boolean): boolean;
 export declare class PolyphonicRecallEngine {
+    #private;
     readonly dbPath: DatabasePath;
     readonly db: Database;
     readonly ownsConnection: boolean;
@@ -47,20 +92,43 @@ export declare class PolyphonicRecallEngine {
     readonly channelId: string | null;
     readonly voiceWeights: Readonly<Record<PolyphonicVoice, number>>;
     constructor(options?: PolyphonicEngineOptions);
-    recall(query: string, queryEmbedding?: readonly number[] | Float32Array | null, topK?: number, contextBudget?: number): PolyphonicMemoryResult[];
-    vectorVoice(queryEmbedding: readonly number[] | Float32Array | null): VoiceRecallResult[];
+    recall(query: string, queryEmbedding?: readonly number[] | Float32Array | null, topK?: number, contextBudget?: number, options?: PolyphonicCallOptions): PolyphonicMemoryResult[];
+    /** The standard recall ranking for the same query, fused as one more voice. */
+    hybridVoice(baseline: readonly RecallResult[], options?: PolyphonicCallOptions): VoiceRecallResult[];
+    vectorVoice(queryEmbedding: readonly number[] | Float32Array | null, options?: PolyphonicCallOptions): VoiceRecallResult[];
+    /**
+     * Memories whose gist or KG facts name a query entity (seeds), plus memories reached
+     * from the strongest seeds over `ctx` edges. The walk is one multi-source BFS: each
+     * node expands at most once, every hop is one batched edge query, and seeds, frontier,
+     * edge rows and results are all capped, so dense proactively linked banks cost the
+     * same bounded work as sparse ones.
+     */
     graphVoice(query: string): VoiceRecallResult[];
     factVoice(query: string): VoiceRecallResult[];
-    temporalVoice(query: string): VoiceRecallResult[];
+    temporalVoice(query: string, options?: PolyphonicCallOptions): VoiceRecallResult[];
+    /**
+     * Reciprocal rank fusion. A voice may report the same memory several times (e.g. the
+     * graph voice once per matching gist or fact); only its best rank counts, so each
+     * voice contributes at most `1 / (RRF_K + 1)` and the fused score stays bounded by
+     * {@link POLYPHONIC_MAX_COMBINED_SCORE}.
+     */
     combineVoices(...voiceResults: readonly VoiceRecallResult[][]): Map<string, PolyphonicResult>;
-    diversityRerank(results: ReadonlyMap<string, PolyphonicResult>, topK: number): PolyphonicResult[];
-    estimateSimilarity(a: PolyphonicResult, b: PolyphonicResult): number;
-    assembleContext(results: readonly PolyphonicResult[], budget: number): PolyphonicResult[];
+    /**
+     * Walk fused candidates best-first, hydrating each and skipping rows that are not
+     * visible or whose content near-duplicates an already selected row, until `topK`
+     * rows are selected.
+     */
+    diversityRerank(results: ReadonlyMap<string, PolyphonicResult>, topK: number, hydrate: (candidate: PolyphonicResult) => PolyphonicMemoryResult | null): PolyphonicMemoryResult[];
+    assembleContext(results: readonly PolyphonicMemoryResult[], budget: number): PolyphonicMemoryResult[];
     getStats(): Record<string, JsonValue>;
     close(): void;
-    private hydrateResults;
-    private lookupMemory;
 }
+/**
+ * The beam's polyphonic engine, built on first use. Building it creates the fact voice
+ * tables; until it succeeds once, each call also backfills `consolidated_facts` from KG
+ * facts extracted while polyphonic recall was off, so enabling the flag on an existing
+ * bank starts with a fact voice and a failed backfill (e.g. a busy database) is retried.
+ */
 export declare function getPolyphonicEngine(beam: BeamMemoryState): PolyphonicRecallEngine;
 export declare function polyphonicRecall(beam: BeamMemoryState, query: string, topK?: number, options?: PolyphonicRecallOptions): PolyphonicMemoryResult[];
 export {};

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

@@ -21,9 +21,19 @@ export interface QueryCacheStats {
     readonly max_size: number;
     readonly version: number;
 }
-export declare function isEnhancedRecallEnabled(env?: Env): boolean;
-export declare function isQueryCacheEnabled(useCache?: boolean, env?: Env): boolean;
-export declare class QueryCache {
+export declare function isEnhancedRecallEnabled(env?: Env, configured?: boolean): boolean;
+export declare function isQueryCacheEnabled(useCache?: boolean, env?: Env, configured?: boolean): boolean;
+/**
+ * Tiered query result cache. Every entry lives in a `scope`: an opaque string the
+ * caller derives from all non-query inputs (result limit, filters, visibility,
+ * ranking mode, ...). Lookups only ever consider entries of the same scope, so the
+ * fuzzy tiers can match a *similar query* but never a different set of options.
+ *
+ * - Tier 1: exact normalized query match.
+ * - Tiers 2/3: query embedding cosine >= 0.88, or >= 0.78 plus word overlap.
+ * - Tier 4: normalized word overlap.
+ */
+export declare class QueryCache<T = QueryCacheResult> {
     #private;
     readonly maxSize: number;
     readonly ttlSeconds: number;
@@ -35,8 +45,8 @@ export declare class QueryCache {
     tier4Hits: number;
     constructor(options?: QueryCacheOptions | string | null, maxSize?: number, ttlSeconds?: number);
     invalidate(): void;
-    get(query: string, embedding?: QueryEmbedding | null): readonly QueryCacheResult[] | null;
-    put(query: string, results: readonly QueryCacheResult[], embedding?: QueryEmbedding | null): void;
+    get(query: string, embedding?: QueryEmbedding | null, scope?: string): readonly T[] | null;
+    put(query: string, results: readonly T[], embedding?: QueryEmbedding | null, scope?: string): void;
     close(): void;
     get hitRate(): number;
     stats(): QueryCacheStats;

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

@@ -9,6 +9,12 @@ export declare const VERACITY_WEIGHTS: Readonly<{
 }>;
 export type Veracity = keyof typeof VERACITY_WEIGHTS;
 export declare const VERACITY_ALLOWED: Record<Veracity, true>;
+/**
+ * Relations that legitimately hold for many objects at once ("Alice uses Rust" and
+ * "Alice uses Go" are both true). A second object for them is not a contradiction, so
+ * no conflict is recorded; otherwise every pair of objects would be one (quadratic).
+ */
+export declare const MULTI_VALUED_PREDICATES: Readonly<Record<string, true>>;
 export interface ConsolidatedFact {
     readonly subject: string;
     readonly predicate: string;
@@ -52,6 +58,11 @@ export declare class VeracityConsolidator {
     resolveConflict(conflictId: number, winningFactId: string): void;
     getConflicts(): Conflict[];
     getConsolidatedFacts(subject?: string | null, minConfidence?: number): ConsolidatedFact[];
+    /**
+     * Active facts whose subject equals one of `subjects`, ignoring ASCII case, so a
+     * lower-case query word finds `PostgreSQL` or `Alice`.
+     */
+    getConsolidatedFactsBySubjects(subjects: readonly string[], minConfidence?: number): ConsolidatedFact[];
     getHighConfidenceSummary(subject: string, threshold?: number): string;
     runConsolidationPass(): void;
     resolveConflictByFacts(winningId: string, losingId: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-mnemopi",
-	"version": "1.1.23",
+	"version": "1.1.25",
 	"description": "Local SQLite memory engine for omp agents",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -39,10 +39,10 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-ai": "1.1.23",
-		"@linxiraos/pi-catalog": "1.1.23",
-		"@linxiraos/pi-natives": "1.1.23",
-		"@linxiraos/pi-utils": "1.1.23"
+		"@linxiraos/pi-ai": "1.1.25",
+		"@linxiraos/pi-catalog": "1.1.25",
+		"@linxiraos/pi-natives": "1.1.25",
+		"@linxiraos/pi-utils": "1.1.25"
 	},
 	"peerDependencies": {
 		"fastembed": "2.1.0",

package/src/config.ts

@@ -279,11 +279,12 @@ let enhancedRecallDefault = false;
 let proactiveLinkingDefault = false;
 
 /**
- * Sets process-wide defaults for the env-gated recall features. Host configuration
- * (e.g. the coding-agent `mnemopi.polyphonicRecall` / `mnemopi.enhancedRecall` /
- * `mnemopi.proactiveLinking` settings) lands here; the `MNEMOPI_POLYPHONIC_RECALL` /
- * `MNEMOPI_ENHANCED_RECALL` / `MNEMOPI_PROACTIVE_LINKING` environment variables still
- * win whenever they are set.
+ * Sets process-wide defaults for the env-gated recall features. Hosts that open
+ * several memories with different policies should pass the per-instance
+ * `polyphonicRecall` / `enhancedRecall` / `proactiveLinking` options instead
+ * (`Mnemopi` / `BeamMemory` constructors), which take precedence over these
+ * defaults. The `MNEMOPI_POLYPHONIC_RECALL` / `MNEMOPI_ENHANCED_RECALL` /
+ * `MNEMOPI_PROACTIVE_LINKING` environment variables still win whenever they are set.
  */
 export function configureRecallFeatures(flags: RecallFeatureFlags): void {
 	if (flags.polyphonicRecall !== undefined) polyphonicRecallDefault = flags.polyphonicRecall;
@@ -291,18 +292,26 @@ export function configureRecallFeatures(flags: RecallFeatureFlags): void {
 	if (flags.proactiveLinking !== undefined) proactiveLinkingDefault = flags.proactiveLinking;
 }
 
-export function polyphonicRecallEnabled(env: Env = process.env): boolean {
+/**
+ * Resolves the polyphonic recall gate: the env var wins when set, then the
+ * per-instance `configured` value, then the process-wide default.
+ */
+export function polyphonicRecallEnabled(env: Env = process.env, configured?: boolean): boolean {
 	const value = envOptionalString("MNEMOPI_POLYPHONIC_RECALL", env);
-	return value === undefined ? polyphonicRecallDefault : value === "1";
+	return value === undefined ? (configured ?? polyphonicRecallDefault) : value === "1";
 }
 
 export function temporalHalflifeHours(env: Env = process.env): number {
 	return envFloat("MNEMOPI_TEMPORAL_HALFLIFE_HOURS", 24, env);
 }
 
-export function enhancedRecallEnabled(env: Env = process.env): boolean {
+/**
+ * Resolves the enhanced recall (query result cache) gate: the env var wins when
+ * set, then the per-instance `configured` value, then the process-wide default.
+ */
+export function enhancedRecallEnabled(env: Env = process.env, configured?: boolean): boolean {
 	const value = envOptionalString("MNEMOPI_ENHANCED_RECALL", env);
-	return value === undefined ? enhancedRecallDefault : value === "1";
+	return value === undefined ? (configured ?? enhancedRecallDefault) : value === "1";
 }
 
 export function proactiveLinkingEnabled(env: Env = process.env): boolean {

package/src/core/beam/consolidate.ts

@@ -1,10 +1,12 @@
 import type { SQLQueryBindings } from "bun:sqlite";
+import { logger } from "@linxiraos/pi-utils";
+import { polyphonicRecallEnabled } from "../../config";
 import { generateId, stableMemoryId } from "../../util/ids";
 import { aaakEncode } from "../aaak";
 import { REGEX_EXTRACTION_MAX_INPUT_CHARS } from "../entities";
 import { EpisodicGraph } from "../episodic-graph";
 import { type ExtractedFactCategories, heuristicExtractFacts } from "../extraction";
-import { clampVeracity } from "../veracity-consolidation";
+import { clampVeracity, VERACITY_WEIGHTS, type Veracity, VeracityConsolidator } from "../veracity-consolidation";
 import { scheduleEmbedding } from "./helpers";
 import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types";
 
@@ -325,6 +327,102 @@ function insertKg(
 		source: sourceMemoryId ?? "extraction",
 		confidence: 0.65,
 	});
+	consolidateKgFact(beam, subject, predicate, object, sourceMemoryId);
+}
+
+/** Veracity of the memory a fact was extracted from, restricted to the consolidator's vocabulary. */
+function sourceMemoryVeracity(beam: BeamMemoryState, sourceMemoryId: string | null): Veracity {
+	if (sourceMemoryId === null) return "unknown";
+	const row = (beam.db.query("SELECT veracity FROM working_memory WHERE id = ?").get(sourceMemoryId) ??
+		beam.db.query("SELECT veracity FROM episodic_memory WHERE id = ?").get(sourceMemoryId)) as {
+		veracity: string | null;
+	} | null;
+	const veracity = row?.veracity ?? "unknown";
+	return Object.hasOwn(VERACITY_WEIGHTS, veracity) ? (veracity as Veracity) : "unknown";
+}
+
+/**
+ * This beam's veracity consolidator, created on first use so `consolidated_facts` /
+ * `conflicts` DDL only runs once polyphonic recall needs them.
+ */
+export function ensureVeracityConsolidator(beam: BeamMemoryState): VeracityConsolidator {
+	const existing = beam.veracityConsolidator;
+	if (existing instanceof VeracityConsolidator && existing.conn === beam.db) return existing;
+	const consolidator = new VeracityConsolidator(beam.dbPath ?? ":memory:", beam.db);
+	beam.veracityConsolidator = consolidator;
+	return consolidator;
+}
+
+/**
+ * Feed an extracted subject/predicate/object fact into the veracity consolidator so
+ * repeated mentions gain confidence in `consolidated_facts`, which the polyphonic
+ * recall fact voice reads. Only runs while polyphonic recall is enabled for this beam;
+ * facts written with it off are picked up by {@link backfillConsolidatedFacts}.
+ * Best-effort: a failure never blocks the extraction write.
+ */
+function consolidateKgFact(
+	beam: BeamMemoryState,
+	subject: string,
+	predicate: string,
+	object: string,
+	sourceMemoryId: string | null,
+): void {
+	if (!polyphonicRecallEnabled(process.env, beam.config?.polyphonicRecall)) return;
+	const cleanSubject = subject.trim();
+	const cleanPredicate = predicate.trim();
+	const cleanObject = object.trim();
+	if (cleanSubject === "" || cleanPredicate === "" || cleanObject === "") return;
+	try {
+		ensureVeracityConsolidator(beam).consolidateFact(
+			cleanSubject,
+			cleanPredicate,
+			cleanObject,
+			sourceMemoryVeracity(beam, sourceMemoryId),
+			sourceMemoryId,
+		);
+	} catch (error) {
+		// Fact consolidation is an enrichment; the MEMORIA/KG rows above are already written,
+		// and the next polyphonic engine built on this bank backfills the fact.
+		logger.warn("mnemopi: fact consolidation failed", { subject: cleanSubject, error: String(error) });
+	}
+}
+
+/**
+ * Consolidate every extracted KG fact (`memoria_kg`) whose source memory is not yet
+ * among that fact's `consolidated_facts` sources, e.g. facts written while polyphonic
+ * recall was off. Idempotent: a (fact, source) pair is only ever counted once.
+ * Facts without a source memory are skipped; the fact voice could not return them.
+ */
+export function backfillConsolidatedFacts(beam: BeamMemoryState, consolidator: VeracityConsolidator): number {
+	const rows = beam.db
+		.query(`
+			SELECT trim(k.subject) AS subject, trim(k.predicate) AS predicate, trim(k.object) AS object,
+				k.source_memory_id AS source
+			FROM memoria_kg k
+			WHERE k.source_memory_id IS NOT NULL AND k.source_memory_id != ''
+				AND trim(k.subject) != '' AND trim(k.predicate) != '' AND trim(k.object) != ''
+				AND NOT EXISTS (
+					SELECT 1 FROM consolidated_facts cf, json_each(cf.sources_json) s
+					WHERE cf.subject = trim(k.subject) AND cf.predicate = trim(k.predicate)
+						AND cf.object = trim(k.object) AND s.value = k.source_memory_id
+				)
+			GROUP BY 1, 2, 3, 4
+			ORDER BY MIN(k.id)
+		`)
+		.all() as { subject: string; predicate: string; object: string; source: string }[];
+	if (rows.length === 0) return 0;
+	consolidator.serializedWrite(() => {
+		for (const row of rows) {
+			consolidator.consolidateFact(
+				row.subject,
+				row.predicate,
+				row.object,
+				sourceMemoryVeracity(beam, row.source),
+				row.source,
+			);
+		}
+	});
+	return rows.length;
 }
 
 function insertPreference(