Agent Memory

atlas-memory MCP

Three-tier agent memory system with hybrid RRF retrieval. Episodic, semantic, and procedural tiers with ONNX embeddings and vector + keyword search fusion. Runs on Brain at port 8030. Distinct from neo4j-memory: atlas-memory handles per-session and per-agent memory; neo4j handles the long-term knowledge graph.

MCPport 8030ONNX embeddingsRRF retrievalbrain repoLive

Overview

atlas-memory is the agent-facing memory MCP. Where neo4j-memory stores factual knowledge about the platform, atlas-memory stores what agents have done, learned, and know how to do. It is the working memory of the Grid's cognitive stack.

The server lives in agent-space-co/brain at atlas-memory/ and runs as part of the Brain cognitive stack on ArcHelm.

vs neo4j-memory

neo4j-memory (port 8050) is the knowledge graph — facts about projects, people, decisions. atlas-memory (port 8030) is agent working memory — episodic events, learned semantics, procedural skills. Use both; they serve different purposes.

Memory tiers

Tier 1

Episodic

Short-term events. "What just happened." Individual interactions, observations, tool call results. Auto-consolidates every 5 writes.

Tier 2

Semantic

Facts and concepts. "What I know." Distilled from episodic consolidation or written directly. Persists across sessions.

Tier 3

Procedural

Skills and workflows. "How I do things." Step-by-step procedures, agent-specific patterns, and reusable decision logic.

Retrieval

atlas-memory uses Reciprocal Rank Fusion (RRF) to combine two search signals:

  • Vector search — ONNX embedding similarity (no LLM in the pipeline)
  • Keyword search — BM25-style text match over memory content

RRF merges the ranked lists from both signals into a single result set. This makes retrieval robust: exact-match terms surface via keyword; semantically-related memories surface via vector, even when wording differs.

Connection

# Claude Code MCP config (~/.claude/settings.json or project .mcp.json) { "mcpServers": { "atlas-memory": { "url": "http://localhost:8030/mcp/" } } }

The server runs at http://localhost:8030/mcp/ on ArcHelm (Brain node). It is always running as part of the Brain cognitive stack.

Tools (9)

write_memory(tier, content, tags[])
Write a memory to the specified tier (episodic | semantic | procedural). Tags are optional but improve retrieval precision.
recall_memory(query, tier?)
Retrieve memories using RRF hybrid search. Optionally scope to a specific tier. Returns ranked results with scores.
search_memories(query, limit?)
Full-text + vector search across all tiers. Returns the top N most relevant memories (default 10).
get_memory(id)
Fetch a specific memory by its ID.
update_memory(id, content)
Update the content of an existing memory. Tier and creation timestamp are preserved.
forget_memory(id)
Delete a specific memory by ID.
list_memories(tier?, limit?)
List memories, optionally filtered by tier. Ordered by recency.
consolidate()
Trigger manual consolidation — distills recent episodic memories into semantic tier entries. Normally fires automatically every 5 episodic writes.
memory_stats()
Returns counts per tier, last consolidation timestamp, and index health.

Auto-consolidation

Every 5 episodic writes, atlas-memory automatically runs a consolidation pass. The consolidator groups related episodic memories and distills them into semantic-tier entries — extracting the durable facts from the transient events. The originating episodic memories are retained (not deleted) but marked consolidated.

Manual consolidation is always available via the consolidate() tool — useful before ending a long session to ensure nothing is lost from the episodic buffer.

Wired agents

These Grid agents have atlas-memory in their identity packs and use it for session continuity:

  • Trebek — routing decisions and request history
  • Donut — storytelling context, community voice memory
  • Scout — platform state, agent lifecycle observations

Any agent running via ArcTrigger can be wired to atlas-memory by including atlas-memory in the identity pack's mcpServers array.