@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/compositor.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Compositor
+ * hypermem Compositor
  *
  * Assembles context for LLM calls by orchestrating all four memory layers:
  *   L1 Redis    — hot session working memory (system, identity, recent msgs)
@@ -11,36 +11,55 @@
  * Provider-neutral internally, translates at the output boundary.
  */
 import type { DatabaseSync } from 'node:sqlite';
-import type { ComposeRequest, ComposeResult, CompositorConfig } from './types.js';
-import { RedisLayer } from './redis.js';
+import type { ComposeRequest, ComposeResult, NeutralMessage, CompositorConfig } from './types.js';
+import { CollectionTrigger } from './trigger-registry.js';
+import { CacheLayer } from './cache.js';
+type AnyCache = CacheLayer;
 import { VectorStore } from './vector-store.js';
+import { type OrgRegistry } from './cross-agent.js';
+export { CollectionTrigger, DEFAULT_TRIGGERS, matchTriggers } from './trigger-registry.js';
+export { getTurnAge, applyToolGradient, appendToolSummary, truncateWithHeadTail, applyTierPayloadCap, evictLargeToolResults };
 /**
- * A trigger definition maps a collection to the conversation signals that
- * indicate it should be queried. When any keyword matches the user's latest
- * message, the compositor fetches relevant chunks from that collection.
+ * Public reshape helper: apply tool gradient then trim to fit within a token budget.
  *
- * Centralizing trigger logic here (not in workspace stubs) means:
- * - One update propagates to all agents
- * - Stubs become documentation, not code
- * - Trigger logic can be tested independently
+ * Used by the plugin's budget-downshift pass to pre-process a Redis history window
+ * after a model switch to a smaller context window, before the full compose pipeline
+ * runs. Trims from oldest to newest until estimated token cost fits within
+ * tokenBudget * 0.65 (using the standard char/4 heuristic).
+ *
+ * @param messages     NeutralMessage array from the Redis hot window
+ * @param tokenBudget  Effective token budget for this session
+ * @returns            Trimmed message array ready for setWindow()
  */
-export interface CollectionTrigger {
-    /** Collection path: governance/policy, identity/job, etc. */
-    collection: string;
-    /** Keywords that trigger this collection (case-insensitive) */
-    keywords: string[];
-    /** Max tokens to inject from this collection */
-    maxTokens?: number;
-    /** Max chunks to retrieve */
-    maxChunks?: number;
-}
+export declare function applyToolGradientToWindow(messages: NeutralMessage[], tokenBudget: number, totalWindowTokens?: number): NeutralMessage[];
 /**
- * Default trigger registry for standard ACA collections.
- * Covers the core ACA offload use case from Anvil's spec.
+ * Canonical history must remain lossless for tool turns.
+ *
+ * If a window contains any structured tool calls or tool results, the caller
+ * should treat applyToolGradientToWindow() as a view-only transform for the
+ * current compose pass and avoid writing the reshaped messages back into the
+ * canonical cache/history store.
  */
-export declare const DEFAULT_TRIGGERS: CollectionTrigger[];
+export declare function canPersistReshapedHistory(messages: NeutralMessage[]): boolean;
+declare function truncateWithHeadTail(content: string, maxChars: number, maxTailChars?: number): string;
+declare function appendToolSummary(textContent: string | null, summary: string): string;
+declare function getTurnAge(messages: NeutralMessage[], index: number): number;
+declare function applyTierPayloadCap(msg: NeutralMessage, perResultCap: number, perTurnCap?: number, usedSoFar?: number, maxTailChars?: number): {
+    msg: NeutralMessage;
+    usedChars: number;
+};
+declare function evictLargeToolResults<T extends NeutralMessage>(messages: T[]): T[];
+/**
+ * Apply gradient tool treatment to a message array.
+ *
+ * Tiers are based on turn age, where turn age is the number of newer user
+ * messages after the current message.
+ */
+declare function applyToolGradient<T extends NeutralMessage>(messages: T[], opts?: {
+    totalWindowTokens?: number;
+}): T[];
 export interface CompositorDeps {
-    redis: RedisLayer;
+    cache: AnyCache;
     vectorStore?: VectorStore | null;
     libraryDb?: DatabaseSync | null;
     /** Custom trigger registry; defaults to DEFAULT_TRIGGERS if not provided */
@@ -48,16 +67,29 @@ export interface CompositorDeps {
 }
 export declare class Compositor {
     private readonly config;
-    private readonly redis;
+    private readonly cache;
     private vectorStore;
     private readonly libraryDb;
     private readonly triggerRegistry;
-    constructor(deps: CompositorDeps | RedisLayer, config?: Partial<CompositorConfig>);
+    /** Cached org registry loaded from fleet_agents at construction time. */
+    private _orgRegistry;
+    constructor(deps: CompositorDeps, config?: Partial<CompositorConfig>);
     /**
      * Set or replace the vector store after construction.
-     * Called by HyperMem.create() once sqlite-vec is confirmed available.
+     * Called by hypermem.create() once sqlite-vec is confirmed available.
      */
     setVectorStore(vs: VectorStore): void;
+    /**
+     * Hot-reload the org registry from the fleet_agents table.
+     * Call after fleet membership changes (new agent, org restructure)
+     * to pick up the latest without a full restart.
+     * Falls back to the current cached registry if the DB is unavailable.
+     */
+    refreshOrgRegistry(): OrgRegistry;
+    /**
+     * Return the currently cached org registry.
+     */
+    get orgRegistry(): OrgRegistry;
     /**
      * Compose a complete message array for sending to an LLM.
      *
@@ -81,24 +113,43 @@ export declare class Compositor {
         systemPrompt?: string;
         identity?: string;
         libraryDb?: DatabaseSync;
+        /** Model string for budget resolution. If omitted, falls back to defaultTokenBudget. */
+        model?: string;
     }): Promise<void>;
