@orka-js/memory-store

Conversation memory management for OrkaJS agents — sliding window, token buffer, summary, vector, and knowledge graph strategies.

Installation

npm install @orka-js/memory-store

Quick Start

import { Memory, SessionMemory } from '@orka-js/memory-store';

// Single-conversation buffer with a sliding window
const memory = new Memory({ maxMessages: 20, strategy: 'sliding_window' });

memory.addMessage({ role: 'user', content: 'Hello!' });
memory.addMessage({ role: 'assistant', content: 'Hi there! How can I help?' });

const history = memory.getHistory();
// Pass history to your LLM on every turn

// Multi-session memory for a web server
const sessions = new SessionMemory({ sessionTTL: 30 * 60 * 1000 }); // 30 min TTL

sessions.addMessage('user-123', { role: 'user', content: 'What is my order status?' });
const history = sessions.getHistory('user-123');

// Clean up expired sessions periodically
const cleared = sessions.clearExpiredSessions();

API

`Memory`

Basic in-process conversation buffer. Trims automatically according to strategy.

import { Memory } from '@orka-js/memory-store';

const memory = new Memory({
  maxMessages?: number,          // default 50 — max messages before trimming
  maxTokensEstimate?: number,    // default 4000 — used by 'buffer' strategy
  strategy?: 'sliding_window' | 'buffer' | 'summary',  // default 'sliding_window'
  summaryThreshold?: number,     // default 10 — for 'summary' strategy
});

Method	Returns	Description
`.addMessage(message)`	`void`	Append a message and trim if needed
`.getHistory()`	`Message[]`	Full conversation history
`.getLastMessages(count)`	`Message[]`	Last N messages
`.getFormattedHistory()`	`string`	`"role: content\n..."`
`.getSummary()`	`string`	Summary buffer (only when strategy is `'summary'`)
`.getMessageCount()`	`number`	Current message count
`.clear()`	`void`	Wipe all messages

`SessionMemory`

Manages independent Memory instances keyed by session ID, with automatic TTL expiry.

import { SessionMemory } from '@orka-js/memory-store';

const sessions = new SessionMemory({
  sessionTTL?: number,     // ms before idle session expires (default 30 min)
  maxMessages?: number,
  strategy?: 'sliding_window' | 'buffer' | 'summary',
});

Method	Returns	Description
`.addMessage(sessionId, message)`	`void`	Add message to a session
`.getSession(sessionId)`	`Memory`	Get (or create) the session's `Memory`
`.getHistory(sessionId)`	`Message[]`	Message history for a session
`.clearSession(sessionId)`	`void`	Delete a session
`.clearExpiredSessions()`	`number`	Remove expired sessions, return count
`.getActiveSessions()`	`string[]`	List active session IDs
`.getSessionCount()`	`number`	Number of active sessions

`SummaryMemory`

LLM-powered memory that auto-compresses old messages into a rolling summary when the buffer exceeds maxMessages. Supports progressive (incremental) compression.

import { SummaryMemory } from '@orka-js/memory-store';

const memory = new SummaryMemory({
  llm: myLLMAdapter,         // required — used for summarization
  maxMessages?: number,      // default 20
  summaryThreshold?: number, // default 10
  summaryMaxLength?: number, // default 1000 chars
  preserveSystemMessages?: boolean,    // default true
  progressiveCompression?: boolean,    // default true — incremental summaries
  compressionRatio?: number,           // default 0.5
});

Method	Returns	Description
`.addMessage(message)`	`Promise<void>`	Add a message; triggers auto-summarization when needed
`.addMessages(messages)`	`Promise<void>`	Batch add messages
`.getHistory()`	`Message[]`	Messages prefixed with summary system message if available
`.getRecentMessages()`	`Message[]`	Raw unsummarized messages
`.getSummary()`	`string`	Current summary text
`.getSummaryStats()`	`{ summary, messageCount, lastSummarizedAt }`	Summary metadata
`.compress()`	`Promise<CompressResult>`	Force compression on demand
`.clear()`	`void`	Wipe messages and summary
`SummaryMemory.fromJSON(data, llm)`	`SummaryMemory`	Deserialize from JSON

`VectorMemory`

Stores messages in a vector database for semantic search. Use .search(query) to recall the most relevant past exchanges.

import { VectorMemory } from '@orka-js/memory-store';

const memory = new VectorMemory({
  embeddings: myEmbeddingsAdapter,  // required
  vectorDB: myVectorDBAdapter,      // required
  maxMessages?: number,             // default 100
  searchTopK?: number,              // default 5
  similarityThreshold?: number,     // default 0.7
  chunkSize?: number,               // context window around matches (default 3)
  includeMetadata?: boolean,        // default true
});

Method	Returns	Description
`.addMessage(message)`	`Promise<string>`	Embed and store a message; returns ID
`.addMessages(messages)`	`Promise<string[]>`	Batch embed and store
`.search(query, topK?)`	`Promise<MemorySearchResult[]>`	Find semantically similar messages
`.searchWithContext(query, topK?)`	`Promise<MemorySearchResult[]>`	Find matches with surrounding context
`.getRelevantHistory(query)`	`Promise<Message[]>`	De-duplicated relevant messages sorted by time
`.getHistory()`	`Message[]`	All messages in insertion order
`.getRecentMessages(count)`	`Message[]`	Last N messages
`.clear()`	`Promise<void>`	Delete all messages from store

`KGMemory`

Builds a live knowledge graph from conversation content. Entities and relations are extracted in batches by an LLM; the graph is queryable to produce context summaries.

import { KGMemory } from '@orka-js/memory-store';

const memory = new KGMemory({
  llm: myLLMAdapter,              // required — used for extraction and querying
  maxMessages?: number,           // default 100
  maxTriples?: number,            // default 500
  extractionBatchSize?: number,   // default 5 — messages per extraction call
  preserveRecentMessages?: number, // default 10
});

Method	Returns	Description
`.addMessage(message)`	`Promise<void>`	Add message; triggers extraction when batch is full
`.addMessages(messages)`	`Promise<void>`	Batch add
`.queryKnowledge(query)`	`Promise<string>`	Ask the graph for context relevant to a query
`.getContextForQuery(query)`	`Promise<Message[]>`	Graph context + recent messages for prompt injection
`.getEntities()`	`Entity[]`	All known entities
`.getRelations()`	`Relation[]`	All extracted relations
`.getEntity(name)`	`Entity \| undefined`	Look up an entity by name
`.getRelationsFor(name)`	`Relation[]`	Relations involving an entity
`.getTriples()`	`KnowledgeTriple[]`	All subject–predicate–object triples
`.getGraphSummary()`	`{ entityCount, relationCount, tripleCount }`	Graph statistics
`.forceExtraction()`	`Promise<void>`	Flush pending extraction
`.clear()`	`void`	Wipe messages and graph
`KGMemory.fromJSON(data, llm)`	`KGMemory`	Deserialize from JSON

Types

import type {
  Message,
  MemoryConfig,
  SummaryMemoryConfig,
  CompressResult,
  Entity,
  Relation,
  KnowledgeTriple,
  MemorySearchResult,
  MemoryVectorSearchResult,
  BaseLLM,
  BaseEmbeddings,
  BaseVectorDB,
} from '@orka-js/memory-store';

Message

interface Message {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp?: number;
  metadata?: Record<string, unknown>;
}

@orka-js/core — Core types and adapters
@orka-js/tools — Document loaders and RAG chains
@orka-js/evaluation — Evaluate agent quality
orkajs — Full OrkaJS bundle