total-recall

╔══════════════════════════════════════════════╗
║  REKALL INC. -- MEMORY IMPLANT SYSTEM v2.84  ║
╠══════════════════════════════════════════════╣
║                                              ║
║  CLIENT: Quaid, Douglas                      ║
║  STATUS: MEMORY EXTRACTION IN PROGRESS       ║
║                                              ║
║  > Loading tier: STICKY ......... [OK]       ║
║  > Loading tier: HOT ............ [OK]       ║
║  > Loading tier: WARM ........... [OK]       ║
║  > Loading tier: COLD ........... [OK]       ║
║  > Semantic index: 384 dimensions  [OK]      ║
║  > Vector search: ONLINE                     ║
║                                              ║
║  ┌──────────────────────────────────┐        ║
║  │ SELECT PACKAGE:                  │        ║
║  │                                  │        ║
║  │  [x] Total Recall -- $899        │        ║
║  │  [ ] Blue Sky on Mars            │        ║
║  │  [ ] Secret Agent                │        ║
║  └──────────────────────────────────┘        ║
║                                              ║
║  "For the Memory of a Lifetime"              ║
╚══════════════════════════════════════════════╝

  

total-recall

Persistent, cross-tool memory for AI coding assistants.

Your AI forgets everything when the session ends. Preferences, decisions, project context, corrections — gone. total-recall fixes that: a shared memory layer that persists across sessions, tools, and devices.

---

The Problem

Every TUI coding assistant has the same gaps:

• No memory between sessions — every new session starts from zero, repeating the same context
• Siloed by tool — switching between Claude Code and Copilot CLI means starting from scratch
• Single-machine — your context doesn't follow you across devices
• Context bloat — stuffing everything into a CLAUDE.md wastes tokens every prompt
• No token visibility — no way to know what your AI sessions actually cost

---

The Solution

• Persistent memory — corrections, preferences, decisions, and project context survive sessions automatically
• Cross-tool — one memory store shared across Claude Code, Copilot CLI, Cursor, Cline, OpenCode, and Hermes; existing memories auto-import on first run
• Built-in web UI — total-recall ui opens a local browser dashboard (Dashboard, Memory, Knowledge Base, Usage, Insights, Eval, Config) for visual memory management without touching the CLI or AI session. Dark/light themes, a keyboard-first ⌘K command palette, and a developer-native Terminal / Archive design
• Cross-device — point TOTAL_RECALL_DB_PATH at a cloud-synced folder and your memory follows you everywhere
• Smarter context, lower token cost — a three-tier model (Hot / Warm / Cold, with sticky pins) enforces a 4000-token budget per prompt; new memories land in warm and earn their way into hot, so you get relevant context without carrying everything
• Token expenditure tracking — see exactly what each session costs, broken down by host, project, and time window
• Knowledge base — ingest your docs, READMEs, API references, and architecture notes; retrieved semantically when relevant
• Observability — measure retrieval quality, run benchmarks, and compare config changes with the built-in eval framework

By default, all state is local: SQLite + vector embeddings, no external services, no API keys. For teams, configure a shared Postgres/pgvector backend and remote embedder — same binary, just config.

---

Quick Start

Self-Install (Paste Into Any AI Coding Assistant)

> Install the total-recall memory plugin: fetch and follow the instructions at https://raw.githubusercontent.com/strvmarv/total-recall/main/INSTALL.md

That's it. Your AI assistant will read the instructions and install total-recall for its platform.

Claude Code

/plugin install total-recall@strvmarv-total-recall-marketplace

Or if the marketplace isn't registered:

/plugin marketplace add strvmarv/total-recall-marketplace
/plugin install total-recall@strvmarv-total-recall-marketplace

npm (Any MCP-Compatible Tool)

npm install -g @strvmarv/total-recall

Then add to your tool's MCP config:

{
  "mcpServers": {
    "total-recall": {
      "command": "total-recall"
    }
  }
}

This works with Copilot CLI, OpenCode, Cline, Cursor, Hermes, and any other MCP-compatible tool. The total-recall ui command is available independently of MCP configuration — it is a local management surface, not a host tool.

