Total Recall
by BAS-More
README.md
<p align="center">
<img src="https://img.shields.io/badge/MCP-Compatible-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6bTAgMThjLTQuNDIgMC04LTMuNTgtOC04czMuNTgtOCA4LTggOCAzLjU4IDggOC0zLjU4IDgtOCA4eiIvPjwvc3ZnPg==" alt="MCP Compatible">
<img src="https://img.shields.io/badge/Tools-26-green?style=for-the-badge" alt="26 Tools">
<img src="https://img.shields.io/badge/Tests-204%20passing-brightgreen?style=for-the-badge" alt="204 Tests Passing">
<img src="https://img.shields.io/badge/SQLite-WAL%20Mode-orange?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL">
<img src="https://img.shields.io/badge/Node.js-20%2B-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js 20+">
<img src="https://img.shields.io/badge/Chrome%20Extension-Manifest%20v3-yellow?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Chrome Extension">
</p>
<h1 align="center">Total Recall</h1>
<p align="center">
<strong>Portable AI memory — persistent, verified, universal.</strong>
<br>
<em>MCP server + REST API + Chrome Extension. Works everywhere AI does.</em>
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#connection-matrix">Platform Matrix</a> •
<a href="#architecture">Architecture</a> •
<a href="#tools">26 Tools</a> •
<a href="docs/USER-MANUAL.md">Full Manual</a> •
<a href="docs/API-REFERENCE.md">API Reference</a>
</p>
---
## The Problem
AI 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.
**Total Recall fixes this permanently, on every platform.**
## What It Solves
| Problem | Solution |
|:--------|:---------|
| Agent forgets everything between sessions | Permanent knowledge base across 12 categories |
| Agent forgets mid-conversation | Checksummed session state verified every turn |
| Agent repeats past mistakes | Corrections loaded first + failure pattern matching |
| Agent claims things without proof | Verification engine (files, git, claims) |
| Knowledge conflicts go unnoticed | Contradiction detection on every write |
| Context window overflows | Smart budget manager drops low-relevance entries |
| Tasks span multiple sessions | Multi-session task tracking with timelines |
| Claude.ai and ChatGPT have no MCP support | Chrome Extension bridges via REST API |
---
## Connection Matrix
| Platform | Connection Method | Auto-Inject | Auto-Capture |
|:---------|:-----------------|:-----------:|:------------:|
| Claude Desktop | MCP (stdio) | Via tools | Via tools |
| Claude Code | MCP (stdio) | Via tools | Via tools |
| Cursor | MCP (stdio) | Via tools | Via tools |
| VS Code + Continue | MCP (stdio) | Via tools | Via tools |
| claude.ai | Chrome Extension + REST API | Yes | Yes |
| ChatGPT | Chrome Extension + REST API | Yes | Yes |
| Gemini | Chrome Extension + REST API | Yes | Yes |
| Perplexity | Chrome Extension + REST API | Yes | Yes |
| Microsoft Copilot | Chrome Extension + REST API | Yes | Yes |
| Poe | Chrome Extension + REST API | Yes | Yes |
| Mistral AI | Chrome Extension + REST API | Yes | Yes |
| Google AI Studio | Chrome Extension + REST API | Yes | Yes |
| Any HTTP client | REST API directly | Manual | Manual |
---
## Quick Start
### For MCP Clients (Claude Desktop, Cursor, etc.)
```bash
# 1. Clone and install
git clone https://github.com/BAS-More/Total-Recall.git
cd Total-Recall
npm install
# 2. Run setup wizard
node bin/total-recall.js init
# 3. Restart your MCP client
# Total Recall is now active.
```
### For claude.ai / ChatGPT / Gemini (Chrome Extension)
```bash
# 1. Install and set up (same as above)
npm install
node bin/total-recall.js init
# 2. Start the REST API server
npm run api
# Running on http://127.0.0.1:3777
# 3. Install the Chrome extension
# Open chrome://extensions → Enable Developer Mode → Load Unpacked → select extension/
# 4. Visit claude.ai or chatgpt.com
# The extension connects automatically — look for the green dot
```
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ CONNECTION LAYER │
├──────────────────────┬──────────────────────┬───────────────────────┤
│ MCP Clients │ Browser Extension │ HTTP Clients │
│ Claude Desktop │ claude.ai │ curl, scripts, │
│ Claude Code │ ChatGPT │ ChatGPT Actions, │
│ Cursor, VS Code │ Gemini, Perplexity │ mobile apps │
│ Any MCP client │ Copilot, Poe, +more │ │
└──────────┬───────────┴──────────┬───────────┴──────────┬────────────┘
│ stdio (MCP) │ HTTP :3777 │ HTTP :3777
▼ ▼ ▼
┌──────────────────────┐ ┌──────────────────────────────────────────┐
│ Total Recall │ │ Total Recall REST API │
│ MCP Server │ │ (src/api.js) │
│ 26 tools │ │ /health /session/* /remember │
│ (src/index.js) │ │ /recall /context /batch-remember │
│ │ │ /stats /recall/:id │
└──────────┬───────────┘ └──────────────────┬───────────────────────┘
│ │
└─────────────────┬───────────────┘
▼
┌────────────────────────────────────────────────────────────────────┐
│ TOTAL RECALL CORE │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Knowledge Engine Intelligence Layer │
│ ├── 12 categories ├── Relevance scoring (6 factors) │
│ ├── Contradiction detect ├── Trigger-based recall │
│ ├── Confidence + TTL ├── NL query routing │
│ └── Version history └── Context budget management │
│ │
│ Session System Prevention & Verification │
│ ├── State files ├── Correction engine (highest priority) │
│ ├── SHA-256 checksums ├── Failure pattern matching │
│ ├── Quality scoring ├── File + git + claim verification │
│ └── Audit trail └── Intent decomposition │
│ │
│ Scale & Resilience │
│ ├── Multi-session tasks ├── Delegation packages │
│ ├── Dependency graph ├── Predictive pre-loading │
│ ├── Sync queue └── Auto-pruning │
│ └── Cross-agent support │
│ │
├────────────────────────────────────────────────────────────────────┤
│ SQLite (WAL mode) — 11 tables, 17 indexes — better-sqlite3 │
│ │
│ Optional: Supabase cloud sync (Phase 5) │
└────────────────────────────────────────────────────────────────────┘
```
---
## Installation
### Prerequisites
- Node.js 20+ (`node --version`)
- npm (comes with Node.js)
- Git (for verification features)
- Any Chromium browser (for extension: Chrome, Edge, Brave, Arc, Vivaldi)
### Install
```bash
git clone https://github.com/BAS-More/Total-Recall.git
cd Total-Recall
npm install
node bin/total-recall.js init
```
The init wizard creates your machine ID, initializes the database, and offers to patch your Claude Desktop config automatically.
### Connect to Claude Desktop
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"total-recall": {
"command": "node",
"args": ["C:\\path\\to\\Total-Recall\\src\\index.js"]
}
}
}
```
Restart Claude Desktop. Ask it to call `health_check` to verify.
### Connect to Claude Code
```bash
# Add to ~/.claude/.mcp.json (global, all projects)
{
"mcpServers": {
"total-recall": {
"command": "node",
"args": ["/path/to/Total-Recall/src/index.js"]
}
}
}
```
Or add `.mcp.json` to a specific project directory.
### Start the REST API
```bash
npm run api
# Total Recall API running on http://127.0.0.1:3777
```
The API runs on localhost only. It accepts connections from the Chrome extension and local tools.
### Install the Chrome Extension
1. Open `chrome://extensions` (or `edge://extensions`)
2. Enable **Developer mode** (top-right toggle)
3. Click **Load unpacked**
4. Select the `extension/` directory from this repository
5. Visit any supported AI chat platform — the extension connects automatically
---
## Tools
### 26 Tools Across 9 Categories
<table>
<tr>
<td width="50%" valign="top">
#### Session Management
| Tool | Purpose |
|:-----|:--------|
| `session_start` | Begin conversation, load corrections + rules |
| `session_state_read` | Refresh mid-conversation memory |
| `session_state_write` | Save files, decisions, errors, facts |
| `session_close` | End session with quality score |
#### Knowledge Operations
| Tool | Purpose |
|:-----|:--------|
| `remember` | Store facts, decisions, errors, patterns |
| `recall` | Natural language search with confidence |
| `recall_by_id` | Get specific entry by UUID |
| `recall_by_category` | Load all entries in a category |
| `forget` | Archive outdated knowledge |
#### Corrections
| Tool | Purpose |
|:-----|:--------|
| `correct` | Record user correction (permanent, highest priority) |
</td>
<td width="50%" valign="top">
#### Verification
| Tool | Purpose |
|:-----|:--------|
| `verify_file` | Check file exists + has content + git-tracked |
| `verify_push` | Compare local HEAD vs remote HEAD |
| `verify_claim` | Verify claim against stored decisions |
#### Context & Intelligence
| Tool | Purpose |
|:-----|:--------|
| `load_context` | Smart load with relevance scoring + budget |
| `get_budget` | Check token budget allocation |
#### Tasks & Delegation
| Tool | Purpose |
|:-----|:--------|
| `task_create` | Create multi-session task |
| `task_update` | Update status, blockers, deliverables |
| `task_list` | Filter tasks by project/status |
| `delegate` | Create context package for agent handoff |
#### Dependencies & System
| Tool | Purpose |
|:-----|:--------|
| `add_dependency` | Track component relationships |
| `query_dependencies` | Change impact analysis |
| `remove_dependency` | Remove relationship |
| `health_check` | Full system status |
| `export_knowledge` | Export to JSON for backup |
| `doctor` | Diagnostics and repair |
| `sync` | Cloud sync (Supabase) |
</td>
</tr>
</table>
---
## Knowledge Categories
Total Recall organizes knowledge into **12 categories**, each with specific behavior:
| Category | Loaded | Prunable | Purpose |
|:---------|:------:|:--------:|:--------|
| `correction` | Always | Never | Past mistakes — highest priority |
| `rule` | Always | Never | Permanent behavioral rules |
| `decision` | By relevance | After 90 days | Locked decisions with rationale |
| `error` | By relevance | After 90 days | Failures with root cause + fix |
| `fact` | By relevance | After 90 days | Verified truths about systems |
| `learning` | By relevance | After 90 days | Lessons and best practices |
| `pattern` | By trigger | After 90 days | How things work in codebases |
| `preference` | By trigger | After 90 days | User working style preferences |
| `risk` | By relevance | After 14 days closed | Active project risks |
| `history` | On demand | After 90 days | Historical events and context |
| `task` | Active auto-loaded | After 30 days done | Multi-session task tracking |
| `relationship` | By relevance | After 90 days | Component dependencies |
---
## How Agents Use It
```
Session Start
│
├─► session_start("claude-desktop")
│ Returns: session_id, corrections (always loaded), rules, active tasks
│
▼
Every Turn
│
├─► session_state_read(session_id) — refresh memory of this conversation
│
├─► [Do work: write code, answer questions, make decisions]
│
├─► session_state_write(session_id, {
│ files_created, decisions_made, errors_encountered, key_facts
│ })
│
├─► remember("decision", "Use Railway for hosting", {
│ tags: ["hosting"], triggers: ["deploy"]
│ })
│
▼
Session End
│
├─► session_close(session_id, "Built auth with 15 tests")
│ Returns: quality_score (0-100), grade (A-F)
│
▼
Next Session (hours, days, weeks later)
│
├─► session_start() → corrections + rules loaded automatically
├─► recall("What did we decide about hosting?")
│ Returns: "Use Railway" (confidence: 95%, category: decision)
└─► All context preserved. Zero loss.
```
## How the Chrome Extension Works
```
User types message on claude.ai
│
├─► Extension intercepts (before send)
├─► Calls POST /context with the message
├─► REST API searches knowledge base, ranks by relevance
├─► Extension prepends <total-recall-context> block to message
├─► Message sent to Claude with full memory context
│
AI responds
│
├─► Extension observes the response
├─► Extracts decisions, errors, rules via pattern matching
└─► Calls POST /batch-remember to store them automatically
```
---
## Configuration
### Config File Location
| Platform | Path |
|:---------|:-----|
| Windows | `%APPDATA%\total-recall\config.json` |
| macOS | `~/.config/total-recall/config.json` |
| Linux | `~/.config/total-recall/config.json` |
### Key Settings
```json
{
"machine_id": "auto-generated-uuid",
"machine_name": "My Machine",
"context_budget": {
"total_tokens": 200000,
"conversation_pct": 40,
"knowledge_pct": 30,
"tool_results_pct": 20,
"system_pct": 10
},
"supabase": {
"enabled": false,
"url": "https://YOUR_PROJECT.supabase.co",
"anon_key": "eyJ..."
},
"pruning": {
"archive_after_days": 90,
"never_archive": ["correction", "rule"]
}
}
```
### Config Discovery (5 levels)
1. CLI flag: `--config /path/to/config.json`
2. `.total-recall.json` in current working directory
3. `.total-recall.json` walking up to filesystem root
4. User config: `~/.config/total-recall/config.json`
5. Built-in defaults (works with no config file)
---
## CLI Commands
```bash
node bin/total-recall.js init # First-time setup wizard
node bin/total-recall.js doctor # Health check
node bin/total-recall.js export # Export knowledge to JSON
node bin/total-recall.js version # Show version
node bin/total-recall.js help # All commands
```
---
## Database
11 tables in SQLite with WAL mode for concurrent access:
| Table | Purpose |
|:------|:--------|
| `knowledge` | Core memory store (12 categories, 20+ columns) |
| `knowledge_history` | Version snapshots for rollback |
| `sessions` | Session lifecycle + quality scoring |
| `audit_log` | Immutable audit trail of every write |
| `tasks` | Multi-session task tracking |
| `dependencies` | Component relationship graph |
| `failure_patterns` | Extracted error patterns for prevention |
| `workflow_transitions` | Predictive pre-loading data |
| `sync_log` | Cloud sync queue (Supabase) |
| `machines` | Machine identity registry |
| `config` | Runtime configuration |
---
## Development
```bash
npm test # Run all 204 tests
npm start # Start MCP server (stdio)
npm run api # Start REST API server (port 3777)
node bin/total-recall.js doctor # Health check
```
### Tech Stack
- **Runtime:** Node.js 20+ (ESM modules)
- **Database:** better-sqlite3 (WAL mode, synchronous)
- **MCP Protocol:** `@modelcontextprotocol/sdk` (stdio transport)
- **REST API:** Express 5 + cors + express-rate-limit
- **Validation:** Zod schemas on all tool inputs
- **Testing:** `node:test` (204 tests, 62 suites)
### Project Stats
```
Source: 34 files, ~4,600 LOC
Tests: 14 files, ~2,200 LOC
Tables: 11 with 17 indexes
Tools: 26 (22 functional, 4 stubs)
Layers: 24 across 7 phases
```
---
## Troubleshooting
<details>
<summary><strong>Claude Desktop doesn't show Total Recall tools</strong></summary>
1. Check `claude_desktop_config.json` has the correct absolute path to `src/index.js`
2. Use absolute paths — relative paths won't work
3. Restart Claude Desktop completely (quit from system tray, not just close)
4. Run `node bin/total-recall.js doctor` to verify database health
</details>
<details>
<summary><strong>Chrome extension shows grey dot (offline)</strong></summary>
The REST API is not running. Start it:
```bash
npm run api
```
The dot turns green when connected.
</details>
<details>
<summary><strong>"Cannot find module" error</strong></summary>
```bash
cd /path/to/Total-Recall
npm install
```
</details>
<details>
<summary><strong>Database locked errors</strong></summary>
Total Recall uses WAL mode with auto-retry (3 attempts, exponential backoff). If persistent:
1. Check no other process has the database open
2. Run `node bin/total-recall.js doctor`
3. Restart the MCP server
</details>
<details>
<summary><strong>How to reset everything</strong></summary>
```bash
# Windows
del "%APPDATA%\total-recall\data.db"
rmdir /s "%APPDATA%\total-recall\sessions"
node bin/total-recall.js init
# macOS/Linux
rm ~/.config/total-recall/data.db
rm -rf ~/.config/total-recall/sessions
node bin/total-recall.js init
```
</details>
---
## Documentation
| Document | Description |
|:---------|:------------|
| [User Manual](docs/USER-MANUAL.md) | Complete guide — installation, tools, config, troubleshooting |
| [Agent Guide](docs/AGENT-GUIDE.md) | Instructions for AI agents using Total Recall |
| [API Reference](docs/API-REFERENCE.md) | Full REST API documentation with curl examples |
| [Activation Guide](docs/ACTIVATION-GUIDE.md) | One-page quick-start for all platforms |
---
## License
MIT License. Created by **Avi Bendetsky / [BAS & More](https://github.com/BAS-More)**.
---
<p align="center">
<strong>Install once. Remember everything. Forever.</strong>
<br><br>
<a href="#quick-start">Get Started</a> •
<a href="docs/USER-MANUAL.md">Read the Manual</a> •
<a href="https://github.com/BAS-More/Total-Recall/issues">Report Issues</a>
</p>