+    refreshRedisGradient(agentId: string, sessionKey: string, db: DatabaseSync, tokenBudget?: number): Promise<void>;
     /**
      * Get slot content: try Redis first, fall back to SQLite.
      */
     private getSlotContent;
     /**
      * Get conversation history: try Redis first, fall back to SQLite.
+     *
+     * When topicId is provided (P3.4), the SQLite path filters to messages
+     * matching that topic OR with topic_id IS NULL (Option B transition safety).
+     * The Redis path is unaffected — Redis doesn't index by topic, so topic
+     * filtering only applies to the SQLite fallback.
      */
     private getHistory;
     /**
      * Build facts content from library DB.
      */
+    /**
+     * Build facts content from library DB.
+     * Applies filterByScope (W1) to enforce retrieval access control.
+     * Returns [content, factCount, scopeFilteredCount] or null if DB unavailable.
+     */
     private buildFactsFromDb;
     /**
      * Build knowledge content from library DB.
      * Prioritizes high-confidence, non-superseded entries.
      */
     private buildKnowledgeFromDb;
+    /**
+     * Build wiki page context for the active topic.
+     * Queries the knowledge table for a synthesized topic page and returns it
+     * wrapped with a header. Capped at 600 tokens.
+     */
+    private buildWikiPageContext;
     /**
      * Build preferences content from library DB.
      * Shows user/operator preferences relevant to this agent.
@@ -110,6 +161,9 @@ export declare class Compositor {
      * Uses Reciprocal Rank Fusion to merge keyword and vector results.
      * Gracefully degrades: FTS5-only when no vector store, KNN-only
      * when FTS query is empty (all stop words), both when available.
+     *
+     * @param precomputedEmbedding — optional pre-computed embedding for the query.
+     *   When provided, the Ollama call inside VectorStore.search() is skipped.
      */
     private buildSemanticRecall;
     /**
@@ -135,5 +189,38 @@ export declare class Compositor {
      * Truncates at line boundaries when possible.
      */
     private truncateToTokens;
+    /**
+     * Query and score keystone candidates from before the current history window.
+     *
+     * Trims the oldest messages from includedHistory to free a keystone budget,
+     * then queries the DB for older messages scored by episode significance,
+     * FTS5 relevance, and recency.
+     *
+     * Returns null if keystones cannot be injected (no cutoff ID found,
+     * no candidates, or all errors).
+     */
+    private buildKeystones;
+    /**
+     * Pull high-signal messages from OTHER topics in this session when their
+     * content is semantically relevant to the current active topic.
+     *
+     * Heuristic-only: no model calls. Token overlap between the current topic
+     * name + last 3 user messages and candidate message content.
+     *
+     * @param agentId      - The agent's ID
+     * @param sessionKey   - Current session key
+     * @param activeTopic  - The current active topic (id + name)
+     * @param currentMessages - Recently included history messages for query extraction
+     * @param db           - The messages database
+     * @param maxKeystones - Max cross-topic keystones to return (default 3)
+     * @returns Scored keystones sorted by score DESC, deduplicated by message id
+     */
+    private getKeystonesByTopic;
+    /**
+     * Extract lowercase key terms from a topic name and the last 3 user messages.
+     * Terms are: tokens with ≥4 characters (skip short stop words).
+     * Returns a Set for O(1) lookup.
+     */
+    private extractQueryTerms;
 }
 //# sourceMappingURL=compositor.d.ts.map

package/dist/compositor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compositor.d.ts","sourceRoot":"","sources":["../src/compositor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAKb,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAiBzE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,EAkE/C,CAAC;AA6KF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,4EAA4E;IAC5E,eAAe,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACvC;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;gBAGpD,IAAI,EAAE,cAAc,GAAG,UAAU,EACjC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAkBpC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI;IAIrC;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAqjB1G;;;OAGG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,YAAY,EAChB,IAAI,CAAC,EAAE;QACL,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,YAAY,CAAC;KAC1B,GACA,OAAO,CAAC,IAAI,CAAC;IA8DhB;;OAEG;YACW,cAAc;IAoB5B;;OAEG;YACW,UAAU;IAoBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyC5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA4C9B;;;;;;OAMG;YACW,mBAAmB;IA6DjC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA6ChC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAezB"}
+{"version":3,"file":"compositor.d.ts","sourceRoot":"","sources":["../src/compositor.ts"],"names":[],"mappings":"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"}