Smart Memory
Three-level memory system with knowledge graph, core facts, and compaction.
Overview
The smart memory system provides three levels of persistent memory for your assistant, from fast key-value lookups to a full knowledge graph with semantic search.
Level 1: Core Facts
Key-value pairs that are always included in the system prompt. Store the most important facts about the user here — name, timezone, preferences.
import { CoreFactsStore } from '@cogitator-ai/memory';
const coreFacts = new CoreFactsStore({ path: './memory.db' });
await coreFacts.initialize();
await coreFacts.set('user_name', 'Alex');
await coreFacts.set('timezone', 'Europe/Berlin');
const prompt = await coreFacts.formatForPrompt();
// "user_name: Alex\ntimezone: Europe/Berlin"Core facts are injected into the agent instructions automatically by RuntimeBuilder.
Level 2: Knowledge Graph
SQLite-backed knowledge graph with nodes and relationships. The agent uses remember, recall, and forget tools to interact with it.
memory:
knowledgeGraph: true
autoExtract: trueMemory Tools
When knowledgeGraph is enabled, three tools are added to the agent:
remember — Save a fact to the knowledge graph
User: "My dog's name is Luna"
Agent calls: remember({ fact: "User's dog is named Luna", category: "pets" })recall — Search memory by query
User: "What's my dog's name?"
Agent calls: recall({ query: "dog name" })
→ Returns: "User's dog is named Luna"forget — Delete facts matching a pattern
User: "Forget everything about my old address"
Agent calls: forget({ query: "address" })Auto-extraction
When autoExtract is enabled, the AutoExtractMiddleware runs after each conversation turn and automatically extracts entities and relationships into the knowledge graph — without the agent needing to call remember explicitly.
memory:
autoExtract: trueLevel 3: Conversation History
Session-based message history stored in the memory adapter (SQLite or Postgres). Each user gets their own session per channel.
Compaction
When the conversation history grows too long, automatic compaction summarizes older messages to stay within context limits:
memory:
compaction:
threshold: 50When a session exceeds threshold messages, the gateway triggers compaction:
- Older messages are summarized into a single summary message
- The most recent messages are kept intact
- The summary replaces the old messages in the session
Full Configuration
memory:
adapter: sqlite # sqlite | postgres
path: ~/.cogitator/memory.db # path for sqlite
knowledgeGraph: true # enable knowledge graph + memory tools
autoExtract: true # auto-extract entities from conversations
compaction:
threshold: 50 # messages before compaction triggersProgrammatic Setup
If you're not using RuntimeBuilder, you can set up memory manually:
import { SQLiteAdapter, SQLiteGraphAdapter, CoreFactsStore } from '@cogitator-ai/memory';
import { createMemoryTools } from '@cogitator-ai/core';
const memory = new SQLiteAdapter({ provider: 'sqlite', path: './memory.db' });
await memory.connect();
const graph = new SQLiteGraphAdapter({ path: './memory.db' });
await graph.initialize();
const coreFacts = new CoreFactsStore({ path: './memory.db' });
await coreFacts.initialize();
const memoryTools = createMemoryTools({
graphAdapter: graph,
coreFacts,
agentId: 'jarvis',
});
const agent = new Agent({
name: 'jarvis',
model: 'google/gemini-2.5-flash',
tools: [...memoryTools],
instructions: 'You are a helpful assistant with persistent memory.',
});