# agent-recall [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/Goldentrii/AgentRecall-MCP  
**GitHub Stars:** 375  
**npm Downloads (last month):** 1030  
**Views:** 9  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-recall

## Description
Correction-first agent memory. Precision KPI tracks if agents heed warnings. 5 layers, local-only.

## Tools
Capabilities this server exposes over MCP:

- **session_start** — [ENTRY — call FIRST, before acting] Use when the user asks to start, load, continue, resume, or open memory for a project. Set mode='lite' for a ≤500-token briefing (good for fresh conversations where the agent will pull memory on demand via recall()).
- **session_end** — [ON SAVE/EXIT — YOU must call this; nothing auto-saves] Use when the user asks to save, checkpoint, summarize, end, retain, or persist the current session. Optionally pass close_phase / open_phase to update the project pipeline narrative spine in the same call.
- **remember** — [MID-SESSION WRITE — single fact/decision; saying it is not saving it] Use when the user asks to remember, store, note, or save a specific decision, fact, or insight.
- **recall** — [RETRIEVE — use freely, any time] Use when the user asks to recall, search, find, or look up previous memory, context, or decisions.
- **check** — [MID-SESSION — safe any time; for alignment, before risky decisions] Use when the user asks to validate understanding, verify alignment, or check if their interpretation matches the human's intent. Also call BEFORE a high-risk action — publish, deploy, delete, credential exposure, external send/message, or any other irreversible write — passing `action_description` (one sentence, what you're about to do). Returns matching corrections/rules/insights plus a `verdict`: `blocked` means an authoritative correction OVERRIDES the plan — read it before proceeding. To RECORD a durable human correction, pass `human_correction` as the STRUCTURED object {rule, why, applies_when} — a plain string is only STAGED for later review, never activated.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-recall": {
    "command": "npx",
    "args": ["-y","agent-recall-mcp"]
  }
}
```

## Documentation

## What agent-recall MCP server does

The agent-recall MCP server gives an MCP client a local memory workflow for project sessions. It is designed around a corrections ledger: human corrections can be recorded as structured entries rather than left only in conversation history. Stored information can include facts, decisions, insights, and rules that should affect later work.

The system also tracks correction outcomes. Retrieved corrections accumulate a retrieval count, while later encounters can be marked as either heeded or recurred. This makes behavioral follow-through measurable instead of treating successful retrieval as proof that an agent changed its behavior.

As a 🧠 Knowledge & Memory tool, agent-recall fits work where decisions and correction history need to persist across agent restarts, sessions, and projects. The repository reports local storage and zero cloud use by default.

## How it works

A session normally begins with `session_start`, which loads project context before the agent acts. The `lite` mode returns a shorter briefing of up to 500 tokens for conversations where the agent will retrieve more detail on demand. During work, `recall` searches prior memory, while `remember` writes one fact, decision, or insight when the user explicitly asks for it.

Before a risky or irreversible action, `check` can compare the planned action with stored corrections, rules, and insights. It returns a verdict; `blocked` means an authoritative correction overrides the plan. A durable correction should be supplied as the structured object `{rule, why, applies_when}`. A plain-text correction is staged for later review rather than activated immediately.

`session_end` is the explicit save or exit operation. Nothing is saved automatically through that lifecycle call, and the tool can also update the project’s phase narrative with `close_phase` and `open_phase`.

## Setup and configuration

The agent-recall MCP server can be launched through npm with `npx -y agent-recall-mcp`. Claude Code users can add it with:

```bash
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
```

Other stdio-capable MCP clients can use an entry with `command` set to `npx` and arguments `-y`, `agent-recall-mcp`.

## Tools and capabilities

- `session_start`: load project memory at the beginning of a session.
- `session_end`: save session context and optionally update project phases.
- `remember`: write a specific fact, decision, insight, or correction.
- `recall`: retrieve previous memory, context, or decisions.
- `check`: validate alignment and inspect stored constraints before an action.

## Limitations and notes

The agent-recall MCP server depends on explicit tool use. Agents must call `session_start` before acting and `session_end` when saving or exiting; the material states that nothing is saved automatically. Saying a fact in conversation is not equivalent to writing it with `remember`.

The published measurements also show that the system should not be treated as proof that corrections will always be captured or followed. The supplied results report 35.3% correction-capture recall in one audit, zero of three evidence-grounded heed events after a measurement reset, and zero of four correction-transfer events in an offline benchmark. These figures describe the project’s reported corpus and evaluation state, not a guarantee for another workload.

The repository’s setup examples use a local stdio process.

_Full upstream README: https://allmcps.com/mcp/agent-recall/readme_