开源MCP工具：Multi-tiered memory and knowledge base plugin

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.

---

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.

Installation from Source

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

Quick Start

Configuration

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

```toml

total-recall configuration

[tiers.pinned] max_content_chars = 500 # Max characters per pinned entry (oversize rejected, never truncated) floor_enabled = true # Per-turn pinned-directive floor (UserPromptSubmit re-injection) floor_every_n_turns = 6 # Re-inject the pinned block at least every N user turns floor_growth_tokens = 6000 # ...or after ~this many tokens of transcript growth (whichever trips first)

[tiers.hot] max_entries = 50 # Max entries auto-injected per prompt token_budget = 4000 # Max tokens for hot tier injection (pinned tokens come off the top) carry_forward_threshold = 0.7 # Score threshold to stay in hot

[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 # Score above which cold→warm 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

api_key = "" # or set TOTAL_RECALL_EMBEDDING_API_KEY env var

--- Skills (optional) ---

--- Remote storage (optional) ---

--- User identity (optional, Postgres only) ---

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.

endpoint = "https://api.openai.com/v1" # OpenAI-compatible base URL

Developer Reference

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

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

Pinned tier surface: memory_pin moves any entry into the pinned tier (with optional scope: "project" | "global"); memory_unpin releases it to warm; memory_store accepts pinned: true to store-and-pin new content; memory_promote / memory_demote reject pinned as source or target. pinned is accepted in the tier filters of memory_search, memory_list, memory_recent, memory_export, and memory_get_all, and status reports pinned counts.

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

---