agent-recall✓ Pass

SKILL.md Content

---
name: agent-recall
description: >-
  Persistent compounding memory for AI agents. 5 default MCP tools: session_start,
  session_end, remember, recall, check. Full surface (18 tools) available with --full flag.
  Two-verb model: inhale (session_start) and exhale (session_end).
  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.
  Optional Supabase backend: when configured via `ar setup supabase`, recall()
  uses pgvector cosine similarity on OpenAI/Voyage embeddings instead of keyword
  search — same API, semantic understanding. Gracefully degrades to local search
  if not configured.
origin: community
version: 3.4.30
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:
  - memory
  - persistence
  - multi-session
  - mcp
  - cross-project
  - feedback-loop
  - intelligent-distance
  - auto-naming
  - knowledge-graph
  - obsidian
trigger:
  - "save"
  - "save session"
  - "/arsave"
  - "/arstart"
  - "remember this"
  - "recall"
  - "what did we do last time"
  - "load context"
  - "start session"
  - "end session"
  - "checkpoint"
  - "保存"
  - "记住"
  - "上次做了什么"
  - "加载上下文"
skip:
  - "don't save"
  - "skip memory"
  - "no need"
  - "不用记"
  - "算了"
---

# AgentRecall v3.4.30 — Usage Guide

AgentRecall is a persistent memory system. Default surface: **5 tools** (two verbs + three essentials). Full surface: 18 tools via `npx agent-recall-mcp --full`. This guide describes how and when to use them.

**Two-verb model:** `session_start` (inhale — load context) and `session_end` (exhale — save and compound). Everything else is available but secondary; most agents never need more than the default 5. See [Automaticity Law](#why-5-default-tools) below.

## Setup

AgentRecall requires the MCP server to be running. If tool calls fail with "unknown tool", the human needs to install it first.

> **Visual setup guide** (all 13 clients, copy-paste prompts): open `warroom/install.html` from the repo, or the [GitHub raw link](https://raw.githubusercontent.com/Goldentrii/AgentRecall-X/main/warroom/install.html) in a browser.

### Installation (human runs once)

**Claude Code:**
```bash
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
```

**Cursor** (`.cursor/mcp.json`):
```json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
```

**VS Code / GitHub Copilot** (`.vscode/mcp.json`):
```json
{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
```

**Codex:**
```bash
codex mcp add agent-recall -- npx -y agent-recall-mcp
```

**Hermes Agent** (`~/.hermes/config.yaml`):
```yaml
mcp_servers:
  agent-recall:
    command: npx
    args: ["-y", "agent-recall-mcp"]
```

**Roo Code** (`.roo/mcp.json`):
```json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
```

**Any MCP-compatible agent:**
```
command: npx
args: ["-y", "agent-recall-mcp"]
transport: stdio
```

---

## Tools

AgentRecall's default surface provides **5 tools**. Start the server with `--full` to enable the complete 18-tool surface.

**Default tools (always available):** `session_start`, `session_end`, `remember`, `recall`, `check`

**Full-mode only (`--full`):** `memory_query`, `check_action`, `register_rule`, `pipeline_open`, `pipeline_close`, `pipeline_list`, `pipeline_current`, `pipeline_show`, `skill_write`, `skill_recall`, `skill_list`, `dashboard_export`, `session_end_reflect`, `project_board`, `project_status`, `digest`, `bootstrap_scan`, `bootstrap_import`

---

### Default tools

### `session_start`

**When:** Beginning of a session, to load prior context.

**What it returns:**
- `project` — detected project name
- `identity` — 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)
  _(Palace = your project's long-term knowledge store, organized into topic rooms like "architecture", "goals", "blockers". Salience = relevance score 0-1 based on recency, access frequency, and connections. Rooms with stale=true haven't been updated in 7+ days.)_
- `cross_project` — insights from other projects matching current context
- `recent` — today/yesterday journal briefs
- `watch_for` — predictive warnings from past correction patterns + decision calibration
- `corrections` — P0 behavioral rules (max 10, always loaded, never expire)
- `resume` — structured re-entry briefing: `last_date`, `last_trajectory`, `sessions_count`

**How to use the response:**
1. Read `identity` to calibrate your tone and approach
2. Read `insights` — these are battle-tested lessons. Follow them.
3. Read `watch_for` — these are patterns where you've been wrong before on this project. Adjust your approach.
4. Read `recent` to understand where the last session left off
5. Present a brief to the human: project name, last session summary, relevant insights

**Example call:**
```
session_start({ project: "auto" })
```

### `remember`

**When:** 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:
- Bug fix / lesson → knowledge store
- Architecture / decision → palace room
- Cross-project pattern → awareness system
- Session activity → journal

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)

### `recall`

**When:** 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_end`

**When:** End of session, after work is done.

**What it does in one call:**
- Writes daily journal entry
- Updates awareness with new insights (merge or add)
- Consolidates decisions/goals into palace rooms
- Archives demoted insights (preserved, not deleted)

**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:**
- 1-3 per session. Quality over quantity.
- Must be reusable. "Fixed a bug" is NOT an insight. "API returns null when session expires — always null-check auth responses" IS an insight.
- `applies_when` keywords determine when this insight surfaces in future sessions across ALL projects.

**Return fields:**
- `journal_written` — boolean, true if journal entry was saved
- `awareness_updated` — boolean, true if any insight was stored
- `palace_consolidated` — boolean, true if palace rooms were updated
- `insights_processed` — number of insights accepted
- `quality_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)

### `check`

**When:** Before executing a complex task where you might misunderstand the human's intent. Also for tracking decision quality over time.

