convez.ai
MCP ServerAutomaçãoIntermediário
Goldentrii

AgentRecall MCP

Goldentrii/AgentRecall-MCP

Memória persistente e corrigida para agentes de IA que aprendem com erros

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que implementa memória persistente e corretiva para agentes de IA, permitindo que aprendam com erros e comprimam contexto entre sessões. Funciona com Claude, Codex, Gemini e qualquer cliente MCP, consolidando conhecimento automaticamente e economizando tokens.

Instalação

$npx convez-ai Goldentrii/AgentRecall-MCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
376
Forks
59
Acompanhando
2
Saúde
57%
Último commit
há 4 dias
Versão
v3.5.3
Issues abertas
26
Contribuidores
1

Casos de uso

  • Agentes que precisam manter contexto entre múltiplas sessões
  • Otimização de consumo de tokens em conversas longas
  • Captura automática de correções para melhorar comportamento futuro

Veredito

Solução técnica robusta para memória em agentes IA, com 5 camadas de memória e algoritmos sofisticados (FSRS-lite, Hopfield). Reduz repetição de erros e contexto desnecessário — ideia bem implementada, mas comunidade ainda pequena.

README

A tradução para o português deste README ainda está na fila.



What & Why · 什么和为什么

AgentRecall is not a memory tool. It's a learning loop.

Memory is the mechanism. Understanding is the goal. Every time you correct your agent — "no, not that version", "put this section first", "ask me before you assume" — that correction is stored, weighted, and recalled next time.

After 10 sessions, your agent doesn't just remember your project. It understands how you think: your priorities, your communication style, your non-negotiables.

AgentRecall 不是记忆工具,是学习闭环。

记忆是机制,理解才是目标。每一次纠正——"不是那个版本"、"先放这一段"、"假设之前先问我"——都会被存储、加权、并在下次召回。

跑 10 次会话之后,agent 不只是记得项目,它理解你的思考方式:优先级、沟通风格、不可妥协的底线。

Five things that make it different:

  • Correction-first. When you say "no, that's wrong", we log a CorrectionRecord with severity, holder, and evidence. After N confirmations across sessions, it auto-promotes to a cross-project insight.
  • Measurable learning loop. Every correction tracks retrieved_count, heeded_count, recurrence_count, precision. The KPI that matters: did the same bug recur after we warned about it?
  • Five memory types. Episodic, semantic, procedural, narrative, correction — mapped to canonical cognitive-psychology taxonomy (Squire 2004, Tulving 1972).
  • Local markdown only. Everything lives in ~/.agent-recall/. Open it in Obsidian. Grep it in the terminal. Version it in git. No cloud, no API keys, no lock-in.
  • Backed by published math. FSRS-lite decay (Ebbinghaus → SuperMemo → FSRS-6), Modern Hopfield retrieval (Ramsauer 2020), RRF fusion (Cormack 2009).

让它不同的五件事:

  • 以纠正为先。 你说"不对"时,我们记下 CorrectionRecord(严重度、归属、证据)。跨会话被确认 N 次后,自动晋升为跨项目的 insight。
  • 可量化的学习闭环。 每条纠正都跟踪 retrieved_count(被召回多少次)、heeded_count(被遵守多少次)、recurrence_count(同样的 bug 是否复发)、precision。唯一重要的 KPI:警告之后同样的 bug 还复发吗?
  • 五种记忆类型。 Episodic、semantic、procedural、narrative、correction —— 对应认知心理学经典分类(Squire 2004、Tulving 1972)。
  • 只用本地 markdown。 一切都在 ~/.agent-recall/。用 Obsidian 打开、用终端 grep、用 git 版本管理。零云、零 API key、零锁定。
  • 基于已发表数学。 FSRS-lite 衰减(Ebbinghaus → SuperMemo → FSRS-6)、Modern Hopfield 检索(Ramsauer 2020)、RRF 融合(Cormack 2009)。

