Class MemoryManager

Two-tier persistent agent memory: a hot session tier (recent turns) + a cold semantic tier (long-term recall). API-compatible with the hosted drop-in ActroneMemoryManager from @actrone/sdk, so migrating from self-hosted to governed hosted memory is a one-import change.

Example

const mm = await MemoryManager.create();
await mm.storeTurn("support-bot", "sess-1", "hi", "hello!");
const ctx = await mm.retrieveContext("support-bot", "sess-1", "hi", 4096);

Index

Constructors

constructor

new MemoryManager(parts: MemoryManagerParts): MemoryManager
Parameters
- parts: MemoryManagerParts
Returns MemoryManager
- Defined in src/manager.ts:69

Accessors

relevanceThreshold

get relevanceThreshold(): number
The admission threshold this manager applies to long-term memories: config.relevanceThreshold when set, else the embedder's calibrated threshold, else the library default.

Returns number
- Defined in src/manager.ts:83

Methods

`Static`create

create(
    options?: {
        config?: Partial<MemoryConfig>;
        l1?: L1Store;
        l2?: L2Store;
        embedder?: Embedder;
        extractor?: FactExtractor;
        reranker?: Reranker;
    },
): Promise<MemoryManager>
Build a ready manager. With no arguments it uses the in-memory store and the best local embedder available (buildLocalEmbedder): bge-small-en-v1.5 through fastembed when that package is installed (the first run downloads the model, about 130 MB), otherwise the dependency-free lexical LocalEmbedder, with a one-time warning that recall is keyword-only. Pass stores / an embedder to back it with Redis + Qdrant + a model of your choice.
Parameters
- options: {
      config?: Partial<MemoryConfig>;
      l1?: L1Store;
      l2?: L2Store;
      embedder?: Embedder;
      extractor?: FactExtractor;
      reranker?: Reranker;
  } = {}
Returns Promise<MemoryManager>
- Defined in src/manager.ts:94

storeTurn

storeTurn(
    agentId: string,
    sessionId: string,
    userMessage: string,
    assistantMessage: string,
    toolResults?: readonly {
        toolName: string;
        params: Record<string, unknown>;
        result: unknown;
        success: boolean;
        durationMs?: number;
    }[],
): Promise<string>
Persist a conversation turn to the hot session tier. Returns the turn id.
Parameters
- agentId: string
- sessionId: string
- userMessage: string
- assistantMessage: string
- OptionaltoolResults: readonly {
      toolName: string;
      params: Record<string, unknown>;
      result: unknown;
      success: boolean;
      durationMs?: number;
  }[]
Returns Promise<string>
- Defined in src/manager.ts:119

retrieveContext

retrieveContext(
    agentId: string,
    sessionId: string,
    query: string,
    tokenBudget: number,
): Promise<RetrievedContext>
Assemble context for the next LLM call using the 4-phase pipeline: parallel L1/L2 fetch → budget allocation → relevance ranking → priority pruning. The system-prompt + current-turn budget is never consumed here.
Parameters
- agentId: string
- sessionId: string
- query: string
- tokenBudget: number
Returns Promise<RetrievedContext>
- Defined in src/manager.ts:150

injectMemory

injectMemory(
    agentId: string,
    content: string,
    importance?: number,
    sessionId?: string,
    topicTags?: readonly string[],
    source?: MemorySource,
    sensitivity?: Sensitivity,
): Promise<string>
Write a fact directly into long-term memory. Returns the memory id.

source and sensitivity are provenance-typing v1: they record where the fact came from and how sensitive it is, so it can be attributed, filtered, and erased by policy (the governance seed that graduates to hosted memory).
Parameters
- agentId: string
- content: string
- importance: number = 0.8
- sessionId: string = "injected"
- OptionaltopicTags: readonly string[]
- source: MemorySource = "injected"
- sensitivity: Sensitivity = "none"
Returns Promise<string>
- Defined in src/manager.ts:218

