Overview

Memento is built on a simple, local-first architecture. All data lives in a single SQLite database file on your machine. No server required for local use.

┌─────────────────────────────────────────────┐
│  AI Agent (Claude/Cursor/OpenCode)          │
│                                             │
│  mem_save()  mem_search()  mem_update()     │
└──────────────┬──────────────────────────────┘
               │ MCP Protocol
               ▼
┌─────────────────────────────────────────────┐
│  MCP Server (memento-mcp)                   │
│                                             │
│  16 tools for memory operations             │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│  Core Engine (bun:sqlite)                   │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐ │
│  │sessions  │  │observ.   │  │journal    │ │
│  └──────────┘  └──────────┘  └───────────┘ │
│  ┌──────────────────────────────────────┐   │
│  │ FTS5 Virtual Tables                  │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Database Schema

Memento uses 6 core tables:

Table	Purpose
sessions	Groups observations by conversation
observations	Core data — decisions, bugs, discoveries
prompts	Saved prompt templates
projects	Project-scoped memory
journal	Immutable append-only entries
journal_tags	Tags for journal entries

Observations

Observations are the central concept. Each has:

• type: One of 10 types: decision, bug, discovery, note, summary, learning, pattern, architecture, config, preference
• content: Structured text (What/Why/Where/Learned format)
• topic_key: Stable key for grouping (e.g., architecture/auth-model)
• project_id: Scope to a project
• scope: project or personal

Full-Text Search (FTS5)

Memento uses SQLite FTS5 for fast full-text search across all observations and journal entries.

-- Observations search
SELECT * FROM observations_fts WHERE observations_fts MATCH ? ORDER BY rank;

-- Journal search
SELECT * FROM journal_fts WHERE journal_fts MATCH ? ORDER BY rank;

The FTS5 tables are standalone mode (no content=), synced at the application level for maximum portability.

Storage

• Engine: bun:sqlite with raw SQL (no ORM)
• PRAGMAs: WAL mode, foreign_keys ON, busy_timeout 5000ms
• Database file: ~/.memento/memento.db (configurable)

Session Model

Sessions group observations by conversation. When an AI agent starts a conversation, it creates a session. At the end, it generates a session summary.

session_start()
  ├── mem_save() × N
  ├── mem_search() × M
  ├── mem_update() × K
  └── mem_session_summary()

Journal

The journal is an immutable, append-only log. Entries cannot be edited or deleted. Use supersedes to correct previous entries without breaking the audit trail.