**What it does:**
- Records your understanding of the goal
- Returns `watch_for` — patterns from past corrections on this project
- Returns `similar_past_deltas` — times you misunderstood similar goals before
- After human responds, record the correction for future agents
- Optionally tracks decision trails with prior/posterior/evidence for calibrated judgment

**Two-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`

---

### Full-mode tools (`npx agent-recall-mcp --full`)

> These tools are available when the server is started with `--full`. Most agents never need them — the default 5 tools carry all compounding memory value. Enable `--full` for project narrative tracking (pipeline), procedural rules (skills), status dashboards, context caching, or first-time bootstrap.

### `project_board`

**When:** 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_status`

**When:** 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" })
```

### `bootstrap_scan`

**When:** First time using AgentRecall, or when /arstatus shows an empty board.

**What it does:** Scans your machine for existing projects — git repos, Claude AutoMemory (`~/.claude/projects/`), and CLAUDE.md files. Returns a structured report of what CAN be imported. Read-only, no writes.

**What it scans:**
- `~/Projects/`, `~/work/`, `~/code/`, `~/dev/`, `~/src/`, `~/repos/`, `~/github/` for git repos
- `~/.claude/projects/` for Claude AutoMemory (user profile, project memories, feedback)
- CLAUDE.md files in project roots

**How to use:**
```
bootstrap_scan()
```

**Returns:** `projects` (array of discovered projects with importable items), `global_items` (user profile), `stats` (totals + scan duration)

### `bootstrap_import`

**When:** After reviewing bootstrap_scan results, to import selected projects.

**What it does:** Creates AgentRecall entries for discovered projects — palace rooms, identity.md, knowledge entries from Claude memory, initial journal from git history.

**How to use:**
```
bootstrap_import({
  scan_result: "<JSON from bootstrap_scan>",
  project_slugs: ["my-app", "api-server"],    // optional: import only these
  item_types: ["identity", "architecture"]     // optional: import only these types
})
```

**CLI equivalent:**
```bash
ar bootstrap                    # scan and show what's available
ar bootstrap --dry-run          # preview what would be imported
ar bootstrap --import           # import all new projects
ar bootstrap --import --project my-app  # import one project
```

**What gets imported per project:**
- `identity` — palace identity.md from project name + description + language
- `memory` — Claude AutoMemory .md files → palace knowledge room
- `architecture` — CLAUDE.md content → palace architecture room
- `trajectory` — git log → initial journal entry with recent activity

**Safety:**
- Scan is read-only — never writes to your machine or to AgentRecall
- Import only writes to `~/.agent-recall/`, never modifies source files
- Skips `.env`, credentials, `.pem`, `.key` files — never reads secrets
- Projects already in AgentRecall are skipped (no double-import)

---

## Session Flow

### Start of session
```
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
```

### During work
```
4. remember() when you learn something   → auto-routes to right store
                                           (stores: journal for daily activity, palace rooms for persistent decisions, awareness for cross-project insights)
5. recall() when you need past context   → searches everything
6. check() before major decisions        → verify understanding
```

### End of session
```
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)
```

---

## How Memory Compounds

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
```

---

## Best Practices

1. **Call `session_start` at the beginning.** Insights from past sessions prevent repeated mistakes.
2. **Call `session_end` when done.** If the session produced decisions, insights, or corrections, save them.
3. **Insights should be reusable.** Write them for a future agent who has never seen this project.
4. **Match the human's language.** If they write in Chinese, save in Chinese.
5. **Don't over-save.** 1-3 insights per session. 1-2 `remember` calls during work. More is noise.
6. **Rate your recall results.** Feedback makes future retrievals better.
7. **Use `check` for ambiguous tasks.** 5 seconds of verification beats 30 minutes of wrong work.
8. **Read `watch_for` warnings.** If `session_start` or `check` returns warnings, adjust your approach.
9. **Run bootstrap on first install.** If `/arstatus` shows no projects, `bootstrap_scan` discovers what's already on your machine and imports it in seconds.
10. **Check active_rooms in session_start.** Palace rooms with high salience contain your project's most important decisions and patterns. Rooms marked stale may need updating.

---

## Storage

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 Compatibility

| 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.

---

## Why 5 Default Tools

The Automaticity Law (measured on the live corpus — 44 projects, 221 journals, 81 corrections, 2026-06-12): push channels (`session_start`, `session_end`, correction hooks, ambient recall) showed repeated behavior-changing usage across weeks of real agent sessions. Pull channels — `check_action`, `skill_recall`, `pipeline_*`, `memory_query` — had zero organic calls, including from the agent that built them.

Every extra tool in the default surface burns tool-definition tokens every session for zero behavioral return. The two-verb model (inhale = `session_start`, exhale = `session_end`) carries all compounding memory value. Everything else is available via `--full` for agents and workflows that explicitly need it.

Corollary: wire before write — a primitive without an automatic trigger will not be used.

---

## Security & Privacy

- **Zero network:** No outbound HTTP requests, no telemetry, no analytics, no cloud sync. All operations are local filesystem reads/writes.
- **Zero credentials:** No API keys, tokens, or environment variables required.
- **Scoped filesystem access:** Reads/writes only to `~/.agent-recall/` (configurable via `--root` flag). Does not access files outside this directory unless the agent explicitly passes project-specific paths.
- **No code execution:** The MCP server does not execute arbitrary code, run shell commands, or spawn child processes.
- **Transparent storage:** All data is human-readable markdown and JSON. Inspect it anytime: `ls ~/.agent-recall/` or open it as an Obsidian vault.
- **Open source:** Full source at [github.com/Goldentrii/AgentRecall-X](https://github.com/Goldentrii/AgentRecall-X). MIT license.

License

Declared license: MIT

MIT License

Copyright (c) 2026 Goldentrii

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.