Interface ICognitiveMemoryManager

interface ICognitiveMemoryManager {
    initialize(config): Promise<void>;
    encode(input, mood, gmiMood, options?): Promise<MemoryTrace>;
    retrieve(query, mood, options?): Promise<CognitiveRetrievalResult>;
    assembleForPrompt(query, tokenBudget, mood, options?): Promise<AssembledMemoryContext>;
    observe?(role, content, mood?, options?): Promise<null | ObservationNote[]>;
    checkProspective?(context): Promise<ProspectiveMemoryItem[]>;
    registerProspective?(input): Promise<ProspectiveMemoryItem>;
    listProspective?(): Promise<ProspectiveMemoryItem[]>;
    removeProspective?(id): Promise<boolean>;
    runConsolidation?(): Promise<ConsolidationResult>;
    getMemoryHealth(): Promise<MemoryHealthReport>;
    getStore(): MemoryStore;
    getTraceCount(): number;
    getWorkingMemory(): CognitiveWorkingMemory;
    getConfig(): CognitiveMemoryConfig;
    getGraph(): null | IMemoryGraph;
    getObserver(): null | MemoryObserver;
    getReflector(): null | MemoryReflector;
    flushReflection(mood?, scopeOverride?): Promise<FlushReflectionResult>;
    getProspective(): null | ProspectiveMemoryManager;
    setHydeRetriever?(retriever): void;
    getHydeRetriever?(): null | HydeRetriever;
    getRerankerService?(): null | RerankerService;
    getContextWindowStats(): null | ContextWindowStats;
    getContextTransparencyReport(): null | string;
    rehydrate?(traceId, requestContext?): Promise<null | string>;
    deleteScope?(scope, scopeId, options?): Promise<MemoryDeletion>;
    deleteTraces?(traceIds): Promise<MemoryDeletion>;
    ensureEncodedScopeIds?(): Promise<number>;
    shutdown(): Promise<void>;
}

Implemented by

Methods

initialize encode retrieve assembleForPrompt observe? checkProspective? registerProspective? listProspective? removeProspective? runConsolidation? getMemoryHealth getStore getTraceCount getWorkingMemory getConfig getGraph getObserver getReflector flushReflection getProspective setHydeRetriever? getHydeRetriever? getRerankerService? getContextWindowStats getContextTransparencyReport rehydrate? deleteScope? deleteTraces? ensureEncodedScopeIds? shutdown

Methods

initialize

encode

  • encode(input, mood, gmiMood, options?): Promise<MemoryTrace>

  • Encode a new input into a memory trace. Called after each user message.

    Parameters

    • input: string
    • mood: PADState
    • gmiMood: string
    • Optional options: {
          type?: MemoryType;
          scope?: MemoryScope;
          scopeId?: string;
          sourceType?: MemorySourceType;
          contentSentiment?: number;
          tags?: string[];
          entities?: string[];
          turnUserId?: string;
          perspectiveSource?: {
              eventId: string;
              eventHash: string;
          };
      }
      • Optional type?: MemoryType
      • Optional scope?: MemoryScope
      • Optional scopeId?: string
      • Optional sourceType?: MemorySourceType
      • Optional contentSentiment?: number
      • Optional tags?: string[]
      • Optional entities?: string[]
      • Optional turnUserId?: string

        MemoryTrace.turnUserId: set on a trace a turn with no learner files for a second user.

      • Optional perspectiveSource?: {
            eventId: string;
            eventHash: string;
        }

        When encoding a subjective trace from PerspectiveObserver (@framers/agentos/memory/pipeline/observation/PerspectiveObserver), thread the source-event identifiers through so the resulting MemoryTrace carries the MechanismMetadata fields that applyReconsolidation reads at retrieval time.

        • eventId: string
        • eventHash: string

    Returns Promise<MemoryTrace>

retrieve

assembleForPrompt

Optional observe

Optional checkProspective

  • checkProspective(context): Promise<ProspectiveMemoryItem[]>

  • Check prospective memory triggers (Batch 2).

    Parameters

    • context: {
          now?: number;
          events?: string[];
          queryText?: string;
          queryEmbedding?: number[];
          maxTierRank?: number;
      }
      • Optional now?: number
      • Optional events?: string[]
      • Optional queryText?: string
      • Optional queryEmbedding?: number[]
      • Optional maxTierRank?: number

        Policy-tier ceiling: drop prospective items whose tierRank exceeds it, matching the assembly path. Forwarded to prospective.check.

    Returns Promise<ProspectiveMemoryItem[]>

