by Goldentrii
AI Session Memory with Think-Execute-Reflect Quality Loops — give your agent a brain that survives every session. Built on the Intelligent Distance principle.
# Add to your Claude Code skills
git clone https://github.com/Goldentrii/AgentRecallNo comments yet. Be the first to share your thoughts!
name: agent-recall description: >- Persistent compounding memory for AI agents. 8 MCP tools: session_start, remember, recall, session_end, check, digest, project_board, project_status. Correction-first memory with decision trail tracking, watch_for warnings, palace rooms with salience scoring, cross-project insight matching, same-day journal merging, ambient recall hooks. Local markdown only. Zero cloud, zero telemetry, Obsidian-compatible. origin: community version: 3.3.28 author: Goldentrii platform: clawhub install: mcp: command: npx args: ["-y", "agent-recall-mcp"] transport: stdio env: {} security: network: none credentials: none filesystem: read-write ~/.agent-recall/ only telemetry: none cloud: none tags:
AgentRecall is a persistent memory system with 8 MCP tools. This guide describes how and when to use them.
AgentRecall requires the MCP server to be running. If tool calls fail with "unknown tool", the human needs to install it first.
Claude Code:
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
Cursor (.cursor/mcp.json):
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
VS Code / GitHub Copilot (.vscode/mcp.json):
{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
Windsurf (~/.codeium/windsurf/mcp_config.json):
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
Codex:
codex mcp add agent-recall -- npx -y agent-recall-mcp
Hermes Agent (~/.hermes/config.yaml):
mcp_servers:
agent-recall:
command: npx
args: ["-y", "agent-recall-mcp"]
Roo Code (.roo/mcp.json):
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
Any MCP-compatible agent:
command: npx
args: ["-y", "agent-recall-mcp"]
transport: stdio
AgentRecall provides these MCP tools:
session_startWhen: Beginning of a session, to load prior context.
What it returns:
project — detected project nameidentity — who the user is (1-2 lines)insights — top 5 awareness insights (title + confirmation count + severity)active_rooms — top 5 palace rooms by salience (with staleness flag + last_updated)cross_project — insights from other projects matching current contextrecent — today/yesterday journal briefswatch_for — predictive warnings from past correction patterns + decision calibrationcorrections — P0 behavioral rules (max 10, always loaded, never expire)resume — structured re-entry briefing: last_date, last_trajectory, sessions_countHow to use the response:
identity to calibrate your tone and approachinsights — these are battle-tested lessons. Follow them.watch_for — these are patterns where you've been wrong before on this project. Adjust your approach.recent to understand where the last session left offExample call:
session_start({ project: "auto" })
rememberWhen: You learn something worth keeping. A decision, a bug fix, an insight, a session note.
What it does: Auto-classifies your content and routes it to the right store:
You do NOT need to decide where it goes. Just describe what to remember.
How to use:
remember({
content: "We decided to use GraphQL instead of REST because the frontend needs flexible queries",
context: "architecture decision" // optional hint, improves routing
})
Returns: routed_to (which store), classification (content type), auto_name (semantic slug generated)
recallWhen: You need to find something from past sessions. A decision, a pattern, a lesson.
What it does: Searches ALL stores at once using Reciprocal Rank Fusion (RRF) — each source (palace, journal, insights) ranks internally, then positions merge so no single source dominates. Journal entries decay fast via Ebbinghaus curve (S=2 days); palace entries are near-permanent (S=9999). Returns ranked results with stable IDs.
How to use:
recall({ query: "authentication design", limit: 5 })
Feedback: After using results, rate them. Ratings use a Bayesian Beta model — the mathematically optimal estimate of true usefulness:
recall({
query: "auth patterns",
feedback: [
{ id: "abc123", useful: true }, // Beta(2,1) → ×1.33 next time
{ id: "def456", useful: false } // Beta(1,2) → ×0.67 next time
]
})
Feedback is query-aware — rating something "useless" for one query doesn't penalize it for unrelated queries.
session_endWhen: End of session, after work is done.
What it does in one call:
How to use:
session_end({
summary: "Built auth module with JWT refresh rotation. Fixed CORS bug.",
insights: [
{
title: "JWT refresh tokens need httpOnly cookies — localStorage is vulnerable",
evidence: "XSS attack vector discovered during security review",
applies_when: ["auth", "jwt", "security", "cookies"],
severity: "critical"
}
],
trajectory: "Next: add rate limiting to API endpoints"
})
Rules for insights:
applies_when keywords determine when this insight surfaces in future sessions across ALL projects.Return fields:
journal_written — boolean, true if journal entry was savedawareness_updated — boolean, true if any insight was storedpalace_consolidated — boolean, true if palace rooms were updatedinsights_processed — number of insights acceptedquality_warnings — advisory warnings if insights are too short, lack evidence, or use event-verb phrasing (never blocks saves)card — formatted save summary (box-drawing card)merge_suggestions — array of similar recent entries (optional)checkWhen: Before executing a complex task where you might misunderstand the human's intent. Also for tracking decision quality over time.
What it does:
watch_for — patterns from past corrections on this projectsimilar_past_deltas — times you misunderstood similar goals beforeTwo-call pattern (correction tracking):
Call 1 — before work:
check({
goal: "Build REST API for user management",
confidence: "medium",
assumptions: ["User wants REST, not GraphQL", "CRUD endpoints", "PostgreSQL backend"]
})
Read the watch_for response. If it says "You've been corrected on API style 3 times", ASK the human before proceeding.
Call 2 — after human corrects (if they do):
check({
goal: "Build REST API for user management",
confidence: "high",
human_correction: "Actually wants GraphQL, not REST",
delta: "API style preference — assumed REST, human prefers GraphQL"
})
This feeds the predictive system. Future agents on this project will get warnings.
Decision trail (Bayesian-inspired calibration):
For major decisions, track confidence and outcome to calibrate judgment over time:
check({
goal: "Use GraphQL instead of REST",
confidence: "medium",
prior: 0.7, // initial confidence (0-1)
evidence: [
{ factor: "Frontend needs flexible queries", direction: "supports", weight: 0.2 },
{ factor: "No GraphQL experience on team", direction: "weakens", weight: 0.3 }
],
posterior: 0.55, // updated confidence after evidence
outcome: "rejected" // final result: "confirmed", "rejected", "partial", or free text
})
When outcome is provided, the decision trail is persisted to the palace decisions room. After 3+ closed decisions, session_start surfaces calibration warnings: "Your priors average 0.8 but outcomes average 0.5 — you're overconfident."
Returns: recorded, watch_for, similar_past_deltas, decision_id (when outcome provided), decision_trail_saved, calibration_note
project_boardWhen: Start of a new session when you don't know which project to work on.
What it does: Scans all projects and returns a status board — last activity date, pending work, active blockers. Use this before session_start to pick which project to load.
project_board()
project_statusWhen: Quick check on a specific project's health without loading full context.
What it returns: Last trajectory, active blockers, palace room freshness (stale flag), next steps, summary line. Lighter than session_start — no awareness or cross-project loading.
project_status({ project: "auto" })
1. session_start() → load context, read insights and warnings
2. Present brief to human → "Last session: X. Insights: Y. Ready."
3. check() if task is complex → verify understanding before work
4. remember() when you learn something → auto-routes to right store
5. recall() when you need past context → searches everything
6. check() before major decisions → verify understanding
7. check() with corrections if any → record what human corrected
8. session_end() → save journal + insights + consolidation
9. Done — all data saved locally (only push to git if user explicitly asks)
Each layer feeds the next. The system gets better the more you use it.
SAVE: remember("JWT needs httpOnly cookies")
→ Auto-named: "lesson-jwt-httponly-cookies-security"
→ Indexed in palace + insights
→ Auto-linked to "architecture" room (keyword overlap)
→ Salience scored: recency(0.30) + access(0.25) + connections(0.20) + ...
RECALL: recall("cookie security") — 3 sessions later, different project
→ Finds the JWT insight via keyword match + graph edge traversal
→ Agent rates it useful → feedback boosts future ranking
→ Next recall on similar query → this result surfaces higher
COMPOUND: After 10 sessions
→ 200-line awareness contains cross-validated insights
→ watch_for warns about past mistakes before they repeat
→ Corrections auto-promote to awareness at 3+ occurrences
→ Graph connects related memories across rooms automatically
session_start at the beginning. Insights from past sessions prevent repeated mistakes.session_end when done. If the session produced decisions, insights, or corrections, save them.remember calls during work. More is noise.check for ambiguous tasks. 5 seconds of verification beats 30 minutes of wrong work.watch_for warnings. If session_start or check returns warnings, adjust your approach.All data is local markdown + JSON at ~/.agent-recall/. No cloud, no telemetry, no API keys.
~/.agent-recall/
awareness.md # 200-line compounding document (global)
awareness-state.json # Structured awareness data
awareness-archive.json # Demoted insights (preserved, not deleted)
insights-index.json # Cross-project insight matching
feedback-log.json # Retrieval quality ratings
projects/<name>/
journal/YYYY-MM-DD.md # Daily journals (legacy)
journal/YYYY-MM-DD--arsave--NL--slug.md # Smart-named journals (auto-save)
palace/rooms/<room>/ # Persistent knowledge rooms
palace/rooms/decisions/ # Decision trail records (prior/posterior/outcome)
palace/identity.md # Project intention + goals
palace/graph.json # Memory connection edges
alignment-log.json # Correction history for watch_for
digest/ # Pre-digested context summaries
Obsidian-compatible. Open palace/ as a vault to see the knowledge graph.
| Platform | How to install |
|----------|---------------|
| Claude Code | claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp |
| Cursor | .cursor/mcp.json |
| VS Code / Copilot | .vscode/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Codex | codex mcp add agent-recall -- npx -y agent-recall-mcp |
| Hermes Agent | ~/.hermes/config.yaml under mcp_servers: |
| Roo Code | .roo/mcp.json |
| Claude Desktop | claude_desktop_config.json |
| Gemini CLI | MCP server config |
| OpenCode | MCP server config |
| Any MCP client | command: npx, args: ["-y", "agent-recall-mcp"], transport: stdio |
All platforms use the same tools. No platform-specific behavior.
~/.agent-recall/ (configurable via --root flag). Does not access files outside this directory unless the agent explicitly passes project-specific paths.ls ~/.agent-recall/ or open it as an Obsidian vault./arstatus, /arsave, /arstart, and /arsaveall[!TIP] New to AgentRecall? Read the → Command Reference — full instructions, all example outputs, installation, and troubleshooting in one place.
[!IMPORTANT] Run
/arstatusat the start of every session. It shows all your projects, what's pending, what's blocked, and lets you pick what to work on — by number, not by remembering project names. Without it, a fresh agent has no idea where to begin.
| Command | When | What it does |
|---------|------|-------------|
| ⭐ /arstatus | Every session — run this first | Status board across ALL projects: pending work, blockers, numbered pick list. The true cold start. |
| /arstart | After picking a project | Load deep context for one project: palace rooms, corrections, task-specific recall |
| /arsave | End of session | Write journal + consolidate to palace + update awareness |
| /arsaveall | End of day (multi-session) | Batch save all parallel sessions at once — scan, merge, deduplicate, done |
The session flow: /arstatus → pick a number → /arstart <project> → work → /arsave.
Running 5 agents in parallel? Don't /arsave five times. Type /arsaveall once — it scans all of today's sessions across all projects, merges them into consolidated journals, deduplicates insights, and updates awareness in one shot. Each session writes to its own file (session-ID scoped), so no conflicts, no data loss, no matter how many windows you have open.
Type /arstatus → see everything in flight across all projects, pick by number:
──────────────────────────────────────────────────────────────
AgentRecall Status Board 2026-04-21 5 projects
──────────────────────────────────────────────────────────────
1 ⚠ novada-site 2026-04-21 BLOCKED
Blocked: .env.local missing — Phase 1 cannot proceed
2 ● novada-mcp 2026-04-21
Next: fix novada_search POST /request → publish v0.8.0
3 ● prismma-scraper 2026-04-17
Next: UI upgrade Option A — light mode + 3D visuals
4 ✓ AgentRecall 2026-04-21 complete
Collecting real production data
──────────────────────────────────────────────────────────────
Enter a number, or:
N New project (with memory — agent knows your full history)
X New project (clean slate — no prior context, pure objectivity)
──────────────────────────────────────────────────────────────
Type /arsave → the system saves everything and renders a card with exact file paths and counts:
──────────────────────────────────────────────────────────────
AgentRecall ✓ Saved my-project 2026-04-20 #12
──────────────────────────────────────────────────────────────
Journal ~/.agent-recall/projects/my-project/journal/
└─ 2026-04-20--arsave--15L--review-feedback.md [written]
Awareness 2 insights added (8 total)
Palace ~/.agent-recall/projects/my-project/palace/
├─ rooms/Architecture [updated]
└─ rooms/Goals [updated]
Corrections 3 stored (always loaded at session start)
⚡ Similar entries found — consider merging:
2026-04-19 (review, feedback, architecture)
──────────────────────────────────────────────────────────────
Type /arstart → loads all context from memory in one shot:
──────────────────────────────────────────────────────────────
AgentRecall ↻ Loaded my-project 2026-04-21
──────────────────────────────────────────────────────────────
Project my-project — SaaS platform for AI agents
Last session 2026-04-20 — review + feedback loop shipped
Insights (top 3):
[5×] Server-rendered cards beat agent templates
[3×] Per-message dedup beats per-session dedup
[2×] Stemming + synonyms improve keyword recall
⚠ Past corrections — watch out:
- "No dark backgrounds" (corrected 3×)
- "Use bb-browser, not Playwright" (corrected 2×)
Cross-project: 2 related insights from novada-mcp
──────────────────────────────────────────────────────────────
Type /arsaveall → batch-saves all parallel sessions at once:
──────────────────────────────────────────────────────────────
AgentRecall ✓ Batch Saved 2026-04-20
──────────────────────────────────────────────────────────────
Sessions scanned 5
Projects saved my-project, novada-mcp, prismma-scraper
Insights merged 4 (deduplicated from 7)
Corrections 2 new (auto-captured via hooks)
──────────────────────────────────────────────────────────────
The cards are rendered server-side — computed from actual operation results, not agent interpretation. What you see is always accurate.
# Install commands (one-time, Claude Code only)
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/arstatus.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstatus.md
curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
curl -o ~/.claude/commands/arsaveall.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/