agent-recall-mcp 2.2.2 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-recall-mcp",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Persistent agent memory and alignment detection via MCP — session state, contradiction nudging, and cross-session intelligence for any AI agent",
   "type": "module",
   "main": "dist/index.js",
@@ -60,5 +60,6 @@
   },
   "engines": {
     "node": ">=18.0.0"
-  }
+  },
+  "readme": "# agent-recall-mcp\n\n> Persistent memory for AI agents. Session state that survives restarts, handoffs, and cold starts.\n\n[![npm](https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square)](https://www.npmjs.com/package/agent-recall-mcp)\n[![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)](https://github.com/Goldentrii/AgentRecall/blob/main/LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-9_tools-orange?style=flat-square)](#tools)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square)](#requirements)\n\n**agent-recall-mcp** is an MCP server that gives any AI agent persistent session memory, alignment detection, and cross-session intelligence. Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop, and any MCP-compatible client.\n\n**Zero cloud. Zero telemetry. All data stays on your machine.**\n\n---\n\n## Why AgentRecall?\n\n| Problem | How AgentRecall solves it |\n|---------|--------------------------|\n| Agent forgets everything between sessions | Three-layer memory persists state across sessions |\n| Cold-start costs 2,000-5,000 tokens of context | Agent reads structured journal in ~200 tokens |\n| Human says one thing, agent builds another | Alignment checks measure the understanding gap |\n| Human contradicts a past decision unknowingly | Nudge protocol surfaces the contradiction |\n| Multi-agent handoff loses context | Machine-readable state transfers cleanly between agents |\n\n---\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add agent-recall -- npx -y agent-recall-mcp\n```\n\n### Cursor\n\n`.cursor/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"agent-recall\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-recall-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\n`.vscode/mcp.json`:\n```json\n{\n  \"servers\": {\n    \"agent-recall\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-recall-mcp\"]\n    }\n  }\n}\n```\n\n### Windsurf / Claude Desktop / Other MCP Clients\n\nAdd as an MCP server with command: `npx -y agent-recall-mcp`\n\n---\n\n## Tools\n\n9 MCP tools across three categories:\n\n### Journal (Session Memory)\n\n| Tool | Description |\n|------|-------------|\n| `journal_read` | Read entry by date or `\"latest\"`. Filter by section (`brief`, `qa`, `completed`, `status`, `blockers`, `next`, `decisions`, `reflection`, `files`, `observations`). |\n| `journal_write` | Append to or replace today's journal. Target a specific section or use `replace_all` for full overwrite. |\n| `journal_capture` | Lightweight Layer 1 Q&A capture — one question + answer pair, tagged, timestamped. |\n| `journal_list` | List recent entries for a project (date, title, momentum). |\n| `journal_search` | Full-text search across all journal entries. Filter by section. |\n| `journal_projects` | List all tracked projects on this machine. |\n\n### Alignment (Intelligent Distance)\n\n| Tool | Description |\n|------|-------------|\n| `alignment_check` | Record what the agent understood, its confidence level, assumptions, and any human correction. Measures the understanding gap over time. |\n| `nudge` | Surface a contradiction between the human's current input and a prior decision. Helps the human clarify their own thinking. |\n\n### Synthesis (Cross-Session Intelligence)\n\n| Tool | Description |\n|------|-------------|\n| `context_synthesize` | Generate L3 semantic synthesis — goal evolution, decision history, active blockers, recurring patterns, and contradiction detection across sessions. |\n\n---\n\n## Three-Layer Memory Architecture\n\n```\nL1: Working Memory    [per-turn, ~50 tokens]    \"What happened\"\n    |  synthesized into\nL2: Episodic Memory   [daily journal, ~800 tok]  \"What it means\"\n    |  synthesized into\nL3: Semantic Memory   [cross-session, ~200 tok]  \"What's true across sessions\"\n    (contradiction detection + goal evolution tracking)\n```\n\nEach layer serves a different consumer:\n- **L1** captures raw events as they happen (fast, append-only)\n- **L2** structures the day's work into a navigable journal (agent reads this on cold start)\n- **L3** synthesizes patterns across sessions (detects contradictions, tracks goal drift)\n\n---\n\n## Resources\n\nTwo MCP resources for browsing without tool calls:\n\n| URI Pattern | Description |\n|-------------|-------------|\n| `agent-recall://{project}/index` | Project journal index |\n| `agent-recall://{project}/{date}` | Specific journal entry |\n\n---\n\n## Project Auto-Detection\n\nWhen `project = \"auto\"` (default), the server resolves the project by:\n\n1. `AGENT_RECALL_PROJECT` env var\n2. Git remote origin -> repo name\n3. Git root directory -> basename\n4. `package.json` -> `name` field\n5. Basename of current working directory\n\n---\n\n## Storage\n\n```\n~/.agent-recall/                    (or $AGENT_RECALL_ROOT)\n+-- config.json\n+-- projects/\n    +-- {project-slug}/\n        +-- journal/\n            +-- index.md              <- auto-generated index\n            +-- YYYY-MM-DD.md         <- L2: daily journal\n            +-- YYYY-MM-DD-log.md     <- L1: raw Q&A capture\n            +-- YYYY-MM-DD-alignment.md <- alignment checks + nudges\n```\n\n**Legacy support**: automatically reads existing journals from `~/.claude/projects/*/memory/journal/`. New writes go to `~/.agent-recall/`.\n\n---\n\n## CLI\n\n```bash\nnpx agent-recall-mcp              # Start MCP server (stdio)\nnpx agent-recall-mcp --help       # Show help\nnpx agent-recall-mcp --list-tools # List all 9 tools as JSON\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AGENT_RECALL_ROOT` | `~/.agent-recall` | Storage root directory |\n| `AGENT_RECALL_PROJECT` | (auto-detect) | Override project slug |\n\n---\n\n## Requirements\n\n- Node.js >= 18\n- Dependencies: `@modelcontextprotocol/sdk`, `zod`\n\n---\n\n## Part of AgentRecall\n\nThis MCP server is one component of the [AgentRecall](https://github.com/Goldentrii/AgentRecall) ecosystem:\n\n- **[SKILL.md](https://github.com/Goldentrii/AgentRecall/blob/main/SKILL.md)** — Claude Code skill with Think-Execute-Reflect quality loops\n- **[agent-recall-mcp](https://www.npmjs.com/package/agent-recall-mcp)** — This MCP server (works with any MCP agent)\n- **[Intelligent Distance Protocol](https://github.com/Goldentrii/AgentRecall/blob/main/docs/intelligent-distance-protocol.md)** — The underlying theory\n\n---\n\n## Feedback & Contributing\n\n- Issues & PRs: [github.com/Goldentrii/AgentRecall](https://github.com/Goldentrii/AgentRecall)\n- Email: tongwu0824@gmail.com\n\n---\n\n## License\n\nMIT — [Tongwu](https://github.com/Goldentrii)\n"
 }