Skip to main content

Memory Model

AgentOS keeps four kinds of state for an agent: working memory and conversation history (always on, one per GMI), cognitive memory traces (on when a factory builds a manager), the cognitive mechanisms and the observer/reflector pipeline (each behind its own config), and durable storage (on when a brain is attached).

Working memory and history​

Every GMI has an InMemoryWorkingMemory for its mood, user context and task context, and a ConversationHistoryManager that keeps the last 20 messages unless the persona sets conversationContextConfig.maxMessages. Both are per instance and live as long as the GMI.

Cognitive memory​

CognitiveMemoryManager stores traces of five types, episodic, semantic, procedural, prospective and relational (types.ts). Each trace is encoded with a strength and a stability computed from the base strength, the current mood's arousal, its emotional intensity, a HEXACO-weighted attention multiplier and a mood-congruence boost (EncodingModel); retrieval ranks candidates by strength, similarity, recency, emotional congruence, graph activation and importance with the default weights in RetrievalPriorityScorer; each retrieval reinforces the top results (DecayModel). The memory graph is on by default with the knowledge-graph backend, and a pure in-memory graphology backend exists (config.ts).

Three parts are opt-in:

  • The eight cognitive mechanisms (reconsolidation, retrieval-induced forgetting, involuntary recall, feeling-of-knowing, temporal gist, schema encoding, source-confidence decay, emotion regulation) run only when the manager is created with a cognitiveMechanisms config; an empty object turns all eight on with their defaults.
  • The observer and reflector pipeline runs only when observer.llmInvoker and reflector.llmInvoker are configured.
  • Durable storage runs only when a brain is attached; without one, traces live in the vector store and the in-process caches.

Where memory attaches​

On the runtime, a GMI receives a cognitive memory manager only when gmiManagerConfig.cognitiveMemoryFactory builds one for it (GMIManager); no default factory exists, so a runtime without one runs GMIs with history and working memory alone. On the lightweight path, agent() takes a memoryProvider whose getContext is injected before each call and whose observe runs after it; souledAgent() supplies one over a soul workspace's markdown wiki. Products that want the cognitive manager build it themselves with its vector store, graph, embedding manager and traits.

Memory System Overview, Cognitive Memory, Soul Files, Generalized Mind Instances.