total-recall AGENTS.md

Agent & Contributor Guide

This file is the operational handbook for AI agents and human contributors working in this repo. For end-user docs see README.md; for the contributor onboarding flow see CONTRIBUTING.md. This file documents project-wide rules, the release flow, the plugin system, the session lifecycle, the schema migration framework, and the beta dogfood mechanics.

State as of 0.9.x: total-recall is a .NET 8 NativeAOT plugin (C# imperative shell + F# functional core). Shell: PowerShell (win32) — use PowerShell syntax for all bash commands. The TypeScript implementation that lived in src/ through 0.7.x was stripped during the 0.7.2 → 0.8.0 cutover. Anything in this file that mentions dist/, bun, tsup, vitest, publish.yml, bin/start.cjs, or src/db/schema.ts is either gone or renamed — see the strip series in CHANGELOG.md (commits 87975a7 → 7a8c437).

---

Quick Reference

Project Overview

.NET 8 NativeAOT MCP server plugin (C# imperative shell + F# functional core) with npm packaging for Claude Code / Copilot CLI / Cursor / Kiro / OpenCode marketplace distribution. Three-tier memory (Hot/Warm/Cold with a sticky flag — new entries default to warm and earn promotion to hot by access; sticky pins, set via memory_pin/memory_unpin, are always injected first and immune to decay/compaction) + hierarchical KB, all local by default (SQLite + sqlite-vec + bundled ONNX), optionally synced to Cortex (sticky pins are local-only, never synced). The single binary also exposes a third surface: a built-in local web UI (total-recall ui) serving an embedded React SPA with six sections (Dashboard, Memory, Knowledge Base, Usage, Insights, Config) via TotalRecall.Web.

Layer Diagram

TotalRecall.Host (C#)          ← AOT entry point + composition root
├── TotalRecall.Server (C#)    ← MCP JSON-RPC over stdio; 49 handlers (one file each)
├── TotalRecall.Web (C#)       ← embedded minimal-API + React SPA (web UI), dispatches to ToolRegistry
├── TotalRecall.Cli (C#)       ← CLI commands (Spectre.Console), including `total-recall ui`
├── TotalRecall.Infrastructure (C#) ← SQLite/Postgres, ONNX embedder, importers, migrations
└── TotalRecall.Core (F#)      ← Pure functions: tokenizer, decay, ranking, parsers, chunker

npm wrapper layer (zero-dep Node):
  bin/start.js (launcher) ← dispatches on argv: `serve` (or no args) runs the MCP
    bootstrap shim (IS the MCP server from the harness's view; comes up instantly;
    provisions [sha256-verified via release provisioning.manifest.json] + spawns +
    proxies the NativeAOT engine; supervises/restarts on crash; never drops the MCP
    connection). Every OTHER subcommand (`ui`, `reindex-embeddings`, `config`,
    `dump-catalog`, …) is run via bin/shim/direct.js — provision then spawn the engine
    directly with inherited stdio (NO shim/handshake), because those emit human-readable
    stdout, not MCP JSON-RPC. Shim modules: bin/shim/{jsonrpc-stdio,state,server-surface,
    provisioner,engine-proxy,orchestrator,direct}.js. catalog.json (repo root) seeds
    tools/list before the engine is ready; generated by
    `dotnet run --project src/TotalRecall.Host -- dump-catalog`.
  scripts/fetch-binary.js ← download helper (shared by postinstall + provisioner)
  scripts/postinstall.js, scripts/verify-binaries.js