Memory API

Every adapter method returns a MemoryResult<T> ({ success: true, data } | { success: false, error }). Check result.success, or use unwrap():

import { InMemoryAdapter, unwrap } from '@cogitator-ai/memory';

const memory = new InMemoryAdapter();
await memory.connect();

const thread = unwrap(await memory.createThread('agent-1', { topic: 'billing' }));
await memory.addEntry({
  threadId: thread.id,
  message: { role: 'user', content: 'Hello' },
  tokenCount: 2,
});
const entries = unwrap(await memory.getEntries({ threadId: thread.id, limit: 20 }));

Memory AdaptersCopy Anchor Link

All conversation adapters implement MemoryAdapter:

The adapter configs take provider plus the fields above; inside CogitatorConfig.memory the same fields go under inMemory, redis, postgres, sqlite or mongodb without provider. See Memory Adapters.

Facts and EmbeddingsCopy Anchor Link

Embedding ServicesCopy Anchor Link

EmbeddingService: embed(text): Promise<number[]>, embedBatch(texts): Promise<number[][]>, dimensions, model.

See Embeddings.

SearchCopy Anchor Link

defaultWeights is { bm25: 0.4, vector: 0.6 }. See Hybrid Search.

Context Building and TokensCopy Anchor Link

ContextBuilderConfig is { maxTokens, strategy: 'recent' | 'relevant' | 'hybrid', reserveTokens?, includeSystemPrompt?, includeFacts?, includeSemanticContext?, includeGraphContext?, graphContextOptions? }; ContextBuilderDeps is { memoryAdapter, factAdapter?, embeddingAdapter?, embeddingService?, graphContextBuilder? }.

Core Facts, Sessions, CompactionCopy Anchor Link

SummarizeFn is (messages: Message[], options?: SummarizeOptions) => Promise<string>, where SummarizeOptions is { model?: string; prompt?: string }, filled from summaryModel / summaryPrompt of the CompactionConfig passed to compact().

Knowledge GraphsCopy Anchor Link

GraphAdapter methods: addNode, getNode, getNodeByName, updateNode, deleteNode, queryNodes, searchNodesSemantic, addEdge, getEdge, getEdgesBetween, updateEdge, deleteEdge, queryEdges, traverse, findShortestPath, getNeighbors, mergeNodes, clearGraph, getGraphStats — all returning MemoryResult. See Knowledge Graphs.

Zod SchemasCopy Anchor Link

For validating configuration: MemoryProviderSchema, InMemoryConfigSchema, RedisConfigSchema, PostgresConfigSchema, SQLiteConfigSchema, MongoDBConfigSchema, QdrantConfigSchema, MemoryAdapterConfigSchema, ContextStrategySchema, ContextBuilderConfigSchema, EmbeddingProviderSchema, OpenAIEmbeddingConfigSchema, OllamaEmbeddingConfigSchema, GoogleEmbeddingConfigSchema, EmbeddingServiceConfigSchema, and the knowledge-graph schemas (GraphNodeSchema, GraphEdgeSchema, ExtractionResultSchema, TraversalOptionsSchema, KnowledgeGraphConfigSchema, …).

TypesCopy Anchor Link

Re-exported from @cogitator-ai/types:

interface Thread {
  id: string;
  agentId: string;
  metadata: Record<string, unknown>; // metadata.userId: the owning user
  createdAt: Date;
  updatedAt: Date;
}

interface MemoryEntry {
  id: string;
  threadId: string;
  message: Message;
  toolCalls?: ToolCall[];
  toolResults?: ToolResult[];
  tokenCount: number;
  createdAt: Date;
  metadata?: Record<string, unknown>;
}

interface Fact {
  id: string;
  agentId: string;
  content: string;
  category: string;
  confidence: number;
  source: 'user' | 'inferred' | 'system';
  createdAt: Date;
  updatedAt: Date;
  expiresAt?: Date;
  metadata?: Record<string, unknown>; // metadata.userId: only in that user's context
}

interface Embedding {
  id: string;
  sourceId: string;
  sourceType: 'message' | 'fact' | 'document';
  vector: number[];
  content: string;
  createdAt: Date;
  metadata?: Record<string, unknown>;
}

interface SearchResult {
  id: string;
  sourceId: string;
  sourceType: Embedding['sourceType'];
  content: string;
  score: number;
  vectorScore?: number;
  keywordScore?: number;
  metadata?: Record<string, unknown>;
}

Also re-exported: the adapter configs, MemoryQueryOptions, SemanticSearchOptions, SearchOptions, SearchFilter, HybridSearchConfig, ContextBuilderConfig, BuiltContext, MemoryConfig, the graph types (GraphNode, GraphEdge, TraversalOptions, InferenceRule, …) and the session types (Session, SessionFilter, CompactionConfig, CompactionResult; the interface is exported as ISessionManager).