deleteMemory

deleteMemory(agentId: string, memoryId: string): Promise<void>
Permanently remove a memory by id.
Parameters
- agentId: string
- memoryId: string
Returns Promise<void>
- Defined in src/manager.ts:258

eraseAgentMemories

eraseAgentMemories(agentId: string, sessionId?: string): Promise<void>
Local right-to-erasure: irreversibly delete an agent's long-term memories. The governance seed that graduates to hosted provable erasure. When sessionId is given, the session's hot-tier turns are cleared too; otherwise only the durable L2 store is wiped (hot-tier turns are ephemeral).
Parameters
- agentId: string
- OptionalsessionId: string
Returns Promise<void>
- Defined in src/manager.ts:270

clearSession

clearSession(agentId: string, sessionId: string): Promise<void>
Delete all hot-tier turns for a session. Long-term memories persist.
Parameters
- agentId: string
- sessionId: string
Returns Promise<void>
- Defined in src/manager.ts:280

searchMemories

searchMemories(
    agentId: string,
    query: string,
    limit?: number,
): Promise<MemoryEntry[]>
Semantic search over long-term memory, ranked by relevance + recency.
Parameters
- agentId: string
- query: string
- limit: number = 10
Returns Promise<MemoryEntry[]>
- Defined in src/manager.ts:287

getSessionMetadata

getSessionMetadata(
agentId: string,
sessionId: string,
): Promise<SessionMetadata | null>
Session stats, or null when the session does not exist / has expired.
Parameters
- agentId: string
- sessionId: string
Returns Promise<SessionMetadata | null>
- Defined in src/manager.ts:309

getRecentTurns

getRecentTurns(agentId: string, sessionId: string, n?: number): Promise<Turn[]>
Recent session turns, oldest → newest, capped at n (defaults to all retained). This is the raw history read that framework memory adapters (e.g. a LangChain BaseChatMessageHistory or a LlamaIndex BaseMemory) build on.
Parameters
- agentId: string
- sessionId: string
- Optionaln: number
Returns Promise<Turn[]>
- Defined in src/manager.ts:320

extractMemories

extractMemories(
    agentId: string,
    sessionId: string,
    n?: number,
): Promise<string[]>
Extract durable facts from a session's recent turns and store them as first-class memories (contentType: "fact", source: "extracted", with an LLM-classified sensitivity). LLM-gated: a FactExtractor must have been supplied to create() / the constructor, else a ConfigurationError is thrown. Returns the stored memory ids (empty when nothing durable is found).
Parameters
- agentId: string
- sessionId: string
- Optionaln: number
Returns Promise<string[]>
- Defined in src/manager.ts:333

close

close(): Promise<void>
Release resources the stores own, by calling their optional close().

The built-in adapters take an already-connected client the caller constructed, so they do not implement close() and nothing is torn down here: disconnecting an injected client stays the application's job. A custom store that opens its own connection should implement close(), and this is what calls it. Mirrors the Python manager, which closes both tiers on shutdown.

Returns Promise<void>
- Defined in src/manager.ts:392

Class MemoryManager

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns MemoryManager

Accessors

relevanceThreshold

Returns number

Methods

Staticcreate

Parameters

Returns Promise<MemoryManager>

storeTurn

Parameters

Returns Promise<string>

retrieveContext

Parameters

Returns Promise<RetrievedContext>

injectMemory

Parameters

Returns Promise<string>

deleteMemory

Parameters

Returns Promise<void>

eraseAgentMemories

Parameters

Returns Promise<void>

clearSession

Parameters

Returns Promise<void>

searchMemories

Parameters

Returns Promise<MemoryEntry[]>

getSessionMetadata

Parameters

Returns Promise<SessionMetadata | null>

getRecentTurns

Parameters

Returns Promise<Turn[]>

extractMemories

Parameters

Returns Promise<string[]>

close

Returns Promise<void>

Settings

On This Page

`Static`create