@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Core Types
+ * hypermem Core Types
  *
  * Provider-neutral message format and compositor interfaces.
  * These types are the internal representation — never sent directly to an LLM.
@@ -159,6 +159,16 @@ export interface Episode {
     createdAt: string;
     decayScore: number;
 }
+/**
+ * A single turn from a parent session, stripped of tool call content.
+ * Used to build spawn context for subagents.
+ */
+export interface RecentTurn {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+    seq: number;
+}
 export interface ComposeRequest {
     agentId: string;
     sessionKey: string;
@@ -183,12 +193,27 @@ export interface ComposeRequest {
      * meaning first-turn retrieval is blind and all retrieval lags by one turn.
      */
     prompt?: string;
+    /**
+     * When set, session-scoped doc chunks stored under this spawn session key
+     * are included in doc chunk retrieval at compose time.
+     * Used for subagent context inheritance: the parent buildSpawnContext() stores
+     * document chunks under a spawn sessionKey, and passes that key here so the
+     * compositor can surface them during composition.
+     */
+    parentSessionKey?: string;
     /**
      * When true, skip provider-specific translation and return NeutralMessage[]
      * instead of ProviderMessage[]. Used by the context engine plugin, which
      * returns messages to the OpenClaw runtime for its own provider translation.
      */
     skipProviderTranslation?: boolean;
+    /**
+     * When set, history fetching is scoped to this topic (Option B: also includes
+     * legacy messages with topic_id IS NULL for transition safety).
+     * If not provided, full session history is returned (no behavior change).
+     * P3.4: topic-aware compositor.
+     */
+    topicId?: string;
 }
 export interface SlotTokenCounts {
     system: number;
@@ -198,6 +223,42 @@ export interface SlotTokenCounts {
     context: number;
     library: number;
 }
+/**
+ * Compose-level diagnostics — emitted on every compose() call.
+ * Useful for observability, tuning, and debugging retrieval quality.
+ */
+export interface ComposeDiagnostics {
+    /** Number of doc chunk trigger collections that matched the user message */
+    triggerHits: number;
+    /** True when trigger-miss fallback semantic retrieval was used */
+    triggerFallbackUsed: boolean;
+    /** Number of facts included after scope filtering */
+    factsIncluded: number;
+    /** Approximate number of lines returned by semantic recall */
+    semanticResultsIncluded: number;
+    /** Number of doc chunk collections that returned at least one chunk */
+    docChunksCollections: number;
+    /** Number of items rejected by scope policy during retrieval */
+    scopeFiltered: number;
+    /**
+     * Why contextParts was empty (only set when no context was assembled).
+     * Helps distinguish between "no triggers + no fallback", "empty corpus",
+     * "budget exhausted", and "all items filtered by scope".
+     */
+    zeroResultReason?: 'no_trigger_no_fallback' | 'empty_corpus' | 'budget_exhausted' | 'scope_filtered_all' | 'unknown';
+    /** The retrieval path that was used for doc chunks */
+    retrievalMode: 'triggered' | 'fallback_knn' | 'fallback_fts' | 'none';
+    /** Number of cross-topic keystone messages injected (P3.5) */
+    crossTopicKeystones?: number;
+    /** Actual reserve fraction used this compose (base or dynamic) */
+    reserveFraction?: number;
+    /** Estimated average turn cost (tokens) used in dynamic reserve calc */
+    avgTurnCostTokens?: number;
+    /** True if dynamic reserve exceeded floor and is actively adjusting budget */
+    dynamicReserveActive?: boolean;
+    /** True if dynamic reserve was clamped at dynamicReserveMax and SESSION_PRESSURE_HIGH emitted */
+    sessionPressureHigh?: boolean;
+}
 export interface ComposeResult {
     messages: ProviderMessage[];
     tokenCount: number;
@@ -213,6 +274,8 @@ export interface ComposeResult {
      * Omitted when no context was assembled.
      */
     contextBlock?: string;
+    /** Compose-level diagnostics for observability and tuning. */
+    diagnostics?: ComposeDiagnostics;
 }
 /**
  * Provider-specific message format (output of compositor).
@@ -266,37 +329,76 @@ export interface SessionMeta {
 export interface HyperMemConfig {
     enabled: boolean;
     dataDir: string;
-    redis: RedisConfig;
+    cache: CacheConfig;
     compositor: CompositorConfig;
     indexer: IndexerConfig;
     embedding: EmbeddingProviderConfig;
+    /** Optional dreaming/promotion config. Default: disabled. */
+    dreaming?: import('./dreaming-promoter.js').DreamerConfig;
+    /** Optional Obsidian vault integration. Default: disabled. */
+    obsidian?: import('./obsidian-watcher.js').ObsidianConfig;
+    /**
+     * Cache replay threshold (ms). When > 0, assemble() returns a cached
+     * contextBlock (systemPromptAddition) for sessions active within this
+     * window, producing byte-identical prompts and hitting provider prefix cache
+     * (Anthropic / OpenAI). Set to 0 to disable.
+     * Default: 900_000 (15 minutes).
+     */
+    warmCacheReplayThresholdMs?: number;
 }
 export interface EmbeddingProviderConfig {
+    /**
+     * Embedding provider. Default: 'ollama'.
+     * - 'ollama': local Ollama (nomic-embed-text or any pulled model)
+     * - 'openai': OpenAI Embeddings API (text-embedding-3-small / 3-large)
+     */
+    provider?: 'ollama' | 'openai';
     /** Ollama base URL. Default: http://localhost:11434 */
     ollamaUrl: string;
-    /** Embedding model name. Default: nomic-embed-text */
+    /** OpenAI API key. Required when provider is 'openai'. */
+    openaiApiKey?: string;
+    /** OpenAI base URL. Default: https://api.openai.com/v1 */
+    openaiBaseUrl?: string;
+    /**
+     * Embedding model name.
+     * - ollama default: nomic-embed-text (768d)
+     * - openai default: text-embedding-3-small (1536d)
+     */
     model: string;
-    /** Embedding dimensions. Default: 768 */
+    /**
+     * Embedding dimensions. Must match the model.
+     * - nomic-embed-text: 768
+     * - text-embedding-3-small: 1536
+     * - text-embedding-3-large: 3072
+     * WARNING: changing providers requires a full re-index (dimensions are incompatible).
+     */
     dimensions: number;
     /** Request timeout ms. Default: 10000 */
     timeout: number;
-    /** Max texts per batch request. Default: 32 */
+    /** Max texts per batch request. Default: 32 (ollama) or 128 (openai) */
     batchSize: number;
 }
-export interface RedisConfig {
-    host: string;
-    port: number;
-    password?: string;
+export interface CacheConfig {
     keyPrefix: string;
     sessionTTL: number;
     historyTTL: number;
-    flushInterval: number;
 }
+/** @deprecated Use CacheConfig */
+export type RedisConfig = CacheConfig;
 export interface CompositorConfig {
     defaultTokenBudget: number;
     maxHistoryMessages: number;
     maxFacts: number;
     maxCrossSessionContext: number;
+    /**
+     * Aggregate token ceiling across all trigger-fired doc chunk collections in a
+     * single compose pass. When unset, hypermem uses a dynamic ceiling of 40% of
+     * the remaining budget at the start of trigger retrieval.
+     *
+     * This prevents pathological prompts from firing many trigger collections at
+     * once and starving the rest of the prompt budget.
+     */
+    maxTotalTriggerTokens?: number;
     /**
      * How many recent tool call/result pairs to keep verbatim in history.
      * Tool call/result content beyond this threshold gets prose-stub treatment.
@@ -316,6 +418,106 @@ export interface CompositorConfig {
      * Default: 0.4 (40% of defaultTokenBudget)
      */
     warmHistoryBudgetFraction: number;
+    /**
+     * Fraction of the model context window to reserve for output tokens and
+     * hypermem operational overhead. The compositor's effective input budget is
+     * (contextWindow × (1 - contextWindowReserve)).
+     *
+     * Higher values = more headroom for large operations, fewer turns before
+     * session break. Lower values = more context available, higher saturation risk.
+     *
+     * Default: 0.25 (25% reserve — leaves 75% for input context)
+     * Previous default was 0.10 (10% reserve).
+     */
+    contextWindowReserve?: number;
+    /**
+     * Number of turns to project forward when computing dynamic reserve.
+     * safety_tokens = avg_turn_cost × dynamicReserveTurnHorizon
+     * Default: 5
+     */
+    dynamicReserveTurnHorizon?: number;
+    /**
+     * Hard ceiling on the dynamic reserve fraction. When the projected safety
+     * tokens would push reserve above this, SESSION_PRESSURE_HIGH is emitted
+     * in diagnostics and reserve is clamped here.
+     * Default: 0.50
+     */
+    dynamicReserveMax?: number;
+    /**
+     * Kill switch for dynamic reserve. Set false to use fixed contextWindowReserve only.
+     * Default: true
+     */
+    dynamicReserveEnabled?: boolean;
+    /**
+     * Fraction of history token budget to allocate for keystone (recalled older) messages.
+     * Range: 0.0–0.5. Default: 0.2 (20% of history budget).
+     * Set to 0 to disable keystone injection.
+     */
+    keystoneHistoryFraction?: number;
+    /**
+     * Maximum number of keystone messages to inject.
+     * Default: 15
+     */
+    keystoneMaxMessages?: number;
+    /**
+     * Minimum episode significance for a message to be considered as a keystone.
+     * Only applies when episode significance is available (not null).
+     * Default: 0.5
+     */
+    keystoneMinSignificance?: number;
+    /**
+     * Fraction of the effective token budget to target for context assembly.
+     * The compositor fills slots until this fraction is consumed, leaving the
+     * remainder for conversation history and response headroom.
+     *
+     * Lower values = lighter context, faster turns, less memory surfaced.
+     * Higher values = richer context, more memory, higher saturation risk.
+     *
+     * Range: 0.3–0.85. Default: 0.65
+     * Typical lightweight config: 0.45
+     * Typical fleet/multi-agent config: 0.65
+     */
+    targetBudgetFraction?: number;
+    /**
+     * Enable Fleet Output Standard (FOS) injection.
+     * FOS injects shared output rules (no em dashes, lead with answer, etc.) into
+     * every composed context. Disable if the operator manages output standards
+     * externally (e.g. via system prompt) to avoid redundancy.
+     * Default: true
+     */
+    enableFOS?: boolean;
+    /**
+     * Enable Model Output Directive (MOD) injection.
+     * MOD injects per-model calibration corrections (verbosity, list length, etc.).
+     * Disable if you want raw model behavior without hypermem calibration.
+     * Default: true
+     */
+    enableMOD?: boolean;
+    /**
+     * Output profile tier. Controls what FOS content is injected.
+     *
+     * 'light'    — ~100 token standalone directives. No MOD, no fleet concepts.
+     *             Works on any single-agent 64k setup. No DB required.
+     * 'standard' — Full FOS: density targets, format rules, compression ratios,
+     *              task-context scoping. No MOD.
+     * 'full'     — FOS + MOD. Cross-agent coordination, full spec.
+     *
+     * Backward compat: 'starter' maps to 'light', 'fleet' maps to 'full'.
+     * Default: 'full' (backward-compatible). New install default: 'light'.
+     */
+    outputProfile?: 'light' | 'standard' | 'full' | 'starter' | 'fleet';
+    /** @deprecated Use outputProfile */
+    outputStandard?: 'light' | 'standard' | 'full' | 'starter' | 'fleet';
+    /**
+     * Hard token ceiling for wiki page injection per compose pass.
+     * Limits how much synthesized topic knowledge is inserted into context.
+     * Lower values keep context lighter; higher values surface more topic depth.
+     *
+     * Default: 600 tokens
+     * Light preset: 300 tokens
+     * Extended preset: 800 tokens
+     */
+    wikiTokenCap?: number;
 }
 export interface IndexerConfig {
     enabled: boolean;
@@ -325,5 +527,7 @@ export interface IndexerConfig {
     factDecayRate: number;
     episodeSignificanceThreshold: number;
     periodicInterval: number;
+    batchSize: number;
+    maxMessagesPerTick: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Core Types
+ * hypermem Core Types
  *
  * Provider-neutral message format and compositor interfaces.
  * These types are the internal representation — never sent directly to an LLM.

package/dist/vector-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Vector Store — Semantic Search via sqlite-vec
+ * hypermem Vector Store — Semantic Search via sqlite-vec
  *
  * Provides embedding-backed KNN search over facts, knowledge, episodes,
  * and session registry entries. Uses Ollama (local) for embeddings,
@@ -9,21 +9,34 @@
  *   - One vec0 virtual table per indexed content type
  *   - Embeddings generated via local Ollama (nomic-embed-text, 768d)
  *   - Vectors stored alongside content in the same agent DB
- *   - Embedding cache to avoid redundant API calls
+ *   - LRU embedding cache (module-level, per-process) to avoid redundant Ollama calls
+ *   - Precomputed embedding passthrough: callers can supply an embedding to skip Ollama
  *   - Batch embedding support for bulk indexing
  */
 import type { DatabaseSync } from 'node:sqlite';
 export interface EmbeddingConfig {
+    /**
+     * Embedding provider. Default: 'ollama'.
+     * - 'ollama': local Ollama instance (nomic-embed-text or any pull'd model)
+     * - 'openai': OpenAI Embeddings API (text-embedding-3-small / 3-large)
+     */
+    provider?: 'ollama' | 'openai';
     /** Ollama base URL. Default: http://localhost:11434 */
     ollamaUrl: string;
-    /** Embedding model name. Default: nomic-embed-text */
+    /** OpenAI API key. Required when provider is 'openai'. */
+    openaiApiKey?: string;
+    /** OpenAI base URL. Default: https://api.openai.com/v1 */
+    openaiBaseUrl?: string;
+    /** Embedding model name. Default: nomic-embed-text (ollama) or text-embedding-3-small (openai) */
     model: string;
-    /** Embedding dimensions. Default: 768 */
+    /** Embedding dimensions. Default: 768 (ollama/nomic) or 1536 (openai/3-small) */
     dimensions: number;
     /** Request timeout ms. Default: 10000 */
     timeout: number;
-    /** Max texts per batch request. Default: 32 */
+    /** Max texts per batch request. Default: 32 (ollama) or 128 (openai) */
     batchSize: number;
+    /** LRU cache max entries. Default: 128 */
+    cacheSize?: number;
 }
 export interface VectorSearchResult {
     rowid: number;
@@ -40,9 +53,14 @@ export interface VectorIndexStats {
     tableBreakdown: Record<string, number>;
     lastIndexedAt: string | null;
 }
+/**
+ * Clear the embedding cache. Primarily for testing.
+ */
+export declare function clearEmbeddingCache(): void;
 /**
  * Generate embeddings via Ollama API.
  * Supports single and batch embedding.
+ * Results are cached per text hash — cache hits skip the Ollama call entirely.
  */
 export declare function generateEmbeddings(texts: string[], config?: EmbeddingConfig): Promise<Float32Array[]>;
 /**
@@ -84,11 +102,16 @@ export declare class VectorStore {
     }>;
     /**
      * Semantic KNN search across one or all vector tables.
+     *
+     * @param precomputedEmbedding — optional pre-computed embedding for the query.
+     *   When provided, skips the Ollama call entirely. The precomputed embedding
+     *   is still inserted into the LRU cache so subsequent identical queries hit.
      */
     search(query: string, opts?: {
         tables?: string[];
         limit?: number;
         maxDistance?: number;
+        precomputedEmbedding?: Float32Array;
     }): Promise<VectorSearchResult[]>;
     /**
      * Get content from a source table by id.
@@ -106,6 +129,21 @@ export declare class VectorStore {
      * Remove vector index entries for deleted source rows.
      */
     pruneOrphans(): number;
+    /**
+     * Remove the vector index entry for a single source item.
+     *
+     * Deletes both the vec table row and the vec_index_map entry for the given
+     * (sourceTable, sourceId) pair. Used by the background indexer for immediate
+     * point-in-time removal when a supersedes relationship is detected.
+     *
+     * @returns true if an entry was found and removed, false if nothing was indexed.
+     */
+    removeItem(sourceTable: string, sourceId: number): boolean;
+    /**
+     * Check whether a source item already has a vector in the index.
+     * Used by the episode backfill to skip already-vectorized entries.
+     */
+    hasItem(sourceTable: string, sourceId: number): boolean;
     /**
      * Tombstone vector entries for superseded facts and knowledge.
      *

package/dist/vector-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../src/vector-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../src/vector-store.ts"],"names":[],"mappings":"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"}