5 Memory Layers · 五层记忆模型

The canonical cognitive-psychology taxonomy mapped to your agent's filesystem · 把认知心理学的经典记忆分类映射到你的文件系统:

All five layers share one canonical naming grammar (<scope>/<type>/[<topic>/]<temporal>--<slug>.md) so any agent — Claude, Codex, future LLM — can compose retrieval paths from intent instead of grepping five conventions. Existing files keep working via a legacy_path virtual-key view. No migration needed.

所有五层共享一个 规范命名语法(<scope>/<type>/[<topic>/]<temporal>--<slug>.md),任何 agent —— Claude、Codex、未来的 LLM —— 都能用意图组合检索路径,不用 grep 五套命名约定。旧文件通过 legacy_path 虚拟键视图继续可用。无需迁移。


The Session Loop · 会话循环

Without /arstatus, a fresh agent has zero orientation. Without /arsave, nothing compounds. These two are the entire loop. 没有 /arstatus,新 agent 完全失去方向。没有 /arsave,什么都不会复合。这两个就是整个闭环。


Already Using Another Memory System? · 已经用过别的?

/arbootstrap scans your machine and imports everything: git repos, Claude AutoMemory (~/.claude/projects/), CLAUDE.md files. Read-only scan, secrets never touched.

/arbootstrap 扫描你的机器并导入所有:git 仓库、Claude AutoMemory(~/.claude/projects/)、CLAUDE.md 文件。只读扫描,secrets 永不触碰。

ar bootstrap            # scan and show what was found
ar bootstrap --import   # import all new projects

Quick Start · 快速开始

MCP Server — for AI agents

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

Skill (Claude Code only) · 仅 Claude Code:

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md

SDK — for JS/TS applications

npm install agent-recall-sdk
import { AgentRecall } from "agent-recall-sdk";
const memory = new AgentRecall({ project: "my-app" });
await memory.capture("What stack?", "Next.js + Postgres");
const ctx = await memory.recall("rate limiting");

CLI — for terminal & CI

npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
npx agent-recall-cli recall "rate limiting"
npx agent-recall-cli palace walk --depth active

MCP Tools

Why only 5 by default? The Automaticity Law (measured on the live corpus, 2026-06-12): push channels — session_start, session_end, correction hooks — show repeated behavior-changing usage. Pull channels (check_action, skill_recall, pipeline_*, memory_query) had zero organic calls in 44 projects over weeks of real use, 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/exhale) carries all compounding value; everything else is opt-in via --full.

为什么默认只有 5 个工具? 自动化定律(基于真实语料库测量,2026-06-12):推送通道(session_start、session_end、纠正 hooks)有持续的行为改变使用记录;拉取通道(check_action、skill_recall、pipeline_*、memory_query)在 44 个项目、数周真实使用中有零次有机调用——包括构建它们的 agent 本身。默认工具面每多一个工具就会在每次会话燃烧 tool-definition tokens,但零行为回报。双动词模型(吸入/呼出)承载了所有复合价值;其余功能通过 --full 按需开启。


How Memory Compounds · 记忆如何复合


What's New in Phase 6 · Phase 6 新增

Phase 6 closes 11 structural gaps the field's research literature flagged. Three improvement loops in one pass — 10-vantage research review → implementation → independent code review → fix-up.

Phase 6 修复了研究文献指出的 11 个结构性缺口。一次完成三个改进循环——10 视角研究审查 → 实现 → 独立代码审查 → 修复。

Full details: see UPDATE-LOG.md Phase 6 section. Visual report: REPORT-2026-05-30.html.

完整细节见 UPDATE-LOG.md Phase 6 章节。可视化报告:REPORT-2026-05-30.html。


SDK API

import { AgentRecall } from "agent-recall-sdk";

const memory = new AgentRecall({ project: "my-app" });

