@avi-total-recall/total-recall

v0.3.0

Published

16 days ago

Portable MCP server giving AI agents persistent, verified, cross-session memory

0High
0Medium
0Low

avi770

mcp ai-memory sqlite claude total-recall avi-os

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

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

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:

Check no other process has the database open
Run node bin/total-recall.js doctor
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

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