guthubrx/rekall

Contents

• TL;DR
• The Problem
• The Solution
• How It Works
• Interface
• What It Automates
• Entry Types
• Sources
• Privacy
• Getting Started
• MCP Server
• Speckit Integration
• Under the Hood (technical)
• Built on Science (research)

TL;DR

The problem: Every developer has solved the same bug twice. Not because they're careless — because humans forget. Research shows Fortune 500 companies lose $31.5 billion annually to knowledge that's never captured.

Our approach: Rekall is a personal knowledge base built on cognitive science research. We studied how human memory actually works — episodic vs semantic memory, spaced repetition, knowledge graphs — and applied it to developer workflows.

What it does: Capture bugs, patterns, decisions, configs as you work. Search by meaning, not just keywords — Rekall uses optional local embeddings (all-MiniLM-L6-v2) combined with full-text search to find relevant entries even when your words don't match exactly. Store rich context (situation, solution, what failed) to disambiguate similar problems later.

Works with your tools: Rekall exposes an MCP server compatible with most AI-powered development tools — Claude Code, Claude Desktop, Cursor, Windsurf, Continue.dev, and any MCP-compatible client. One command (rekall mcp) and your AI consults your knowledge before every fix.

What it automates: Keyword extraction, consolidation scoring, pattern detection, link suggestions, review scheduling (SM-2 spaced repetition). You focus on capturing — Rekall handles the rest.

# Install
uv tool install git+https://github.com/guthubrx/rekall.git

# Capture (interactive mode guides you)
rekall add bug "CORS fails on Safari" --context-interactive

# Search (understands meaning, not just keywords)
rekall search "browser blocking API"

# Connect to AI (one command, works with Claude/Cursor/Windsurf)
rekall mcp

You've already solved this problem.

Three months ago, you spent two hours debugging a cryptic error. You found the fix. You moved on.

Today, the same error appears. You stare at it. It looks familiar. But where was that solution again?

You start from scratch. Another two hours gone.

This happens to every developer. According to research, Fortune 500 companies lose $31.5 billion annually because lessons learned are never captured. Not because people are careless — but because we're human, and humans forget.

What if your AI assistant remembered for you?

Imagine this: you ask Claude or Cursor to fix a bug. Before writing a single line of code, it checks your personal knowledge base:

🔍 Searching your knowledge...

Found 2 relevant entries:

[1] bug: CORS error on Safari (85% match)
    "Add credentials: include and proper Access-Control headers"
    → You solved this 3 months ago

[2] pattern: Cross-origin request handling (72% match)
    "Always test on Safari - it has stricter CORS enforcement"
    → Pattern extracted from 4 similar bugs

Your AI assistant now has context. It knows what worked before. It won't reinvent the wheel — it'll build on your past experience.

That's Rekall.

A second brain that thinks like you do

Key idea: Rekall is built on how human memory actually works — connecting related knowledge, extracting patterns from episodes, and surfacing forgotten information before it fades.

Rekall isn't just a note-taking app. It's built on how human memory actually works:

Your knowledge, connected

When you solve something, related knowledge surfaces automatically. Fixed a timeout bug? Rekall shows you the three other timeout issues you've solved and the retry pattern you extracted from them.

              ┌──────────────┐
              │ Auth Timeout │
              │   (today)    │
              └──────┬───────┘
                     │ similar to...
        ┌────────────┼────────────┐
        ▼            ▼            ▼
  ┌──────────┐ ┌──────────┐ ┌──────────┐
  │ DB #47   │ │ API #52  │ │ Cache #61│
  │ (2 weeks)│ │ (1 month)│ │(3 months)│
  └────┬─────┘ └────┬─────┘ └──────────┘
       └──────┬─────┘
              ▼
     ┌─────────────────┐
     │ PATTERN: Retry  │
     │ with backoff    │
     └─────────────────┘

Events become wisdom