> Note: npx -y @strvmarv/total-recall does not work due to an npm bug with scoped package binaries. Use the global install (total-recall command) instead.

---

What Gets Remembered

Every memory has an entry type that tells total-recall what it is and how to treat it.

| Entry Type | Stored When | Example | |---|---|---| | Correction | You fix a mistake the AI made | "Use Array.from() not spread for NodeList — spread fails in our build target" | | Preference | You state a style or workflow preference | "Always use const over let unless reassignment is needed" | | Decision | You make an architecture or design choice | "Using Zustand for state — Redux was overkill for this app size" | | Surfaced | The AI captures context automatically | Key facts, constraints, or project-specific patterns noticed during work | | Imported | First-run import from another tool | Your existing Claude Code memories, Copilot snippets, Cursor history | | Compacted | Tier compaction generates a summary | Multiple related memories merged into a higher-signal entry | | Ingested | You ingest a file or directory | Chunks from READMEs, API docs, architecture notes |

Correction and Preference entries get priority treatment. They surface as actionable hints at every session start and carry higher decay scores — helping them earn promotion into the hot tier and resist eviction once there.

---

How It Works

Tier Model

total-recall uses a three-tier memory model — Hot / Warm / Cold — with a sticky flag that turns any hot entry into an always-injected pin. New memories land in Warm by default and earn their way into Hot by proving useful, so the auto-injected context stays high-signal without carrying everything:

• Warm (default landing tier, up to 10K entries) — where new memories go unless you say otherwise. Retrieved semantically per query: when you ask about authentication, relevant auth memories surface automatically. An entry is promoted to Hot once it earns it — access_count ≥ 5 and decay_score ≥ 0.7 (both tunable). Unused entries decay and migrate to Cold.
• Hot (up to 50 entries, 4000-token budget, 1200 chars/entry) — auto-injected into every prompt, no query needed. Populated by earned promotion from warm (and by explicit tier: "hot" writes, which are capped at 1200 characters — store a concise summary, not an essay). Sticky tokens come off the top of this budget.
• Sticky (pinned) — a flag on a hot entry, set via memory_pin (or store-and-pin with memory_store { pinned: true }). Sticky entries are unbounded, injected verbatim and first at session start under a ## Pinned directives (always follow) header, and are never truncated, decayed, demoted, evicted, or compacted. memory_unpin clears the flag, leaving the entry in hot as a normal earned resident. Project-scoped injection (default on): untagged pins are global and inject everywhere; a pin tagged with a project value (lowercase owner/repo slug or folder name) injects only when the detected cwd matches that repo. When no git repo is detected, only global pins inject (fail-closed).
• Cold (unlimited, hierarchical) — your knowledge base. Ingest entire directories — source trees, documentation, design specs — and they're retrieved when relevant.

> Upgrading from 3.x? The old Pinned tier is merged into Hot as the sticky flag, and a one-time migration runs automatically on first session_start: existing pins become sticky-hot, previously auto-hot entries move to warm, and the legacy pinned_* tables are dropped. The migration is irreversible — back up ~/.total-recall/total-recall.db first if you want a rollback path.

Hybrid Search

Retrieval combines BM25 full-text search and cosine vector similarity, merged by a pure F# ranking function. You get keyword precision when you search by exact terms and semantic recall when you describe what you need in natural language. The BM25/vector weight is tunable via [search] fts_weight.

Embeddings

All memories are embedded with bge-small-en-v1.5 (384 dimensions, CLS pooling, with an asymmetric query prefix for searches), running locally via ONNX — no API calls, no network dependency. The model (~133 MB) is fetched and sha256-verified at release build time and ships bundled inside the npm/release artifact; there is no runtime HuggingFace download. If the bundled model is absent, the binary fails fast with a clear error rather than fetching anything.

