Persistent three-layer memory system for pulse-null entities. Gives AI agents long-term recall across sessions — curated facts, recent session context, and searchable conversation archives.
LLM coding agents start every session from zero. Built-in memory is typically a single flat file with no session continuity, no short-term vs long-term distinction, and no searchable history. Memory management that depends on the agent remembering to save things is circular.
recall-echo makes the memory lifecycle mechanical. When running as a pulse-null plugin, archival and checkpointing happen automatically. The agent writes to MEMORY.md during sessions. Everything else is handled by the system.
recall-echo provides a three-layer memory model:
┌──────────────────────────────────────────────────────┐
│ MEMORY ARCHITECTURE │
│ │
│ Layer 1: CURATED (always in context) │
│ ┌───────────┐ │
│ │ MEMORY.md │ Facts, preferences, patterns │
│ └───────────┘ Distilled & maintained by the agent │
│ │
│ Layer 2: SHORT-TERM (FIFO rolling window) │
│ ┌───────────────┐ │
│ │ EPHEMERAL.md │ Last N session summaries │
│ └───────────────┘ Appended on archive, auto-trimmed │
│ │
│ Layer 3: LONG-TERM (searched on demand) │
│ ┌─────────────┐ ┌────────────────────────────┐ │
│ │ ARCHIVE.md │───→│ conversations/ │ │
│ └─────────────┘ │ conversation-001.md │ │
│ │ conversation-002.md │ │
│ │ ... │ │
│ └────────────────────────────┘ │
│ YAML frontmatter + markdown │
│ LLM-summarized or algorithmic │
└──────────────────────────────────────────────────────┘
All paths are relative to an entity root directory:
{entity_root}/memory/
├── MEMORY.md # Layer 1 — curated facts (≤200 lines)
├── EPHEMERAL.md # Layer 2 — rolling session window (default 5)
├── ARCHIVE.md # Layer 3 — conversation index
├── conversations/ # Layer 3 — full conversation archives
│ ├── conversation-001.md
│ ├── conversation-002.md
│ └── ...
└── .recall-echo.toml # Optional configuration
recall-echo operates in two modes:
recall-echo is a native pulse-null plugin implementing the Plugin trait from echo-system-types. It fills the required Memory role (exactly one per entity).
- pulse-null calls
archive::archive_session()at session end — creates a conversation archive with LLM-generated summary, updates ARCHIVE.md index, appends to EPHEMERAL.md - pulse-null calls
checkpoint::create_checkpoint()before context compaction — preserves conversation state before details are lost - Health checks report memory directory state (Healthy / Degraded / Down)
- Setup wizard prompts for entity_root during
pulse-null init
use recall_echo::RecallEcho;
// pulse-null creates the plugin via factory:
let plugin = recall_echo::create(&config, &ctx).await?;
// plugin.role() == PluginRole::MemoryFor administration and use outside pulse-null:
recall-echo init [entity_root] # Create memory directory structure
recall-echo status [entity_root] # Health check with dashboard
recall-echo search <query> # Line-level archive search
recall-echo search <query> --ranked # File-ranked relevance search
recall-echo distill [entity_root] # Analyze MEMORY.md, suggest cleanup
recall-echo consume [entity_root] # Output EPHEMERAL.md contentcargo install recall-echo
recall-echo initDownload from GitHub Releases for:
x86_64-unknown-linux-gnuaarch64-unknown-linux-gnux86_64-apple-darwinaarch64-apple-darwin(Apple Silicon)
tar xzf recall-echo-<target>.tar.gz
./recall-echo initgit clone https://github.com/dnacenta/recall-echo.git
cd recall-echo
cargo build --release
./target/release/recall-echo initCreate the memory directory structure under entity_root. Creates memory/ with MEMORY.md, EPHEMERAL.md, ARCHIVE.md, and conversations/. Idempotent — never overwrites existing files.
Health check with a dashboard showing memory usage, ephemeral state, archive count, recent sessions, and health assessment. Color-coded bars show MEMORY.md capacity (green → yellow → red at 75% / 90%).
recall-echo — healthy
MEMORY.md: 142/200 lines (71%)
EPHEMERAL.md: 3 entries
Archives: 23 conversations
Search conversation archives.
recall-echo search "auth middleware" # line-level matches
recall-echo search "auth middleware" -C 3 # with 3 lines of context
recall-echo search "auth middleware" --ranked # ranked by relevance
recall-echo search "auth middleware" --ranked --max-results 5Ranked search scores files by match count, word coverage, and recency.
Analyze MEMORY.md and suggest cleanup. Identifies sections over 30 lines that could be extracted to topic files (e.g., memory/debugging.md) with references left in MEMORY.md.
Output EPHEMERAL.md content wrapped in memory markers. Used by hooks or scripts that need to inject recent session context into an agent's input.
Conversation archives use YAML frontmatter with markdown content:
---
log: 5
date: "2026-03-06T10:30:00Z"
session_id: "abc123"
message_count: 34
duration: "30m"
source: "session"
topics: ["auth", "jwt", "middleware"]
---
## Summary
Summary of the conversation with key outcomes.
**Decisions**: Chose JWT for authentication.
**Action Items**: Implement token refresh endpoint.
### User
(message content)
### Assistant
(message content)
## Tags
**Files**: src/auth.rs, src/middleware.rs
**Tools**: Read, Edit, BashSummaries are LLM-generated when a provider is available (via pulse-null), with silent fallback to algorithmic extraction.
Optional .recall-echo.toml in the memory directory:
[ephemeral]
max_entries = 5 # Rolling window size (1-50, default 5)All settings have sensible defaults. Missing file or invalid values fall back silently.
See CONTRIBUTING.md for branch naming, commit conventions, and workflow.