Every bug you fix is an episode — a specific event with context. But patterns emerge. After fixing three similar timeout bugs, Rekall helps you extract the principle: "Always add retry with exponential backoff for external APIs."

Episodes are raw material. Patterns are reusable knowledge.

Forgotten knowledge resurfaces

Rekall tracks what you access and when. Knowledge you haven't touched in months? It'll remind you before it fades completely. Think of it as spaced repetition for your dev brain.

How it works in practice

1. Capture knowledge as you work

After solving something tricky, capture it in 10 seconds:

rekall add bug "CORS fails on Safari" --context-interactive

Rekall asks: What was happening? What fixed it? What keywords should trigger this?

> Situation: Safari blocks requests even with CORS headers set
> Solution: Add credentials: 'include' and explicit Allow-Origin
> Keywords: cors, safari, cross-origin, fetch, credentials

Done. Your future self will thank you.

2. Search by meaning, not just keywords

Can't remember if you called it "CORS" or "cross-origin"? Doesn't matter.

rekall search "browser blocking my API calls"

Rekall understands meaning. It finds relevant entries even when your words don't match exactly.

3. Let your AI assistant use it

Connect Rekall to Claude, Cursor, or any AI that supports MCP:

rekall mcp  # Start the server

Now your AI consults your knowledge before every fix. It cites your past solutions. It suggests saving new ones. Your knowledge compounds over time.

The interface

Why Terminal-First? Rekall's interface is a full-featured Terminal UI (TUI) — and that's by design. Modern development happens everywhere: on your laptop, on remote servers, inside containers, over SSH. A terminal interface means you can access your knowledge base from anywhere without opening a browser or forwarding ports.

Whether you're debugging a production server at 2 AM via SSH, working in a headless VM, or simply prefer the speed and keyboard-driven efficiency of terminal apps — Rekall is right there with you. No GUI dependencies. No context switching. Just your knowledge, one command away.

A web interface is on the roadmap for teams who prefer browser-based workflows.

Terminal UI

rekall  # Launch the visual interface

┌─ Rekall ────────────────────────────────────────────────┐
│     Search: cors safari                                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  [1] bug: CORS fails on Safari              85% ██████  │
│      safari, cors, fetch  •  3 months ago               │
│      "Add credentials: include..."                      │
│                                                         │
│  [2] pattern: Cross-origin handling         72% █████   │
│      architecture  •  1 month ago                       │
│      "Safari has stricter CORS enforcement"             │
│                                                         │
│  [3] reference: MDN CORS guide              68% ████    │
│      docs, mdn  •  6 months ago                         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  [/] Search  [a] Add  [Enter] View  [q] Quit            │
└─────────────────────────────────────────────────────────┘

Command line

rekall add bug "Fix: null pointer in auth" -t auth,null
rekall search "authentication error"
rekall show 01HX7...
rekall link 01HX7 01HY2 --type related
rekall review  # Spaced repetition session

Enhanced CLI Experience

New in 2025: Rekall now includes powerful CLI enhancements for faster workflows and better knowledge exploration.

Graph Visualization

Explore your knowledge graph as ASCII trees to understand relationships and discover connected insights:

rekall graph 01HX7...  # Visualize entry connections

Fix auth bug [bug] ↓2 ↑0
├── [DERIVED_FROM] JWT pattern [pattern] ↓0 ↑1
│   └── [RELATED] Security decision [decision] ↓1 ↑2
└── [SUPERSEDES] Old fix [bug] ↓0 ↑1

Options:

• --depth N — Traversal depth (1-4, default: 2)
• --outgoing — Show only outgoing links
• --incoming — Show only incoming links
• --style compact — ASCII-only rendering

📖 — Complete reference with use cases and examples

Shell Auto-completion

Get instant command and option completion across all shells:

# Install once
rekall --install-completion

# Enjoy instant completion
rekall sea<TAB>    # → rekall search
rekall add <TAB>   # → bug, pattern, decision, pitfall...
rekall graph --d<TAB>  # → --depth