Optional registerProspective

Optional listProspective

Optional removeProspective

Optional runConsolidation

getMemoryHealth

getStore

getTraceCount

getWorkingMemory

getConfig

getGraph

getObserver

getReflector

flushReflection

  • flushReflection(mood?, scopeOverride?): Promise<FlushReflectionResult>

  • Step-8: Force the memory reflector to run over any pending observation notes regardless of accumulated-token threshold. Encoded reflection traces land in the memory store; superseded trace IDs are soft-deleted. Returns the IDs so callers can apply side effects (e.g. BM25 indexing).

    Parameters

    • Optional mood: PADState

      Optional mood override passed to each encoded trace.

    • Optional scopeOverride: {
          scope: MemoryScope;
          scopeId: string;
      }

      When set, overrides the scope + scopeId on every reflection-derived trace before encoding. Needed when the caller (e.g. bench adapter) needs all reflection traces to land in the same scope the retrieval path queries, regardless of what the reflector LLM invented.

    Returns Promise<FlushReflectionResult>

getProspective

Optional setHydeRetriever

Optional getHydeRetriever

Optional getRerankerService

  • getRerankerService(): null | RerankerService

  • Get the attached neural reranker, or null when none is configured. Step 3 uses this so the bench-side HybridRetriever can plumb the manager's reranker into the per-case retriever without bracket-accessing a private field.

    Returns null | RerankerService

getContextWindowStats

getContextTransparencyReport

Optional rehydrate

  • rehydrate(traceId, requestContext?): Promise<null | string>

  • Return the verbatim content that was archived when this trace was consolidated, or null if the trace is not gisted/archived or the archive is unreachable.

    Parameters

    • traceId: string

      The trace id to rehydrate.

    • Optional requestContext: string

      Optional caller hint for audit.

    Returns Promise<null | string>

    The original verbatim content, or null.

Optional deleteScope

  • deleteScope(scope, scopeId, options?): Promise<MemoryDeletion>

  • Delete every trace of one scope for good, as an account deletion needs: its memory-graph node, its original in the configured archive and the typed facts extracted from it, then the trace in the cache (every store over the Brain in this process keeps none of its words), the vector index and the Brain, and the knowledge graph's episodic copy (MemoryStore.deleteScope). With no Brain, the scope's documents in the vector index are found and deleted too, those another store filed before a restart included. With turnUserId, only the scope's traces that user filed as a second user on the session (MemoryTrace.turnUserId). Optional, so a host's own implementation keeps compiling.

    Parameters

    • scope: MemoryScope
    • scopeId: string
    • Optional options: {
          turnUserId?: string;
      }
      • Optional turnUserId?: string

    Returns Promise<MemoryDeletion>

    Throws

    TypeError when scopeId is empty, so a caller's missing id never deletes every trace filed under no scope id, or when turnUserId is given and is not a non-empty string.

Optional deleteTraces

Optional ensureEncodedScopeIds

  • ensureEncodedScopeIds(): Promise<number>

  • Re-files the Brain's plain user and persona scope ids that hold a /, a % or a : in the encoded form a learning layer reads, once per Brain, and moves what the manager's store holds of the traces it moved; on a Brain another handle or process re-filed, the store follows the Brain's rows (MemoryStore.ensureEncodedScopeIds). The layer calls it when it first opens the manager. Optional, so a host's own implementation keeps compiling.

    Returns Promise<number>

    How many traces its re-file moved: none when the Brain held the record already.

shutdown

Settings

Member Visibility

Theme

On This Page

initializeencoderetrieveassembleForPromptobservecheckProspectiveregisterProspectivelistProspectiveremoveProspectiverunConsolidationgetMemoryHealthgetStoregetTraceCountgetWorkingMemorygetConfiggetGraphgetObservergetReflectorflushReflectiongetProspectivesetHydeRetrievergetHydeRetrievergetRerankerServicegetContextWindowStatsgetContextTransparencyReportrehydratedeleteScopedeleteTracesensureEncodedScopeIdsshutdown