Mnemopi: Memory System
Relevant source files
The following files were used as context for generating this wiki page:
Mnemopi is a local SQLite-based memory engine designed for Oh My Pi agents. It provides a multi-tiered memory architecture including working memory, episodic memory, and a knowledge graph (triples). The system facilitates long-term information retention through a combination of vector embeddings, full-text search (FTS), and LLM-driven extraction and consolidation.
Sources: packages/mnemopi/README.md:1-12, packages/mnemopi/src/core/memory.ts:149-165
System Architecture
The Mnemopi architecture is built around the BeamMemory engine and the Mnemopi facade. It manages data isolation through "banks" and supports various scoping strategies such as global or per-project isolation.
Core Components
| Component | Responsibility |
|---|---|
| BeamMemory | The lower-level engine managing working and episodic memory tiers. |
| Mnemopi Facade | High-level API for remember, recall, stats, and sleep workflows. |
| EpisodicGraph | Manages gists, facts (triples), and semantic relationships between memories. |
| BankManager | Handles the creation, deletion, and path resolution of isolated memory banks. |
| AnnotationStore | Manages metadata, source information, and veracity attestation for memories. |
Sources: packages/mnemopi/README.md:5-9, packages/mnemopi/src/core/memory.ts:333-355, packages/mnemopi/src/core/episodic-graph.ts:121-131, packages/mnemopi/src/cli.ts:243-268
Data Flow for Memory Retention
The following diagram illustrates the flow of information when an agent stores a new memory.
Memory Tiers and Storage
Mnemopi utilizes a multi-layered storage strategy to balance immediate context with long-term retrieval.
Working and Episodic Memory
- Working Memory: Stores recent, high-granularity interactions and facts.
- Episodic Memory: Formed through "consolidation" (the
sleepprocess), where working memories are summarized into broader episodes.
Sources: packages/mnemopi/README.md:1-10, packages/mnemopi/src/cli.ts:133-149
Episodic Graph (Knowledge Triples)
The system extracts structured "Facts" in the form of (subject, predicate, object) triples. These are used for graph-based queries and semantic linking.
Retrieval and Recall
Mnemopi supports hybrid retrieval, combining:
- Vector Search: Using embeddings for semantic similarity.
- Full-Text Search (FTS): For keyword-exact matches.
- Graph Querying: Traversing relationships in the Episodic Graph.
Recall Logic Flow
Memory Maintenance (Consolidation)
The sleep (or consolidate) operation is the primary maintenance task. It processes working memory, runs LLM-based summarization, and moves data into the episodic tier.
The Consolidation Pipeline
- Phase 1 (Extraction): Scans recent session threads and generates raw memories and rollout summaries via LLM.
- Phase 2 (Consolidation): Synthesizes raw memories into
MEMORY.mdand structured "skills" within the project's memory root.
Sources: packages/coding-agent/src/memories/index.ts:252-386, packages/mnemopi/src/core/memory.ts:446-448
Configuration and Scoping
The system supports multiple isolation modes defined by mnemopi.scoping:
| Scope | Behavior |
|---|---|
| global | All projects share a single default bank. |
| per-project | Each project has a strictly isolated SQLite database. |
| per-project-tagged | Project-local writes, but recall can optionally span multiple banks. |
Sources: packages/coding-agent/src/mnemopi/backend.ts:303-318, packages/mnemopi/README.md:46-55
Provider Options
Mnemopi can be configured with various LLM and embedding providers:
- Local Embeddings: Via
fastembed(default:BAAI/bge-small-en-v1.5). - Remote APIs: OpenAI-compatible endpoints for both LLM and embeddings.
- Local Models: Optional on-device tiny models for consolidation and extraction.
Sources: packages/mnemopi/README.md:21-44, packages/coding-agent/src/mnemopi/backend.ts:358-400
CLI Usage
The mnemopi command-line tool provides direct access to memory operations.
| Command | Description |
|---|---|
store <content> | Stores a new memory with optional importance and source. |
recall <query> | Searches for relevant memories. |
stats | Displays counts for working, episodic, and triple tiers. |
sleep | Triggers the consolidation process. |
diagnose | Runs integrity checks on the SQLite databases. |
Sources: packages/mnemopi/src/cli.ts:373-388
Conclusion
Mnemopi serves as a sophisticated local brain for agents, moving beyond simple key-value storage into a structured semantic system. By combining graph-based relationship tracking with tiered consolidation, it ensures that agents can maintain long-term context without overwhelming active token windows.