Agent Memory

Reeve memory is plain Markdown in the agent workspace. The files are the source of truth — the model only "remembers" what gets written to disk.

Memory Files

Every agent workspace has two memory layers:

~/reeve/
  ├── MEMORY.md              # Long-term memory
  └── memory/
      ├── 2026-03-01.md      # Daily log
      ├── 2026-03-02.md
      └── 2026-03-03.md

At session start, the agent reads today's and yesterday's daily logs. MEMORY.md is loaded in the main (private) session only — never in group contexts.

Writing Memory

Agents write memory in three ways:

1. You ask them to

Tell your agent "remember this" and it writes to the appropriate file. This is the most reliable way to store important information.

2. Automatic memory flush

When a session approaches compaction (context window filling up), Reeve triggers a silent memory flush. The agent writes durable notes to memory/YYYY-MM-DD.md before the context is summarized.

This is controlled by config:

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

3. Agent initiative

Well-configured agents learn to write memory proactively — noting decisions, preferences, and important context without being asked.

Reading Memory

Agents access memory through two tools:

• memory_search — Semantic search across all memory files
• memory_get — Read a specific memory file by path

Semantic Search

Memory search uses vector embeddings to find relevant notes even when wording differs:

Query: "What model does the marketing team prefer?"
→ Finds: "2026-02-15: Marketing decided to use Claude Sonnet for all content generation"

This works because semantic search matches meaning, not just keywords. It also supports hybrid search (vector + BM25 keyword matching) for exact tokens like IDs and code symbols.

Search Configuration

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "local"
      }
    }
  }
}

pnpm approve-builds    # Select node-llama-cpp
pnpm rebuild node-llama-cpp

Hybrid Search

Combine semantic and keyword search for best results:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        }
      }
    }
  }
}

Hybrid search excels at finding both natural language matches and exact tokens (IDs, error strings, code symbols).

Index Storage

Memory embeddings are stored in a per-agent SQLite database:

~/.reeve/memory/<agentId>.sqlite

The index automatically rebuilds when you change the embedding provider, model, or chunking parameters. A file watcher detects memory changes and updates the index in the background.

Session Memory (Experimental)

Optionally index session transcripts for search:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "experimental": { "sessionMemory": true },
        "sources": ["memory", "sessions"]
      }
    }
  }
}

This lets agents search past conversations, not just memory files. Session indexing is opt-in and runs asynchronously.

Best Practices

• Tell agents what to remember — If something is important, say "remember this"
• Review MEMORY.md periodically — Curate it like you would notes; remove outdated info
• Daily logs are disposable — They accumulate and get searched, but old ones don't need maintenance
• Keep memory files Markdown — The system expects .md files; other formats won't be indexed
• Enable semantic search — It's the difference between "grep" and "understanding"

The Three Content Layers

Every Reeve agent maintains memory across three source layers:

1. Session Transcripts

Every conversation is stored in full as a raw transcript. These aren't just logs — they're indexed and searchable. Reeve can surface a decision you made three months ago, a bug that was fixed last week, or a pattern that keeps recurring across your sessions.

How it works: Session files are chunked into conversational exchanges (question + response = one unit), embedded with a language model, and stored in a local semantic index. Searchable within seconds of the conversation ending.

2. Daily Notes

After each working session, Reeve writes a structured daily note (memory/YYYY-MM-DD.md). This is the "what happened today" layer — summarized, organized, and immediately readable by both the agent on its next session and by you.

Daily notes are the reconciliation point for cloud sync: if two sessions write to the same day's note (e.g., you worked in both local and Slack that day), the entries are append-merged — nothing is lost.

3. Long-Term Memory (MEMORY.md)

The curated, durable layer. Decisions that stick, preferences, recurring context, key relationships, product direction. Reeve maintains this file and references it at the start of every session. It's what makes a year-old agent feel like a senior team member rather than a new hire.

This file is yours — you can read it, edit it, and shape it directly.

The Semantic Index

On top of the three content layers sits a unified semantic index. All three layers — transcripts, daily notes, and long-term memory — are chunked and embedded using your configured embedding model (OpenAI, Gemini, or local via Ollama).

When you ask your agent to recall something, or when the agent searches its own memory, it runs a hybrid search: vector similarity (semantic meaning) + full-text BM25 (keyword precision), merged and ranked. The result is accurate recall even when you can't remember the exact words you used.

Per-Agent Memory

Every agent has its own memory workspace. An agent's memory is specialized to its role — your marketing agent accumulates brand voice, competitor notes, and campaign history; your dev agent accumulates codebase context, architectural decisions, and bug patterns.

This specialization is intentional. You don't want your dev agent's memory polluted with campaign data, and vice versa. Each agent develops genuine expertise over time.

The Scope Hierarchy

Memory in Reeve is scoped at three levels, merged at query time:

In single-user local mode, only the agent scope is active. In cloud/team mode, all three scopes are searched and merged using Reciprocal Rank Fusion.

Local ↔ Cloud Sync

Vision: You work locally with your agent in the morning. You pick up the same conversation in Slack from your phone 30 seconds later — full context, no re-explaining.

How it works: When a memory file changes locally, a file watcher triggers a sync to S3 within ~1–5 seconds. When a cloud session starts, it pulls the latest memory state from S3 before the first message. Conflict resolution:

• Daily notes (memory/YYYY-MM-DD.md): append-merge — both versions are preserved
• MEMORY.md and other files: last-writer-wins based on modification time

The sync engine is fully built. Cloud provisioning (S3 bucket, STS credentials endpoint) is in progress.

Shared Agent Memory

Vision: Your whole team works with the same agent. Dev 1 ships a feature; Dev 2 picks up code review with the agent already knowing the full context. A new team member joins; the agent already knows your codebase, your decisions, your preferences.

How it works: When an agent writes a daily summary, it automatically extracts "promotable insights" — decisions, bugs fixed, process changes, config updates — and promotes them to the shared org memory layer. These insights are attributed ([date | user | agent]) and accumulate over time. Any team member's session can query this shared layer.

What gets auto-promoted: Lines containing decision language ("decided," "chose," "going with"), bug language ("fixed," "resolved"), process changes ("migrated," "restructured"), and configuration changes.

The auto-promotion pipeline and shared memory search are built. End-to-end testing with real teams is in progress.

Knowledge Graph Memory

Vision: Reeve doesn't just store what you told it — it understands the relationships between things. "This bug was caused by that dependency change." "That decision affects these three features." "This person owns that project." A graph you can traverse, not just search.

How it works: As sessions are archived, a background process runs entity and relationship extraction using Claude Haiku. Entities are typed (person, project, decision, concept, tool, brand, codebase, bug, feature, config). Relationships use 12 constrained edge types: owns, created, decided, uses, affects, depends_on, part_of, fixed_by, caused_by, blocked_by, related_to, replaced_by.

Connected entity clusters are detected and summarized by community — so instead of retrieving individual facts, Reeve can retrieve a coherent picture of a topic cluster ("everything related to the auth system rewrite").

Under the hood: This runs on the same SQLite file as the rest of memory — entities, relationships, and community summaries are stored as tables and queried alongside the semantic index. No new infrastructure required.

Extraction pipeline, community detection, and graph search are built and merged. Wiring the graph results into the memory_search tool response is in progress.

See the full Memory reference for all configuration options including caching, batch indexing, and SQLite vector acceleration.