// Write — auto-routes to journal / palace / awareness based on content
await memory.capture("What stack?", "Next.js + Postgres + Drizzle ORM");
await memory.remember("Database: pgvector enabled, RRF fusion for hybrid recall");

// Read — full hybrid search
const results = await memory.recall("rate limiting");
const filescoped = await memory.recall("auth flow", { file_path: "src/auth.ts" });

// Reflect — bundle recent journals + corrections for LLM-side distillation
const bundle = await memory.reflect({ lookback_days: 7 });

// Pipeline — track project narrative
await memory.pipelineOpen({ phase_name: "Discovery", goal: "Map user pain points" });
await memory.pipelineClose({
  what_was_hard: "Conflicting signals from interviews",
  how_solved: "Triangulated against analytics data",
  synthesis: "Behavior > stated preference when they diverge"
});

// Skills — save and recall procedural know-how
await memory.skillWrite({
  name: "Cloudflare 4-step routing",
  topic: "deploy",
  triggers: ["cloudflare", "dns", "ssl"],
  when: "Setting up a new domain with API gateway behind Cloudflare",
  steps: ["Add DNS record", "Enable Proxy", "Add Origin Rule", "Set SSL mode = Full"]
});
const hits = await memory.skillRecall({ intent: "set up cloudflare for new domain" });

CLI

# Capture & recall
ar capture "Question" "Answer"
ar recall "topic"                # hybrid BM25 + vector + Hopfield re-rank
ar recall "topic" --since 7d     # time-filtered

# Sessions
ar status                        # status board across all projects
ar save                          # full session_end (journal + palace + awareness)
ar saveall                       # batch save all parallel sessions

# Bootstrap
ar bootstrap                     # scan and show
ar bootstrap --import            # import all new projects

# Palace navigation
ar palace walk --depth active    # browse active rooms
ar palace read goals             # read a room

# Pipeline
ar pipeline show <project>       # narrative spine
ar pipeline list <project>       # JSON summaries

Run ar --help for the full surface · 完整命令运行 ar --help.


Architecture · 架构

TypeScript monorepo, 4 published packages · TypeScript monorepo,4 个发布包:

packages/
├── core/          # storage + tool logic + helpers (agent-recall-core)
├── mcp-server/    # thin MCP wrappers (agent-recall-mcp)
├── sdk/           # programmatic API for JS/TS apps (agent-recall-sdk)
└── cli/           # `ar` shell command (agent-recall-cli)

Storage layout · 存储布局:

~/.agent-recall/
├── projects/
│   └── <slug>/
│       ├── journal/                  # episodic — per-session entries
│       ├── corrections/              # behavioral rules + outcome KPIs
│       └── palace/
│           ├── rooms/                # semantic — topic-clustered facts
│           ├── skills/               # procedural — IF-THEN rules (NEW)
│           ├── pipeline/             # narrative — project phases (NEW)
│           ├── identity.md
│           └── awareness             # cross-project insights
├── dashboard.html                    # human-readable dashboard
└── dashboard.json                    # agent-readable snapshot (NEW)

Optional Supabase mirror · 可选 Supabase 镜像 — pgvector for semantic recall, RRF fusion when configured. All-local stays the default.


Platform Compatibility · 平台兼容

PlatformMechanismStatus
Claude CodeMCP server + skill + hooks✅ Primary
CursorMCP server✅
WindsurfMCP server✅
VS Code (Copilot)MCP server✅
CodexMCP server✅
Any JS/TS appSDK (agent-recall-sdk)✅
Terminal / CICLI (ar)✅

Docs · 文档


Community · 社区


Contributing · 贡献

PRs welcome. Open an issue first for anything substantive — the design is opinionated and based on published research; we want changes to be grounded the same way.

欢迎 PR。任何实质性改动请先开 issue——这个设计有自己的主张,且基于已发表的研究;我们希望改动也能用同样的方式落地。


License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados