> ## Documentation Index
> Fetch the complete documentation index at: https://meepa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```markdown theme={null}
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:

```bash theme={null}
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

```markdown theme={null}
## 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

```markdown theme={null}
## 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

```sql theme={null}
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.

```json theme={null}
{
  "content": "Alice prefers responses under 200 words",
  "source": "user"
}
```

### `memory_search`

Search the fact store by text query using FTS5.

```json theme={null}
{
  "query": "Alice preferences"
}
```

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

### `memory_delete`

Delete a fact by ID.

```json theme={null}
{
  "id": "uuid-of-fact"
}
```

### `memory_note`

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

```json theme={null}
{
  "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`.

```json theme={null}
{
  "file": "USER.md"
}
```

***

## Soul Tools

### `soul_read`

Read the current `SOUL.md` content.

```json theme={null}
{}
```

### `soul_edit`

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

```json theme={null}
{
  "content": "You are Meepa, updated persona here..."
}
```

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

***

## Configuration

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

```yaml theme={null}
agents:
  - id: meepa
    # Memory lives at ~/.meepagateway/agents/meepa/memory.db by default
    # No explicit memory config needed
```

Advanced (rarely needed):

```yaml theme={null}
agents:
  - id: meepa
    memory:
      auto_compact_threshold: 1000  # Prune when fact count exceeds this
```

***

## CLI Management

```bash theme={null}
# 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.