# Memory

Local-only agent memory — remember, recall, and forget, all on your machine.

Everything your agent remembers stays on your machine. No cloud sync, no external storage, no data leaving your device. Memory is a set of local files that agents search, update, and reference across sessions.

## Three operations

| Operation | What it does |
| --- | --- |
| **Remember** | Save information as a named entry |
| **Recall** | Search entries by keyword (BM25-ranked) |
| **Forget** | Delete an entry by name |

Agents use these as tools — they decide what to remember based on conversation context.

## Storage

Entries live in `~/.crabtalk/memory/entries/<name>.md`, each with YAML frontmatter:

```
---
name: project-architecture
description: Overview of the microservices layout
---

The project uses three services: auth, api, and worker...
```

BM25 search indexes the name, description, and content of every entry. Better descriptions mean better recall.

## Auto-recall

Before each turn, the agent automatically recalls memories using the first 8 words of your message as a search query. Relevant entries are injected into context — the agent doesn't need to explicitly call recall for recent topics.

## Special files

**`MEMORY.md`** — A curated overview that's injected into every system prompt. Think of it as the agent's working memory — a summary of what matters most.

**`Crab.md`** — The agent's identity and personality. Place it at `~/.crabtalk/Crab.md` to override the default, or in a project root for project-specific identity.

## Configuration

```
[system.memory]
recall_limit = 5          # max results per recall (default: 5)
```

## What's next

- Agents — auto-compaction and how agents use memory
- Configuration — memory settings in config.toml