MemU Architecture

Inside MemU — SQLite, FTS5, auto-capture, significance scoring, and embeddings.

Overview

MemU (Memory Unit) is ArgentOS's built-in persistent memory system. It is a direct SQLite database (via better-sqlite3) with FTS5 full-text search, stored at ~/.argentos/memory.db.

Unlike external memory services, MemU runs entirely locally with no network dependencies. All reads and writes happen through direct SQLite calls in the agent process.

Database Schema

The core memory table contains:

Column	Type	Description
`id`	INTEGER	Primary key
`content`	TEXT	The memory content
`type`	TEXT	Category (fact, preference, event, relationship, etc.)
`significance`	INTEGER	Importance score (1-10)
`entities`	TEXT	JSON array of referenced entities
`emotional_context`	TEXT	Emotional tone or context
`source`	TEXT	Where this memory came from
`created_at`	TEXT	Timestamp of creation
`updated_at`	TEXT	Last update timestamp
`embedding`	BLOB	Vector embedding for semantic search

FTS5 Full-Text Search

MemU uses SQLite's FTS5 extension for fast text search. The FTS5 index covers the content field and enables:

Boolean queries: preference AND open-source
Phrase matching: "infrastructure specs"
Prefix matching: config*
OR queries: telegram OR discord

Search Tips

Single keywords work best for broad recall
Use OR for multi-word queries to improve recall
Strip common stop words for better results
FTS5 handles stemming automatically

Significance Scoring

Every memory has a significance score from 1-10:

Score	Level	Example
1-2	Low	Passing observations
3-4	Medium	Useful context
5-6	High	Important facts and preferences
7-8	Very High	Key personal information, critical decisions
9-10	Critical	Core identity, security-sensitive data

Higher significance memories are prioritized in search results and bootstrap injection.

The agent is trained to automatically store important information without being explicitly asked. When it detects a new fact, preference, event, or relationship in conversation, it calls memory_store proactively.

Embeddings

MemU supports vector embeddings for semantic similarity search. Embeddings are generated when memories are stored and used alongside FTS5 for hybrid search ranking.

Final Score = FTS5_relevance * weight + embedding_similarity * weight + significance_boost

Storage Location

~/.argentos/memory.db      # Main database
~/.argentos/memory.db-wal  # Write-ahead log
~/.argentos/memory.db-shm  # Shared memory

The database is accessed via getMemuStore() in src/memory/memu-store.ts.