Supported shells: Bash, Zsh, Fish, PowerShell Performance: < 50ms completion time (< 100ms on slow systems)

Command Shortcuts

Speed up your workflow with single-letter shortcuts:

All shortcuts support the same options as full commands.

Interactive Review (TUI)

Start spaced repetition sessions with a visual interface:

rekall review --tui  # Launch interactive review

┌─ Review Session ──────────────────────────────────────────────┐
│  [1/10] Fix Safari CORS bug                                   │
│                                                                │
│  Stability: 12.5d  │  Difficulty: 4.2  │  Recall: 68%         │
│                                                                │
│  Preview: Safari blocks requests even with CORS headers...    │
│                                                                │
│  Rate your recall:                                            │
│  [1] Again (3h)  [2] Hard (1.2d)  [3] Good (3.1d)  [4] Easy...│
└────────────────────────────────────────────────────────────────┘

Keyboard controls:

• 1-4 — Rate recall (Again/Hard/Good/Easy)
• p — Toggle content preview
• s — Skip entry
• q — Quit session

📖 — Complete workflow and FSRS algorithm explanation

What Rekall does for you

Philosophy: You focus on capturing knowledge. Rekall handles everything else.

On every entry you add

• Auto-Context Capture — Automatically extracts conversation history and modified files from your IDE (Claude Code, Cline, etc.) to provide rich context without typing
• Keyword extraction — Analyzes your title and content, suggests relevant keywords
• Context validation — Warns if situation/solution is too vague or generic
• Embedding generation — Creates semantic vectors for intelligent search (if enabled)
• Automatic indexing — Full-text search index updated in real-time

On every search

• Hybrid matching — Combines exact words (FTS5) + meaning (embeddings) + triggers (keywords)
• No configuration — Works out of the box, no tuning needed
• Related entries — Shows linked knowledge automatically

In the background (you do nothing)

• Access tracking — Every view updates frequency and recency stats
• Consolidation scoring — Calculates how "stable" each memory is (60% frequency + 40% freshness)
• Pattern detection — Finds clusters of similar entries, suggests creating a pattern
• Link suggestions — Detects related entries, proposes connections
• Review scheduling — SM-2 algorithm plans optimal review times (spaced repetition)
• Context compression — Stores verbose context at 70-85% smaller size

When you run rekall review

• Loads due entries — Based on SM-2 scheduling, not arbitrary dates
• Adjusts difficulty — Your rating (0-5) updates the ease factor automatically
• Reschedules — Calculates next optimal review date

What can you capture?

Track your sources

Philosophy: Every piece of knowledge came from somewhere. Rekall helps you track where — so you can evaluate reliability, revisit original sources, and see which sources are most valuable to you.

Link entries to their sources

When you capture knowledge, you can attach sources:

# Add a bug with a URL source
rekall add bug "Safari CORS fix" -t cors,safari
# Then link the source URL
rekall source link 01HX7... --url "https://stackoverflow.com/q/12345"

# Or use the TUI: open entry → Add source
rekall

Three source types

Reliability ratings (Admiralty System)

Not all sources are equally trustworthy. Rekall uses a simplified Admiralty System:

Personal score: What matters to you

Each source gets a personal score (0-100) based on:

Score = Usage × Recency × Reliability

- Usage: How often you cite this source
- Recency: When you last used it (decays over time)
- Reliability: A=1.0, B=0.8, C=0.6

Sources you use frequently and recently rank higher — regardless of how "authoritative" they are globally. Your personal experience matters.

Backlinks: See all entries from a source

Click any source to see all entries that reference it:

┌─ Source: stackoverflow.com/questions/* ─────────────────┐
│  Reliability: B  │  Score: 85  │  Used: 12 times        │
├─────────────────────────────────────────────────────────┤
│  Entries citing this source:                            │
│                                                         │
│  [1] bug: CORS fails on Safari                          │
│  [2] bug: Fetch timeout on slow networks                │
│  [3] pattern: Error handling for API calls              │
└─────────────────────────────────────────────────────────┘

Link rot detection

Web sources can go offline. Rekall periodically checks URL sources and flags inaccessible ones:

rekall sources --verify  # Check all sources
rekall sources --status inaccessible  # List broken links

The TUI Sources dashboard shows:

• Top sources by personal score
• Emerging sources (recently cited multiple times)
• Dormant sources (not used in 6+ months)
• Inaccessible sources (link rot detected)

Seed sources and automatic promotion

Rekall distinguishes between two types of high-value sources:

Seeds are sources you explicitly mark as trusted. They're exempt from demotion and always visible in recommendations. Import them from Speckit research files:

rekall sources migrate --path ~/.speckit/research/
# Imports all URLs from your research markdown files as seed sources

Promotion happens automatically. When a source meets these criteria:

• Usage count ≥ 3
• Personal score ≥ 30
• Last used within 180 days

...it gets promoted. Promoted sources get priority in suggestions.

Source themes

Tag sources with themes to organize and filter:

rekall sources add-theme 01HX7... security
rekall sources add-theme 01HX7... oauth

# Find sources by theme
rekall sources suggest --theme security
# Returns JSON list of security-related sources, sorted by score

Hub vs Authority classification

Rekall automatically classifies sources based on known domains:

Classification affects scoring — authorities get a small bonus. Add your own known domains:

rekall sources classify 01HX7... authority

100% local. 100% yours.

Your machine
     │
     ▼
┌─────────────────────────────────────┐
│  ~/.local/share/rekall/             │
│                                     │
│  Everything stays here.             │
│  No cloud. No account. No tracking. │
│                                     │
└─────────────────────────────────────┘
     │
     ▼
  Nowhere else. Ever.

Your knowledge is yours. Rekall doesn't phone home. It doesn't require an account. It works offline. Your debugging history, your architectural decisions, your hard-won wisdom — all private, all local.

Getting started

Install

# With uv (recommended)
uv tool install git+https://github.com/guthubrx/rekall.git

# With pipx
pipx install git+https://github.com/guthubrx/rekall.git

Try it

# Add your first entry
rekall add bug "My first captured bug" -t test

# Search it
rekall search "first"

# Open the visual interface
rekall

MCP Server: Works with any AI assistant

Rekall exposes your knowledge base via the Model Context Protocol (MCP) — the open standard for connecting AI assistants to external tools.

One command, universal access

rekall mcp  # Start the MCP server

Compatible with major AI tools

Configuration example (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rekall": {
      "command": "rekall",
      "args": ["mcp"]
    }
  }
}

What your AI can do

Once connected, your AI assistant can:

• Search your knowledge base before answering
• Cite your past solutions in its responses
• Suggest capturing new knowledge after solving problems
• Link related entries automatically
• Surface patterns across your debugging history

Auto-Context Capture

When using Rekall with compatible agents (Claude Code, Cline, Continue), it automatically detects the active conversation and modified files. When the agent saves a memory, Rekall attaches:

• Conversation Excerpt: Relevant parts of the dialogue leading to the solution
• Modified Files: List of files changed in the git repository
• Temporal Markers: Time of day and day of week to help episodic memory

This ensures you never lose the "why" and "how" behind a solution.

Your knowledge compounds automatically — the more you use it, the smarter it gets.

Integrate with Speckit

Speckit is a specification-driven development toolkit. Combined with Rekall, it creates a powerful workflow where your specifications feed your knowledge base.

Why integrate?

• Specs become searchable knowledge: Decisions made during spec writing are captured
• Patterns emerge: Common architectural choices surface across projects
• Context preserved: The "why" behind specs is never lost

Setup

1. Install both tools:

uv tool install git+https://github.com/guthubrx/rekall.git
uv tool install git+https://github.com/YOUR_USERNAME/speckit.git

2. Configure Speckit to use Rekall (in your .speckit/config.yaml):

integrations:
  rekall:
    enabled: true
    auto_capture: true  # Automatically capture decisions
    types:
      - decision
      - pattern
      - pitfall

3. During spec work, Speckit will:
   • Query Rekall for relevant past decisions
   • Suggest capturing new architectural choices
   • Link specs to related knowledge entries

Example workflow

# Start specifying a feature
speckit specify "User authentication system"

# Speckit queries Rekall: "Have you made auth decisions before?"
# → Shows your past OAuth vs JWT decision from another project

# After finalizing the spec
speckit plan

# Rekall captures: decision "JWT for stateless auth in microservices"

┌──────────────────────────────────────────────────────────────┐
│                     YOUR QUERY                               │
│              "browser blocking API calls"                    │
└──────────────────────────────────┬───────────────────────────┘
                                   │
           ┌───────────────────────┼───────────────────────┐
           ▼                       ▼                       ▼
    ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
    │   FTS5      │        │  Semantic   │        │  Keywords   │
    │  (50%)      │        │   (30%)     │        │   (20%)     │
    │             │        │             │        │             │
    │ Exact word  │        │ Meaning via │        │ Structured  │
    │ matching    │        │ embeddings  │        │ triggers    │
    └──────┬──────┘        └──────┬──────┘        └──────┬──────┘
           │                      │                      │
           └───────────────────────┼───────────────────────┘
                                   ▼
                        ┌─────────────────┐
                        │  FINAL SCORE    │
                        │  85% match      │
                        └─────────────────┘

# FTS-only mode (default, no model needed)
rekall search "CORS error"

# Enable semantic search (downloads model on first use)
rekall config set embeddings.enabled true

┌──────────────────────────────────────────────────────────────┐
│  situation        │  "API calls timeout after deploy"        │
│  solution         │  "Increased connection pool size"        │
│  what_failed      │  "Retry logic didn't help"               │
│  trigger_keywords │  ["timeout", "deploy", "connection pool"]│
│  error_messages   │  "ETIMEDOUT after 30s"                   │
│  files_modified   │  ["config/database.yml"]                 │
└──────────────────────────────────────────────────────────────┘

rekall add bug "Timeout in prod" --context-interactive
# Rekall asks: What was happening? What fixed it? What didn't work?
# Your answers become searchable disambiguation context

┌───────────────────────────────────────────────────────────────┐
│                    ENTRY STORAGE                              │
├───────────────────────────────────────────────────────────────┤
│  context_blob     │  Compressed JSON (zlib)    │  ~70% smaller│
│  context_keywords │  Indexed table for search  │  O(1) lookup │
│  emb_summary      │  384-dim vector (summary)  │  Semantic    │
│  emb_context      │  384-dim vector (context)  │  Semantic    │
└───────────────────────────────────────────────────────────────┘

score = 0.6 × frequency_factor + 0.4 × freshness_factor

Learn more

Requirements

• Python 3.10+
• That's it. No cloud services. No API keys. No accounts.

Development Setup

If you want to contribute to Rekall or run it from source:

Using uv (Recommended)

This project uses uv for dependency management.

# 1. Clone the repository
git clone https://github.com/guthubrx/rekall.git
cd rekall

# 2. Sync dependencies (including embeddings support)
uv sync --extra embeddings

# 3. Run Rekall
uv run rekall

The uv sync command creates a local .venv with all necessary packages. You only need to run this once (or when dependencies change).

Using pip

If you prefer standard pip:

# Install in editable mode with embeddings support
# Note the quotes around the package name for zsh compatibility
pip install -e ".[embeddings]"

License

MIT — Do what you want with it.

Stop losing knowledge. Start remembering.

uv tool install git+https://github.com/guthubrx/rekall.git
rekall