@avi-total-recall/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

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

• Open chrome://extensions (or edge://extensions)
• Enable Developer mode (top-right toggle)
• Click Load unpacked
• Select the extension/ directory from this repository
• Visit any supported AI chat platform — the extension connects automatically

Tools

26 Tools Across 9 Categories

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)

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)

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)

• CLI flag: --config /path/to/config.json
• .total-recall.json in current working directory
• .total-recall.json walking up to filesystem root
• User config: ~/.config/total-recall/config.json
• 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

Claude Desktop doesn't show Total Recall tools

• Check claude_desktop_config.json has the correct absolute path to src/index.js
• Use absolute paths — relative paths won't work
• Restart Claude Desktop completely (quit from system tray, not just close)
• Run node bin/total-recall.js doctor to verify database health

Chrome extension shows grey dot (offline)

The REST API is not running. Start it:

npm run api

The dot turns green when connected.

"Cannot find module" error

cd /path/to/Total-Recall
npm install

Database locked errors

Total Recall uses WAL mode with auto-retry (3 attempts, exponential backoff). If persistent:

• Check no other process has the database open
• Run node bin/total-recall.js doctor
• Restart the MCP server

How to reset everything

# 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

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.

Install once. Remember everything. Forever.

Get Started • Read the Manual • Report Issues