If you swap the local embedder, existing vectors are in the old model's space. By default (embedding.on_model_change = "auto") the sqlite and cortex backends re-embed their local index automatically — a one-time re-embed that runs in the background after launch, not on the startup path. The server stays fully usable while it runs; local semantic retrieval is degraded until it finishes, and progress is reported through session_start/status (you'll see a "re-index in progress (N/M)" notice). It's batched and resumable, so restarting mid-re-index picks up where it left off rather than starting over. This also covers a pre-existing index that was never fingerprint-stamped (e.g. an older cortex database): if it holds vectors but carries no fingerprint, it is re-embedded too rather than silently left in a stale model space. Set on_model_change = "warn" to run with the stale vectors (degraded retrieval, recurring warning) or "block" to refuse to start. Postgres can't auto-migrate: under auto it stops with an actionable error — re-ingest into a fresh database or use "warn". For cortex, only the local vector index is re-embedded (the remote re-embeds independently); total-recall reindex-embeddings runs the same re-embed offline for warn/block deferrals and manual re-embeds.

For enterprise deployments, swap in a remote embedder (OpenAI, Amazon Bedrock) for higher-dimensional vectors and finer-grained retrieval across shared team knowledge.

Session Start

Every session_start call runs the same sequence:

1. Import sync — scans all installed host tools (Claude Code, Copilot CLI, Cursor, Cline, OpenCode, Hermes), deduplicates via content hash, and imports new entries. 2. Sticky + hot tier assembly — sticky (pinned) entries are injected first, verbatim and untruncated, then current hot entries fill the remaining token budget. When tiers.pinned.project_scoping is on (default), only global pins and pins tagged to the detected repo are included; if no repo is detected, only global pins inject (fail-closed). 3. Hint generation — surfaces up to 5 high-value warm memories as actionable one-liners: Correction and Preference entries first, frequently accessed entries (3+ accesses) second, warm→hot promotion candidates third. No LLM calls — pure DB queries. 4. Tier summary — counts entries across hot, warm, cold, and all KB collections, plus a sticky count (tierSummary.pinned is retained for wire compatibility and now reports sticky-hot entries). A pinned_budget_pressure hint fires when sticky pins consume over half the token budget (suggested action: memory_unpin). 5. Session continuity — reports human-readable time since the last compaction event (proxy for last active session).

Every session_start also runs a skill scan: it reads ~/.claude/skills/ plus any directories listed in [skills] extra_dirs, persists the content + a locally-computed embedding to a SQLite skill cache, and advertises discovered skills as an ## Available Skills block in the session context. Scanned skills are invokable on demand via the skill_get MCP tool and discoverable via skill_search (hybrid semantic + keyword ranking with a usage-decay tie-breaker) — both work entirely offline with no Cortex required. In Cortex mode the scanned skills are also pushed to Cortex, usage events sync back as a multi-machine rollup, and pulled skills from other machines merge into the same local cache.

Pinned-Directive Floor

Pinned directives are injected once at session_start, but in a long session they drift far enough up the transcript that the model stops honoring them. The pinned floor re-asserts the pinned block near the live edge on an adaptive throttle, so your pins keep being followed all session long.

A per-turn UserPromptSubmit hook runs before each prompt and re-injects the pinned block when either trigger trips since the last injection:

• floor_every_n_turns user turns have elapsed (default 6), or
• ~floor_growth_tokens of transcript growth has accumulated (default 6000).

The first turn of a session seeds the throttle and skips (the block was just injected at session start). The re-injected block is rendered verbatim — identical to the session-start block — and prefixed with a short reminder line. Project scoping applies here too: the hook reads the cwd from the hook payload and filters pins by the detected repo (same fail-closed semantics as session start). The hook is fail-safe: it never blocks or rejects a prompt. Disable it entirely with floor_enabled = false.

Per-host support:

