Total Recall

<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.)

# 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)

# 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

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

{
  "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

# 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

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

{
  "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

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

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:

npm run api

The dot turns green when connected. </details>

<details> <summary><strong>"Cannot find module" error</strong></summary>

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>

# 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	Complete guide — installation, tools, config, troubleshooting
Agent Guide	Instructions for AI agents using Total Recall
API Reference	Full REST API documentation with curl examples
Activation Guide	One-page quick-start for all platforms

---

License

MIT License. Created by Avi Bendetsky / 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>