Memory & AlgoChat
Merlin remembers what it has done and can preview agent-to-agent messaging over Algorand. Memory is part of the day-to-day product surface. AlgoChat is an advanced preview and a 1.1+ direction; it is not a Merlin 1.0 end-user requirement.
Memory
Memory is one of Merlin's core identity pieces: keyed, durable context about users, projects, conversations, decisions, feedback, releases, and benchmark findings. RAG may eventually help Merlin retrieve relevant documents; memory is where Merlin stores intentional context.
At task start, Merlin queries memory with the task description and injects any matches as context. At task end, it writes a one-line ephemeral summary keyed by the task text. This gives the agent continuity across sessions without manual context management.
Why Memory Matters
Without memory, every session starts cold. The agent does not know what it did yesterday, what approaches failed, or what conventions you have established. Memory turns a stateless tool into a collaborator that learns from its own history.
Keyed Context
Memories should use short, predictable slug keys. Useful families:
| Key family | Example | Use |
|---|---|---|
user-* | user-leif-1 | User facts and preferences |
project-* | project-merlin-desktop-1 | Project conventions and roadmap state |
conversation-* | conversation-current-summary-1 | Thread/session summaries |
decision-* | decision-app-first-1 | Explicit choices the team made |
feedback-* | feedback-desktop-cyan-buttons-1 | User feedback to preserve |
benchmark-* | benchmark-openai-o3-mini-1 | Model/provider findings |
release-* | release-0.4.7-1 | Release readiness and blockers |
agent-* | agent-codex-workflow-1 | Agent workflow lessons |
Tiers
| Tier | Storage | Mutability | Lifetime | Use |
|---|---|---|---|---|
| Ephemeral | SQLite | Read/write | TTL-bounded (default 7 days) | Per-task summaries, recent state, scratch notes |
| Mutable | ARC-69 ASA on Algorand | Updateable | Until explicitly deleted | Long-lived knowledge: preferences, project facts, architectural decisions |
| Permanent | Algorand transaction | Immutable | Forever | Decisions, milestones, audit trail |
Merlin currently writes everything as ephemeral. The tier-selection
heuristic (when to promote a memory to mutable or permanent) is a
future sprint.
Recall
use merlin_core::memory;
let entries = memory::recall("parser refactor", &config.memory);
let context = memory::format_context(&entries);recall shells out to fledge plugins run memory-recall. The plugin
supports three recall modes:
| Mode | Use |
|---|---|
--key user-leif-1 | Exact lookup. Fastest and most reliable when the key is known. |
--prefix user-leif | Key-family lookup. Returns memories whose keys start with the prefix. |
--query "parser refactor" | Broad content search when the key family is unknown. |
Precedence is deterministic when multiple args are present: key, then
prefix, then query. The plugin does the actual lookup; merlin-core
only formats results.
Search from the REPL
> /memory parser refactor
task-add error handling to the parser [ephemeral] -- Added Result returns and three error variants...AlgoChat
AlgoChat is encrypted messaging over Algorand. For the app-first Merlin
1.0 milestone, AlgoChat is a preview. The Rust-native algochat-rs
plugin is useful for identity, discovery, contacts, encryption, and
receive/decrypt experiments, but Rust-native transaction signing and
submission remain 1.1+ work.
merlin --listen| Setting | Default | Description |
|---|---|---|
network | "localnet" | Only localnet supported in v0.1; mainnet/testnet are non-goals |
auto_respond | true | When false, incoming messages are logged but not run |
Inspecting Contacts
> /contacts
alice -- ABCD1234...
bob -- WXYZ5678...Requires fledge-plugin-algochat to be installed. If it isn't, you'll
see "No contacts found. Is AlgoChat plugin installed?".