MCP 服务器

Total Recall

Portable MCP memory server giving AI agents persistent, verified, cross-session memory. 30 tools, SQLite + cloud sync, Chrome Extension for every AI chat platform. The only JavaScript MCP memory server. Includes behavioral learning engine, semantic search, knowledge scoping, session quality scoring, and web dashboard.

README

<h1 align="center">Total Recall</h1>

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

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

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)

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

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

<details> <summary>Claude Desktop doesn't show Total Recall tools</summary>

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 </details>

<details> <summary>Chrome extension shows grey dot (offline)</summary>

The REST API is not running. Start it:

npm run api

The dot turns green when connected. </details>

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

cd /path/to/Total-Recall
npm install

</details>

<details> <summary>Database locked errors</summary>

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 </details>

<details> <summary>How to reset everything</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