Total Recall

Total Recall

Portable AI memory — persistent, verified, universal. MCP server + REST API + Chrome Extension. Works everywhere AI does.

Quick Start • Platform Matrix • Architecture • 26 Tools • Full Manual • API Reference

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

Connection Matrix

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.jsonmacOS: ~/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

Knowledge Categories

Total Recall organizes knowledge into 12 categories, each with specific behavior:

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

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:

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

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

The REST API is not running. Start it:

npm run api

The dot turns green when connected.

cd /path/to/Total-Recall
npm install

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

# 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

Documentation

License

MIT License. Created by Avi Bendetsky / BAS & More.

Install once. Remember everything. Forever. Get Started • Read the Manual • Report Issues