Memory

Three-layer persistent memory: SOUL.md persona, markdown notes, and SQLite fact store

Overview

MeepaGateway agents wake up fresh each session — no conversation history carries over automatically. Memory bridges the gap. There are three layers, each serving a different purpose:

Layer	File	Tools
Fact store	memory.db (SQLite + FTS5)	memory_store, memory_search, memory_delete
Long-term notes	MEMORY.md	memory_note, memory_read
User profile	USER.md	memory_note, memory_read

The agent’s persona lives separately in SOUL.md, managed by the soul tools.

All files live in the agent workspace at ~/.meepagateway/agents/{agent_id}/.

---

Agent Workspace Layout

~/.meepagateway/agents/{agent_id}/
  SOUL.md        # Agent persona and instructions
  MEMORY.md      # Curated long-term notes (written by the agent)
  USER.md        # User profile (written by the agent)
  memory.db      # SQLite fact store with FTS5 full-text search
  skills/        # Agent-specific skill files
  .mcp.json      # MCP server configuration

At the start of every session the agent is instructed (via the auto-generated AGENTS.md) to read SOUL.md, USER.md, and MEMORY.md before doing anything else.

---

SOUL.md

SOUL.md is the agent’s persistent persona — who it is, how it behaves, and what it knows about itself. It is loaded on every session start and injected as part of the system prompt.

The agent can read and edit it at runtime using soul_read and soul_edit.

Example SOUL.md

You are Meepa, a helpful assistant for the Acme team.

## Personality
- Direct and concise
- Use bullet points for lists
- Prefer code examples over long explanations

## Context
- The team is building a Rust microservices platform
- Primary language is Rust; secondary is TypeScript
- Production runs on Hetzner with Kubernetes

To edit via CLI:

meepagateway agent soul edit meepa

---

MEMORY.md and USER.md

These are plain markdown files the agent writes to itself using memory_note. They persist across sessions.

• MEMORY.md — General long-term notes: project decisions, recurring topics, things to remember
• USER.md — User-specific profile: preferences, name, timezone, communication style

The agent reads them with memory_read, specifying the target file.

Example MEMORY.md

## Project Notes
- Using pgx/v5 for Postgres — not sqlx
- Deploy pipeline: GitHub Actions → Docker → Hetzner

## Recurring Topics
- Alice usually asks about performance — provide benchmarks when relevant

Example USER.md

## Alice
- Prefers concise answers
- Timezone: UTC+1
- Usually asks about backend architecture

---

Fact Store (SQLite)

The fact store holds structured facts with full-text search (FTS5) and optional vector embeddings for semantic similarity.

Schema

CREATE TABLE facts (
    id          TEXT PRIMARY KEY,  -- UUID
    content     TEXT NOT NULL,     -- Fact text
    source      TEXT NOT NULL,     -- e.g. "user", "observation", "conversation"
    embedding   BLOB,              -- Optional float32 vector
    created_at  TEXT NOT NULL,
    last_accessed TEXT NOT NULL
);

-- FTS5 virtual table for full-text search
CREATE VIRTUAL TABLE facts_fts USING fts5(content, content='facts');

Facts are retrieved by:

• Full-text search — FTS5 MATCH query with automatic tokenization
• Vector similarity — cosine similarity against stored embeddings (when embeddings are present)

Compaction

When the fact count exceeds auto_compact_threshold, older facts that haven’t been accessed recently are pruned automatically.

---

Memory Tools

All memory tools are available to the LLM during the agent loop. They are registered automatically — no configuration required.

memory_store

Store a fact in the SQLite fact store.

{
  "content": "Alice prefers responses under 200 words",
  "source": "user"
}

memory_search

Search the fact store by text query using FTS5.

{
  "query": "Alice preferences"
}

Returns a ranked list of matching facts with their IDs, content, source, and timestamps.

memory_delete

Delete a fact by ID.

{
  "id": "uuid-of-fact"
}

memory_note

Append a note to MEMORY.md or USER.md.

{
  "content": "## New Decision\nWe are switching to Bun for frontend tooling.",
  "file": "MEMORY.md"
}

memory_read

Read the full contents of MEMORY.md or USER.md.

{
  "file": "USER.md"
}

---

Soul Tools

soul_read

Read the current SOUL.md content.

{}

soul_edit

Replace the entire SOUL.md content. The agent can use this to update its own persona.

{
  "content": "You are Meepa, updated persona here..."
}

soul_edit replaces the entire file. The agent should call soul_read first, then make targeted edits to the content before writing it back.

---

Configuration

Memory configuration is derived automatically from the agent workspace path. The optional auto_compact_threshold controls when old facts are pruned:

agents:
  - id: meepa
    # Memory lives at ~/.meepagateway/agents/meepa/memory.db by default
    # No explicit memory config needed

Advanced (rarely needed):

agents:
  - id: meepa
    memory:
      auto_compact_threshold: 1000  # Prune when fact count exceeds this

---

CLI Management

# Edit SOUL.md interactively
meepagateway agent soul edit meepa

# View SOUL.md
meepagateway agent soul show meepa

Facts and notes are managed by the agent itself at runtime using its tools, or via the Captain Dashboard.