![\"MCP](\"https://img.shields.io/badge/MCP-Compatible-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6bTAgMThjLTQuNDIgMC04LTMuNTgtOC04czMuNTgtOCA4LTggOCAzLjU4IDggOC0zLjU4IDgtOCA4eiIvPjwvc3ZnPg==\"){kind=icon}
\r\n ![\"26](\"https://img.shields.io/badge/Tools-26-green?style=for-the-badge\"){kind=icon}
\r\n ![\"204](\"https://img.shields.io/badge/Tests-204%20passing-brightgreen?style=for-the-badge\"){kind=icon}
\r\n ![\"SQLite](\"https://img.shields.io/badge/SQLite-WAL%20Mode-orange?style=for-the-badge&logo=sqlite&logoColor=white\"){kind=icon}
\r\n ![\"Node.js](\"https://img.shields.io/badge/Node.js-20%2B-339933?style=for-the-badge&logo=nodedotjs&logoColor=white\"){kind=icon}
\r\n ![\"Chrome](\"https://img.shields.io/badge/Chrome%20Extension-Manifest%20v3-yellow?style=for-the-badge&logo=googlechrome&logoColor=white\"){kind=icon}
\r\n\r\n
\r\n Portable AI memory — persistent, verified, universal.\r\n
\r\n MCP server + REST API + Chrome Extension. Works everywhere AI does.\r\n
\r\n Quick Start •\r\n Platform Matrix •\r\n Architecture •\r\n 26 Tools •\r\n Full Manual •\r\n API Reference\r\n
\r\n\r\n---\r\n\r\n## The Problem\r\n\r\nAI agents are **stateless**. Every session starts from zero. Mid-conversation context decays. Knowledge doesn't travel between sessions, machines, or agents — and on platforms like claude.ai or ChatGPT, you can't even connect an MCP server.\r\n\r\n**Total Recall fixes this permanently, on every platform.**\r\n\r\n## What It Solves\r\n\r\n| Problem | Solution |\r\n|:--------|:---------|\r\n| Agent forgets everything between sessions | Permanent knowledge base across 12 categories |\r\n| Agent forgets mid-conversation | Checksummed session state verified every turn |\r\n| Agent repeats past mistakes | Corrections loaded first + failure pattern matching |\r\n| Agent claims things without proof | Verification engine (files, git, claims) |\r\n| Knowledge conflicts go unnoticed | Contradiction detection on every write |\r\n| Context window overflows | Smart budget manager drops low-relevance entries |\r\n| Tasks span multiple sessions | Multi-session task tracking with timelines |\r\n| Claude.ai and ChatGPT have no MCP support | Chrome Extension bridges via REST API |\r\n\r\n---\r\n\r\n## Connection Matrix\r\n\r\n| Platform | Connection Method | Auto-Inject | Auto-Capture |\r\n|:---------|:-----------------|:-----------:|:------------:|\r\n| Claude Desktop | MCP (stdio) | Via tools | Via tools |\r\n| Claude Code | MCP (stdio) | Via tools | Via tools |\r\n| Cursor | MCP (stdio) | Via tools | Via tools |\r\n| VS Code + Continue | MCP (stdio) | Via tools | Via tools |\r\n| claude.ai | Chrome Extension + REST API | Yes | Yes |\r\n| ChatGPT | Chrome Extension + REST API | Yes | Yes |\r\n| Gemini | Chrome Extension + REST API | Yes | Yes |\r\n| Perplexity | Chrome Extension + REST API | Yes | Yes |\r\n| Microsoft Copilot | Chrome Extension + REST API | Yes | Yes |\r\n| Poe | Chrome Extension + REST API | Yes | Yes |\r\n| Mistral AI | Chrome Extension + REST API | Yes | Yes |\r\n| Google AI Studio | Chrome Extension + REST API | Yes | Yes |\r\n| Any HTTP client | REST API directly | Manual | Manual |\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### For MCP Clients (Claude Desktop, Cursor, etc.)\r\n\r\n```bash\r\n# 1. Clone and install\r\ngit clone https://github.com/BAS-More/Total-Recall.git\r\ncd Total-Recall\r\nnpm install\r\n\r\n# 2. Run setup wizard\r\nnode bin/total-recall.js init\r\n\r\n# 3. Restart your MCP client\r\n# Total Recall is now active.\r\n```\r\n\r\n### For claude.ai / ChatGPT / Gemini (Chrome Extension)\r\n\r\n```bash\r\n# 1. Install and set up (same as above)\r\nnpm install\r\nnode bin/total-recall.js init\r\n\r\n# 2. Start the REST API server\r\nnpm run api\r\n# Running on http://127.0.0.1:3777\r\n\r\n# 3. Install the Chrome extension\r\n# Open chrome://extensions → Enable Developer Mode → Load Unpacked → select extension/\r\n\r\n# 4. Visit claude.ai or chatgpt.com\r\n# The extension connects automatically — look for the green dot\r\n```\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────────────┐\r\n│ CONNECTION LAYER │\r\n├──────────────────────┬──────────────────────┬───────────────────────┤\r\n│ MCP Clients │ Browser Extension │ HTTP Clients │\r\n│ Claude Desktop │ claude.ai │ curl, scripts, │\r\n│ Claude Code │ ChatGPT │ ChatGPT Actions, │\r\n│ Cursor, VS Code │ Gemini, Perplexity │ mobile apps │\r\n│ Any MCP client │ Copilot, Poe, +more │ │\r\n└──────────┬───────────┴──────────┬───────────┴──────────┬────────────┘\r\n │ stdio (MCP) │ HTTP :3777 │ HTTP :3777\r\n ▼ ▼ ▼\r\n┌──────────────────────┐ ┌──────────────────────────────────────────┐\r\n│ Total Recall │ │ Total Recall REST API │\r\n│ MCP Server │ │ (src/api.js) │\r\n│ 26 tools │ │ /health /session/* /remember │\r\n│ (src/index.js) │ │ /recall /context /batch-remember │\r\n│ │ │ /stats /recall/:id │\r\n└──────────┬───────────┘ └──────────────────┬───────────────────────┘\r\n │ │\r\n └─────────────────┬───────────────┘\r\n ▼\r\n┌────────────────────────────────────────────────────────────────────┐\r\n│ TOTAL RECALL CORE │\r\n├────────────────────────────────────────────────────────────────────┤\r\n│ │\r\n│ Knowledge Engine Intelligence Layer │\r\n│ ├── 12 categories ├── Relevance scoring (6 factors) │\r\n│ ├── Contradiction detect ├── Trigger-based recall │\r\n│ ├── Confidence + TTL ├── NL query routing │\r\n│ └── Version history └── Context budget management │\r\n│ │\r\n│ Session System Prevention & Verification │\r\n│ ├── State files ├── Correction engine (highest priority) │\r\n│ ├── SHA-256 checksums ├── Failure pattern matching │\r\n│ ├── Quality scoring ├── File + git + claim verification │\r\n│ └── Audit trail └── Intent decomposition │\r\n│ │\r\n│ Scale & Resilience │\r\n│ ├── Multi-session tasks ├── Delegation packages │\r\n│ ├── Dependency graph ├── Predictive pre-loading │\r\n│ ├── Sync queue └── Auto-pruning │\r\n│ └── Cross-agent support │\r\n│ │\r\n├────────────────────────────────────────────────────────────────────┤\r\n│ SQLite (WAL mode) — 11 tables, 17 indexes — better-sqlite3 │\r\n│ │\r\n│ Optional: Supabase cloud sync (Phase 5) │\r\n└────────────────────────────────────────────────────────────────────┘\r\n```\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n\r\n- Node.js 20+ (`node --version`)\r\n- npm (comes with Node.js)\r\n- Git (for verification features)\r\n- Any Chromium browser (for extension: Chrome, Edge, Brave, Arc, Vivaldi)\r\n\r\n### Install\r\n\r\n```bash\r\ngit clone https://github.com/BAS-More/Total-Recall.git\r\ncd Total-Recall\r\nnpm install\r\nnode bin/total-recall.js init\r\n```\r\n\r\nThe init wizard creates your machine ID, initializes the database, and offers to patch your Claude Desktop config automatically.\r\n\r\n### Connect to Claude Desktop\r\n\r\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"total-recall\": {\r\n \"command\": \"node\",\r\n \"args\": [\"C:\\\\path\\\\to\\\\Total-Recall\\\\src\\\\index.js\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\nRestart Claude Desktop. Ask it to call `health_check` to verify.\r\n\r\n### Connect to Claude Code\r\n\r\n```bash\r\n# Add to ~/.claude/.mcp.json (global, all projects)\r\n{\r\n \"mcpServers\": {\r\n \"total-recall\": {\r\n \"command\": \"node\",\r\n \"args\": [\"/path/to/Total-Recall/src/index.js\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\nOr add `.mcp.json` to a specific project directory.\r\n\r\n### Start the REST API\r\n\r\n```bash\r\nnpm run api\r\n# Total Recall API running on http://127.0.0.1:3777\r\n```\r\n\r\nThe API runs on localhost only. It accepts connections from the Chrome extension and local tools.\r\n\r\n### Install the Chrome Extension\r\n\r\n1. Open `chrome://extensions` (or `edge://extensions`)\r\n2. Enable **Developer mode** (top-right toggle)\r\n3. Click **Load unpacked**\r\n4. Select the `extension/` directory from this repository\r\n5. Visit any supported AI chat platform — the extension connects automatically\r\n\r\n---\r\n\r\n## Tools\r\n\r\n### 26 Tools Across 9 Categories\r\n\r\n| \r\n\r\n#### Session Management\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `session_start` | Begin conversation, load corrections + rules |\r\n| `session_state_read` | Refresh mid-conversation memory |\r\n| `session_state_write` | Save files, decisions, errors, facts |\r\n| `session_close` | End session with quality score |\r\n\r\n#### Knowledge Operations\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `remember` | Store facts, decisions, errors, patterns |\r\n| `recall` | Natural language search with confidence |\r\n| `recall_by_id` | Get specific entry by UUID |\r\n| `recall_by_category` | Load all entries in a category |\r\n| `forget` | Archive outdated knowledge |\r\n\r\n#### Corrections\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `correct` | Record user correction (permanent, highest priority) |\r\n\r\n | \r\n\r\n\r\n#### Verification\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `verify_file` | Check file exists + has content + git-tracked |\r\n| `verify_push` | Compare local HEAD vs remote HEAD |\r\n| `verify_claim` | Verify claim against stored decisions |\r\n\r\n#### Context & Intelligence\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `load_context` | Smart load with relevance scoring + budget |\r\n| `get_budget` | Check token budget allocation |\r\n\r\n#### Tasks & Delegation\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `task_create` | Create multi-session task |\r\n| `task_update` | Update status, blockers, deliverables |\r\n| `task_list` | Filter tasks by project/status |\r\n| `delegate` | Create context package for agent handoff |\r\n\r\n#### Dependencies & System\r\n| Tool | Purpose |\r\n|:-----|:--------|\r\n| `add_dependency` | Track component relationships |\r\n| `query_dependencies` | Change impact analysis |\r\n| `remove_dependency` | Remove relationship |\r\n| `health_check` | Full system status |\r\n| `export_knowledge` | Export to JSON for backup |\r\n| `doctor` | Diagnostics and repair |\r\n| `sync` | Cloud sync (Supabase) |\r\n\r\n | \r\n
\r\n Install once. Remember everything. Forever.\r\n
\r\n Get Started •\r\n Read the Manual •\r\n Report Issues\r\n