| Host | Per-turn floor | Mechanism | |---|---|---| | Claude Code | Active | UserPromptSubmit hook → additionalContext | | Copilot CLI | Pending upstream fix | Wired the same way, but Copilot CLI currently ignores the returned additionalContext | | Cursor | Layered fallback | session-start injection + skill-guided session_refresh (Cursor's beforeSubmitPrompt is block-only and cannot inject context) |

---

Supported Platforms

| Platform | Support | Notes | |---|---|---| | Claude Code | Full | Native plugin, session hooks, auto-import | | Copilot CLI | Full | Plugin wrapper, session hooks, auto-import from Copilot memory files | | Cursor | Full | Plugin wrapper, SessionStart hook; run /total-recall:commands compact manually — no SessionEnd hook | | OpenCode | Full | Plugin wrapper, auto-import from OpenCode project and agent files | | Cline | Full | Auto-import from task history; MCP server config required | | Hermes | Importer | Auto-import from SOUL.md and skills on first run; no session hooks |

---

Web UI

total-recall ships a built-in local web UI — a third surface alongside the MCP server (AI assistant integration) and the CLI (total-recall status, total-recall eval, etc.). It is a React SPA served directly from the single NativeAOT binary, no separate install or Node required.

Design. The UI has a developer-native Terminal / Archive identity: a monospace-forward type system (self-hosted JetBrains Mono + IBM Plex Sans — bundled into the binary, no CDN, fully offline), a fixed left navigation rail, a faint ruled-grid backdrop, and an amber phosphor accent. It ships dark and light themes with a toggle — your choice persists, and on first visit it follows your OS preference. A ⌘K / Ctrl-K command palette jumps to any page and runs live search across memories and the knowledge base, so the whole UI is reachable from the keyboard.

!total-recall web UI — Dashboard, dark theme

total-recall ui                  # serve on http://localhost:5577 and open the browser
total-recall ui --port 5600      # custom port
total-recall ui --no-open        # suppress auto-open (e.g. remote / headless)
total-recall ui --host 0.0.0.0   # bind all interfaces (warns about exposure)
total-recall ui --token <tok>    # supply a fixed token instead of a per-launch random one
total-recall ui --smoke          # CI mode: start, GET /api/health, exit 0/1

The server binds loopback only (localhost) by default. Every launch generates a fresh ephemeral bearer token that is injected directly into the served HTML, so opening the URL in a browser is sufficient — no copy-paste of credentials. A Host-header allowlist mitigates DNS-rebinding.

Seven sections are available in the left navigation rail:

| Section | What it shows | |---|---| | Dashboard | Tier composition, retrieval quality, token usage, recent activity, trend sparklines | | Memory | Browse, search, filter, promote/demote/pin/delete individual entries | | Knowledge Base | List collections, search, ingest files/directories, refresh or remove collections | | Usage | Token expenditure by host, project, model, and time window; per-session breakdown | | ✨ Insights | Memory-health score with an expandable breakdown, plus actionable cards computed server-side from your local store (no LLM): merge near-duplicate memories, promote high-use entries to pinned, surface retrieval gaps, and tune the similarity threshold from a recall curve | | Eval | Run the retrieval benchmark, review hit/miss/MRR with per-tier & per-content-type breakdowns and top misses, grow the benchmark from real retrieval misses, and compare config snapshots | | Config | Edit a safe subset of tuning knobs (validated, persisted via config_set); storage & embedding shown read-only |

Cost figures in the Usage section are client-side estimates derived from a bundled model pricing table. They are not billed amounts.

The SPA build is opt-in (-p:BuildSpa=true triggers npm ci && npm run build in ClientApp/ and embeds the Vite output in the assembly). Default dotnet build and all tests are Node-free — the binary falls back to a placeholder page when built without the SPA. Release builds always include the SPA.

---

Commands

All commands are routed through the /total-recall:commands skill:

| Command | Description | |---|---| | /total-recall:commands help | Show command reference table | | /total-recall:commands status | Dashboard overview | | /total-recall:commands search <query> | Semantic search across all tiers | | /total-recall:commands store <content> | Manually store a memory | | /total-recall:commands forget <query> | Find and delete entries | | /total-recall:commands inspect <id> | Deep dive on single entry with compaction history | | /total-recall:commands promote <id> | Move entry to higher tier | | /total-recall:commands demote <id> | Move entry to lower tier | | /total-recall:commands pin <id> | Pin entry — always injected at session start, never decays | | /total-recall:commands unpin <id> | Clear an entry's sticky flag (it stays in hot as an earned resident) | | /total-recall:commands history | Show recent tier movements | | /total-recall:commands lineage <id> | Show compaction ancestry | | /total-recall:commands export | Export to portable JSON format | | /total-recall:commands import <file> | Import from export file | | /total-recall:commands ingest <path> | Add files or directories to knowledge base | | /total-recall:commands kb search <query> | Search knowledge base | | /total-recall:commands kb list | List KB collections | | /total-recall:commands kb refresh <id> | Re-ingest a collection | | /total-recall:commands kb remove <id> | Remove KB entry | | /total-recall:commands compact | Force compaction | | /total-recall:commands eval | Retrieval quality metrics | | /total-recall:commands eval --benchmark | Run synthetic benchmark | | /total-recall:commands eval --compare <name> | Compare metrics between two config snapshots | | /total-recall:commands eval --snapshot <name> | Manually create a named config snapshot | | /total-recall:commands eval --grow | Review and accept/reject benchmark candidates from retrieval misses | | /total-recall:commands config get <key> | Read config value | | /total-recall:commands config set <key> <val> | Update config | | /total-recall:commands import-host | Re-run import sync from all host tools |

Memory capture, retrieval, and compaction run automatically in the background — see the "Automatic Behavior" section of the /total-recall:commands skill.

> Note: /total-recall:commands is implemented as a Claude Code skill (at skills/commands/SKILL.md), not as a slash-command file under commands/. The skill handles all <subcommand> arguments internally.

---

Configuration

The config file lives at ~/.total-recall/config.toml. All fields have defaults — you only need to override what you want to change.

# total-recall configuration

[tiers.pinned]
# The Pinned tier was merged into Hot as a "sticky" flag in 4.0. This section
# is kept as a deprecated alias — its floor_* / project_scoping fields still
# drive the per-turn re-injection of sticky pins. max_content_chars no longer
# applies (sticky entries are unbounded).
floor_enabled = true              # Per-turn pinned-directive floor (UserPromptSubmit re-injection)
floor_every_n_turns = 6           # Re-inject the sticky block at least every N user turns
floor_growth_tokens = 6000        # ...or after ~this many tokens of transcript growth (whichever trips first)
project_scoping = true            # Scope sticky injection by git repo: repo-tagged pins inject only in their repo; untagged pins are global; fail-closed when no repo detected

[tiers.hot]
max_entries = 50                  # Max entries auto-injected per prompt
token_budget = 4000               # Max tokens for hot tier injection (sticky pins come off the top)
carry_forward_threshold = 0.7     # Score threshold to stay in hot
max_content_chars = 1200          # Max characters per hot entry (oversize rejected — store a summary or keep it in warm); sticky pins are exempt

[tiers.warm]
max_entries = 10000               # Max entries in warm tier
retrieval_top_k = 5               # Results returned per search
similarity_threshold = 0.65       # Min cosine similarity for retrieval
cold_decay_days = 30              # Days before unused warm entries decay to cold

[tiers.cold]
chunk_max_tokens = 512            # Max tokens per knowledge base chunk
chunk_overlap_tokens = 50         # Overlap between adjacent chunks
lazy_summary_threshold = 5        # Accesses before generating summary

[compaction]
decay_half_life_hours = 168       # Score half-life (168h = 1 week)
warm_threshold = 0.3              # Score below which warm→cold
promote_threshold = 0.7           # Min decay_score to promote (cold→warm, and warm→hot)
promote_min_access = 5            # Min access_count for warm→hot promotion (paired with promote_threshold on decay_score)
warm_sweep_interval_days = 7      # How often to run warm sweep

[search]
fts_weight = 0.3                  # BM25 weight in hybrid ranking (0.0 = vector only, 1.0 = FTS only)

[scope]
default = "user"                  # Default scope for new entries (e.g., "user", "team")

[usage]
initial_backfill_days = 30        # Days of usage history to backfill on first sync

[regression]
miss_rate_delta = 0.1             # Alert if miss rate increased by this much vs. previous snapshot
latency_ratio = 2.0               # Alert if latency increased by this factor vs. previous snapshot
min_events = 20                   # Minimum retrieval events required before regression check runs

[embedding]
model = "bge-small-en-v1.5"      # Embedding model name
dimensions = 384                  # Embedding dimensions
# provider = "local"              # "local" (default) | "openai" | "bedrock"
# endpoint = "https://api.openai.com/v1"   # OpenAI-compatible base URL
# bedrock_region = "us-east-1"             # Bedrock only
# bedrock_model = "cohere.embed-v4:0"      # Bedrock model ID
# api_key = ""                             # or set TOTAL_RECALL_EMBEDDING_API_KEY env var

# --- Skills (optional) ---
# [skills]
# extra_dirs = [
#   "~/my-skills",
#   "/path/to/team-skills"
# ]

# --- Remote storage (optional) ---
# [storage]
# connection_string = "Host=localhost;Database=total_recall;Username=tr;Password=changeme"

# --- User identity (optional, Postgres only) ---
# [user]
# user_id = "alice"               # or set TOTAL_RECALL_USER_ID env var

Relocating the database: set TOTAL_RECALL_DB_PATH to an absolute path or ~/-prefixed path. See INSTALL.md for cloud-sync and shared-workspace guidance.

Switching to Postgres: uncomment the [storage] section with your connection string. The binary auto-detects the backend — no code changes, no flag. Pair with [embedding] provider = "bedrock" or "openai" for remote embeddings. Run migrate_to_remote to copy local memories to the shared database with re-embedding.

Connecting to Cortex

Total Recall Cortex is the shared backend platform that adds team knowledge bases, connectors (Jira, Confluence, GitHub), chat/RAG, and a React UI on top of the plugin's memory layer.

In Cortex mode, the plugin operates as a hybrid:

• User memories are stored locally (fast reads/writes), synced bidirectionally to Cortex every 300 seconds and at session boundaries
• Sticky (pinned) entries are local-only — Cortex has no sticky-pin support yet, so pins are never pushed, pulled, reconciled, or migrated (migrate_to_remote skips them)
• Global knowledge (team KB, connector-ingested data) is queried remotely from Cortex
• Telemetry (usage, retrieval events, compaction log) is pushed to Cortex for unified dashboards
• Skills are synced to Cortex so team members share the same skill library

Configure in your config.toml:

[storage]
mode = "cortex"

[cortex]
url = "https://your-cortex-instance.example.com"
pat = "tr_your_personal_access_token"
sync_interval_seconds = 300       # Background sync interval (default: 300)

Or via environment variables:

export TOTAL_RECALL_CORTEX_URL="https://your-cortex-instance.example.com"
export TOTAL_RECALL_CORTEX_PAT="tr_your_personal_access_token"

Generate a PAT from the Cortex web UI under Settings → Personal Access Tokens.

Offline resilience: If Cortex is unreachable, the plugin continues working locally. A persistent sync queue buffers outbound changes and flushes automatically when connectivity is restored.

Skills

total-recall can advertise custom skills at every session_start so your AI assistant knows which workflows are available. Skills are discovered from two places:

• ~/.claude/skills/ — the standard Claude Code user skills directory (always scanned)
• extra_dirs — additional directories you configure, scanned on every session start regardless of whether Cortex is available

Configure extra skill directories in ~/.total-recall/config.toml:

[skills]
extra_dirs = [
  "~/my-custom-skills",
  "/path/to/shared/team-skills"
]

Paths can be absolute or ~/-prefixed. Skills in extra_dirs are always advertised from disk — Cortex is not required.

Skill format: Each skill is either a single .md file or a directory containing a SKILL.md entry point. A minimal single-file skill:

---
name: my-skill
description: Does something useful
---

Full skill content here...

A bundle (directory with supporting files) uses the same frontmatter in its SKILL.md, and can include scripts, templates, or reference files alongside it.

Merge behavior: When Cortex is configured and reachable, the session context block merges cortex-stored skills with locally-scanned extra_dirs skills, deduplicating by name (Cortex entries take precedence). When Cortex is unavailable or not configured, only local skills appear.

---

Developer Reference

The MCP server exposes 41 core tools in every backend mode; local SQLite and Cortex modes add usage, cache, skill, and feedback tools (49 and 50 total, respectively). All tool names follow the pattern <domain>_<action>.

| Category | Tools | |---|---| | Session | session_start, session_end, session_context, session_refresh | | Memory | memory_store, memory_get, memory_get_all, memory_update, memory_delete, memory_inspect, memory_search, memory_list, memory_recent, memory_extract, memory_feedback† | | Tier management | memory_promote, memory_demote, memory_pin, memory_unpin, memory_history, memory_lineage | | Import / Export | memory_export, memory_import, import_host | | Knowledge base | kb_ingest_file, kb_ingest_dir, kb_search, kb_list_collections, kb_refresh, kb_remove, kb_summarize, kb_resolve | | Compaction | compact_now | | Eval | eval_report, eval_benchmark, eval_compare, eval_snapshot, eval_grow | | Config | config_get, config_set | | Status & Usage | status, usage_status† | | Cache | cache_check†, cache_store† | | Migration | migrate_to_remote | | Skills† | skill_search, skill_get, skill_list, skill_import_host, skill_delete (skill_delete: Cortex mode only) |

†Unavailable in Postgres mode (local SQLite + Cortex modes only).

Sticky (pinned) surface: memory_pin sets the sticky flag on an entry, moving it into the hot tier (with optional scope: "project" | "global"); memory_unpin clears the flag, leaving the entry in hot as an earned resident; memory_store accepts pinned: true to store-and-pin new content directly as sticky-hot; memory_promote / memory_demote reject a sticky entry as source or target (unpin it first). memory_list accepts a sticky: true filter, and status reports a sticky count (surfaced as tierSummary.pinned for wire compatibility). Project-scoped injection (enabled by tiers.pinned.project_scoping, default on): a pin is tagged to a repo by setting its project field to the lowercase owner/repo slug (e.g. radancy-pe/rai-ops-cortex) or bare folder name when no remote is configured — at injection time ProjectResolver detects the current repo from cwd (pure filesystem walk) and PinnedScope.OptsFor filters accordingly. Untagged (null-project) pins are global and always inject. When no repo is detected the injection is fail-closed to globals only.

Retrieval-quality feedback: memory_search returns { retrievalId, results } and kb_search returns a top-level retrievalId. The assistant can call memory_feedback with that retrievalId to confirm whether the retrieval was actually used; un-acted retrievals are inferred as misses after a grace window. This drives the eval_report metrics and the web UI's "Retrieval quality" card. memory_feedback is intentionally assistant-only — it is not exposed to the web UI.

Handler implementations live in src/TotalRecall.Server/Handlers/<ToolName>Handler.cs. Tool wiring: src/TotalRecall.Server/ServerComposition.cs → BuildRegistry().

---

Architecture

npm wrapper layer (Node, zero runtime dependencies):
  bin/start.js (MCP bootstrap shim) — comes up instantly; answers initialize/ping/tools/list
    from catalog.json before the engine is ready; provisions (sha256-verified download via
    release provisioning.manifest.json) + spawns + proxies the engine; supervises and
    restarts on crash; the MCP connection never drops (no more MCP error -32000 on first
    launch after an update); emits notifications/tools/list_changed once proxying begins.

MCP Server (.NET 8 NativeAOT — C# imperative shell + F# functional core)
├── TotalRecall.Core (F#)        — pure functions: tokenizer, decay, hybrid ranking, parsers, chunker
├── TotalRecall.Infrastructure   — SQLite/Postgres storage, ONNX/remote embedder, importers, migrations
├── TotalRecall.Server           — MCP JSON-RPC server, 41 core tool handlers (48–49 with mode-dependent tools), lifecycle
├── TotalRecall.Web              — embedded ASP.NET Core minimal API + React SPA (the web UI)
├── TotalRecall.Cli              — CLI commands (status, eval, kb, memory, config, migrate, ui)
└── TotalRecall.Host             — composition root, AOT entry point, migration guard

Tiers:
  Hot (50 entries, 1200 chars/entry) → auto-injected every prompt; earned from warm by access
    └─ sticky flag → user-pinned; injected first, unbounded, never decays/compacts/evicts
  Warm (10K entries, default ingress) → BM25 + cosine hybrid search per query; promotes to hot on merit
  Cold (unlimited)   → hierarchical KB retrieval

Backends (selected by config):
  Local:    SQLite + sqlite-vec + bundled ONNX embedder (default, zero config)
  Postgres: Postgres/pgvector + HNSW indexes + tsvector FTS + per-user visibility
  Cortex:   Local SQLite + write-local-then-enqueue sync to Cortex; remote queries for global KB

Data flow:

1. store — write a memory, assign tier (warm by default), embed, persist 2. search — embed query, BM25 + cosine vector search across all tiers, merge with F# ranking, return results 3. compact — decay scores, compact hot→warm (summarize), demote warm→cold; earned warm→hot promotion runs in the warm sweep 4. ingest — chunk files with heading-aware Markdown and regex-based code parsing, embed chunks, store in cold tier

Local mode: all state lives in ~/.total-recall/total-recall.db. The embedding model and the sqlite-vec native extension are bundled with the binary. No network calls required at runtime.

Cortex mode: user memories write locally first for low latency. A RoutingStore wraps every write: persist locally, enqueue to sync_queue. A background sync loop flushes the queue to Cortex every sync_interval_seconds (default: 300) and at session boundaries. Global knowledge (team KB, connectors) is read directly from Cortex.

---

Prerequisites

These apply only if you're building from source. The prebuilt binary is self-contained — no .NET runtime, no system SQLite, no Bun required.

• .NET 10 SDK — pinned by global.json at the repo root; builds the net8.0 NativeAOT target
• npm — for npm ci, which pulls sqlite-vec native libs needed by the csproj copy targets
• Embedding model — run sh scripts/fetch-bge-small.sh once to fetch + sha256-verify the bge-small-en-v1.5 ONNX model (~133 MB) into models/bge-small-en-v1.5/. The model is no longer committed to the repo (not in Git LFS); release builds fetch and bundle it into the per-RID artifact.

---

Installation from Source

git clone https://github.com/strvmarv/total-recall.git
cd total-recall
sh scripts/fetch-bge-small.sh              # fetch + sha256-verify the ONNX model (~133 MB)
npm ci                                     # pulls sqlite-vec native libs into node_modules/
dotnet build src/TotalRecall.sln
dotnet test src/TotalRecall.sln --filter "Category!=Integration"   # ~1000 tests
dotnet publish src/TotalRecall.Host/TotalRecall.Host.csproj -c Release -r win-x64 -p:PublishAot=true
# (swap win-x64 for your RID: linux-x64, linux-arm64, osx-arm64)

The publish output lands in src/TotalRecall.Host/bin/Release/net8.0/<rid>/publish/ with the binary plus all sibling native libs (libonnxruntime., libe_sqlite3., runtimes/vec0.*) ready to run.

Supported RIDs: linux-x64, linux-arm64, osx-arm64, win-x64. Intel Mac (osx-x64) is not shipped.

---

Contributing

See CONTRIBUTING.md for the full contributor guide, including how to add a new host importer, extend the chunking pipeline, or add a new MCP tool handler.

---

Built With & Inspired By

superpowers by obra

total-recall's plugin architecture, skill format, hook system, multi-platform wrapper pattern, and development philosophy are directly inspired by and modeled after the superpowers plugin. superpowers demonstrated that a zero-dependency, markdown-driven skill system could fundamentally improve how AI coding assistants behave — total-recall extends that same philosophy to memory and knowledge management.

If you're building plugins for TUI coding assistants, start with superpowers. It's the foundation this ecosystem needs.

Core Technologies

• .NET 8 / NativeAOT — single-binary deployment, no runtime dependency
• F# Core — pure functional core: tokenizer, parsers, decay, hybrid ranking
• Microsoft.Data.Sqlite — embedded SQLite with extension loading
• sqlite-vec — vector similarity search in SQLite (loaded as a native extension via LoadExtension)
• Microsoft.ML.OnnxRuntime — local ML inference, AOT-compatible
• Microsoft.ML.Tokenizers — canonical BERT BasicTokenization + WordPiece
• bge-small-en-v1.5 — sentence embeddings (384d, CLS pooling)
• Hand-rolled JSON-RPC stdio MCP server in TotalRecall.Server (no SDK dependency)
• Spectre.Console — CLI rendering for total-recall status / eval / kb list

---

License

MIT — see LICENSE