{"id":50254903,"url":"https://github.com/88plug/total-recall","last_synced_at":"2026-05-30T06:01:03.873Z","repository":{"id":360590682,"uuid":"1249864662","full_name":"88plug/total-recall","owner":"88plug","description":"Cross-CLI memory for AI coding assistants","archived":false,"fork":false,"pushed_at":"2026-05-27T04:53:49.000Z","size":866,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T05:04:55.178Z","etag":null,"topics":["anthropic","claude-code","claude-code-plugin","cross-cli","data-mining","mcp","memory","operator-profile","session-logs"],"latest_commit_sha":null,"homepage":"https://github.com/88plug/total-recall","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/88plug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T05:21:33.000Z","updated_at":"2026-05-27T04:53:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/88plug/total-recall","commit_stats":null,"previous_names":["88plug/total-recall"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/88plug/total-recall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Ftotal-recall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Ftotal-recall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Ftotal-recall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Ftotal-recall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/88plug","download_url":"https://codeload.github.com/88plug/total-recall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Ftotal-recall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33681809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude-code","claude-code-plugin","cross-cli","data-mining","mcp","memory","operator-profile","session-logs"],"created_at":"2026-05-27T05:00:43.842Z","updated_at":"2026-05-30T06:01:03.850Z","avatar_url":"https://github.com/88plug.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Requirements:** `bash` + `curl` + internet. That's it. The plugin\n\u003e bootstraps everything else (`uv`, python, deps) into its own data dir\n\u003e on first hook fire. No system-wide `pip install`. No system python required.\n\n# total-recall\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/88plug/total-recall)\n\nVersion: `v0.9.0` — see [git tag](https://github.com/88plug/total-recall/releases/tag/v0.9.0).\n\nCross-session memory for Claude Code. Mines your own `~/.claude/projects/\u003ccwd-slug\u003e/*.jsonl` session\ntranscripts and surfaces the useful parts — prior decisions, your corrections, approaches that\nfailed, real progress, plus a persistent profile of you (the operator) — to future Claude Code\nsessions before the model has to ask.\n\nThe operator is the source of truth. Models change, projects come and go; the human running the\nsessions is the one constant. v0.3 makes that explicit: an `OperatorProfile` and `VoiceProfile`\nare first-class extracted artifacts, queryable in one MCP call at SessionStart.\n\n## Why this exists\n\nClaude Code today has three kinds of memory, and none of them mine the transcript history:\n\n- **`amnesia`** (88plug) handles *intra-session* continuity across compaction. It snapshots the\n  current working state so a single session survives a compact. It does not look at other sessions.\n- **Auto-memory** (`~/.claude/projects/\u003cproj-slug\u003e/memory/`) is hand-curated by the user and the\n  model. Useful, but it captures only what someone remembered to write down.\n- **CLAUDE.md** is static, hand-edited, and global / per-project.\n\nMeanwhile every session you've ever run is sitting on disk as append-only JSONL: every decision,\nevery \"no, do it this way\", every dead end. On a working machine that's tens of thousands of turns\nacross dozens of projects. Future sessions start blind to all of it.\n\n`total-recall` reads that history (locally, read-only) and feeds the high-signal parts back to\nnew sessions in a low-token form.\n\n## Quickstart\n\nLocal checkout (recommended during dev):\n\n```bash\ngit clone https://github.com/88plug/total-recall.git\ncd total-recall\npip install -e .[vec]\nclaude --plugin-dir \"$PWD\"\n```\n\nMarketplace install (once published):\n\n```\n/plugin marketplace add 88plug/total-recall\n/plugin install total-recall@88plug\n```\n\nFirst run will auto-backfill your existing transcripts in the background (setsid-detached, so it\nsurvives the spawning Claude Code session exiting; progress goes to `logs/bootstrap.log`).\nSubsequent sessions get a SessionStart signpost summarizing what's relevant to the current `cwd`.\n\nFor a manual full reindex, `total-recall index --rebuild --jobs N` parallelizes ingest across\nsession files (a typical corpus drops from ~22s single-threaded to ~9s at `--jobs 4`).\n\n## What it captures\n\n17 extractors total. 11 run inline over each session's record stream; 6 are operator-level\naggregators that run out-of-band against the full corpus.\n\n**Per-session (in pipeline):**\n\n- `corrections` — turns where the user redirected the model (\"no, not that way\",\n  `queue-operation` interrupts, restated requirements).\n- `decisions` — \"we're going with X because Y\" moments, from assistant text and user-confirmed\n  pivots.\n- `self_corrections` — places the model corrected itself (\"actually, scratch that\") — useful\n  signal that an earlier statement is now wrong.\n- `progress` — how far a given line of work actually got. Anchors \"we already did X\".\n- `domain_facts` — durable signals about the codebase / environment (versions, paths, conventions).\n- `away_summaries` — recap text the user wrote after returning to a stale session.\n- `model_corrections` — corrections specifically about model behavior / output format.\n- `standing_decisions` — decisions the user explicitly marked as durable across sessions.\n- `bans` — explicit \"never do X\" instructions.\n- `goals` — what the user said they're trying to achieve in this session.\n- `truth_rhetoric` — assertions the user made about objective state (\"the deploy is broken\",\n  \"X is the canonical file\") — kept so a later session can check whether they still hold.\n\n**Standalone (operator-level, run out-of-band against the corpus):**\n\n- `operator_profile` — durable signals about *the human*: who they are, how they work,\n  preferences across projects.\n- `voice_profile` — how the user writes: tone, phrasing patterns, verbal tics. Lets a model\n  match register without being told.\n- `ontology` — vocabulary the user uses for their own systems (project names, machine names,\n  service names) so a fresh session resolves jargon without asking. Also populates a\n  cross-project co-mention graph (`projects.related_projects`) so the operator's portfolio\n  shape — hub vs spoke projects, dependency direction — is queryable.\n- `workflow` — *how* the operator works: fan-out vocabulary + per-session frequency, autonomy\n  score, mid-flight interrupt rate, planning idiom, peak hours / preferred work window,\n  session shape, subagent adoption rate. EMA-blended on the hot path.\n- `implicit_preferences` — preferences the operator expresses by *behavior* rather than as\n  a ban/decision: tool-call ratios (e.g. Edit vs Write), shell-command dominance within a\n  group (e.g. uv vs pip), absence patterns, format preferences, recurring vocabulary. Promoted\n  only when the signal crosses a multi-axis threshold (≥5 sessions, ≥3 projects, ≥7-day span,\n  ≥80% non-contradiction).\n- `satisfaction` — bidirectional praise/frustration profile paired with the preceding\n  assistant-turn shape (`tool_call_brief`, `long_prose`, `confirmation_request`, etc.).\n  Captures that for some operators satisfaction is silent — calibration on the absence of\n  frustration, not just the presence of praise.\n\n## Metrics\n\nAfter your index is built, `total-recall metrics` gives you visibility into your own Claude Code usage — tokens spent, slowest sessions, most-corrected topics, compaction frequency — all from the local SQLite index. No external collector, no telemetry, no SaaS.\n\n### Subcommands\n\n- `total-recall metrics summary [--since 7d] [--project PATH]` — sessions, tokens (with cache-read %), wall vs active hours, estimated $ cost, top corrections, busiest project, longest session.\n- `total-recall metrics cost [--rate model=in/out] [--since 30d]` — per-model token+cost breakdown using bundled default rates or your overrides.\n- `total-recall metrics sessions [--top 10] [--by tokens|duration|corrections]` — rank sessions on a column.\n- `total-recall metrics topics [--since 30d] [--limit 10]` — most-extracted topics across corrections and decisions.\n- `total-recall metrics health` — last ingest age, hook fire rate, p95 latency, error count.\n\nAll subcommands support `--json` for piping into `jq` / spreadsheets.\n\n### Example\n\n```\n$ total-recall metrics summary --since 7d\ntotal-recall metrics — past 7d\n  sessions: 42   projects: 6   compactions: 11\n  tokens:  in 18.4M (62% cache-read), out 412k    ~ $14.20 @ sonnet\n  active:  21.3h    wall: 38.1h\n  top corrections: \"use Edit not Write\" ×6,  \"no emojis in commits\" ×4\n  busiest project: /home/operator/acme-net  (8.1M tokens, 14 sessions)\n  longest session: 73 min, 2.1M tokens — \"feature-dev: relay-failover\"\n```\n\n### Why not OpenTelemetry / Langfuse?\n\nWe considered both. Findings:\n\n- **Langfuse** is wrong-shape: its core abstraction is `Generation` (LLM call), but total-recall doesn't call LLMs — it's a memory tool downstream of Claude Code. Plus self-hosting needs Postgres + ClickHouse + Redis (4GB RAM floor) for what amounts to a 50MB SQLite plugin.\n- **OpenTelemetry** is deferred to v0.3. The official `modelcontextprotocol/python-sdk` issue #421 (\"Add OTel\") is still open and unmerged in mid-2026; manual span wrappers now would need rewriting when upstream lands. Claude Code itself already emits OTel at the host level (`CLAUDE_CODE_ENABLE_TELEMETRY=1`).\n- **Native analytics over our own SQLite index** wins: every `usage{}` block, `compact_boundary`, and extracted correction is already queryable. `total-recall metrics` exposes that directly, with zero new dependencies and zero data leaving the machine.\n\nWhen (a) the upstream MCP SDK lands OTel middleware, or (b) total-recall gets multi-user deployments where a central operator needs aggregated metrics, the path is wired-but-off: add an optional `[telemetry]` extra dependency group and emit spans alongside the existing metrics tables.\n\n## Delivery surfaces\n\n- **SessionStart signpost hook** — injects a short, budget-aware brief at session start. Default\n  cap is a few hundred tokens; truthfully nothing if there's nothing useful to say. The\n  recommended one-call pattern for the model is `get_operator_context`, which bundles the\n  operator profile, voice profile, active goal, recent corrections, and standing decisions.\n- **MCP server (26 tools)** — live queries the model can call mid-conversation.\n\n  *v0.1 core (6):* `recall`, `prior_sessions_for_cwd`, `find_failed_attempts`,\n  `find_user_preferences`, `get_session_digest`, `search_messages`.\n\n  *v0.3 operator-aware (17):* `get_operator_context`, `get_operator_profile`,\n  `get_voice_profile`, `recall_corrections_about`, `get_recent_corrections`,\n  `list_standing_decisions`, `get_decision_for_topic`, `check_banned`, `list_failed_attempts`,\n  `get_active_goal`, `list_goals`, `get_past_truth_assertions`, `assess_escalation_risk`,\n  `get_project_graph`, `get_machine_inventory`, `define_term`, `recall_targeted`.\n\n  *v0.8 workflow / satisfaction / implicit-prefs (3):* `get_workflow_profile`,\n  `get_satisfaction_profile`, `list_implicit_preferences`.\n\n- **`/recall` skill** — orientation-style guidance the model loads on demand for deeper dives.\n- **`/speak-like-operator` skill** — operator voice-matching skill, runtime-populated from `get_voice_profile()`.\n- **Slash commands** — for the human operator: `/recall`, `/recall-status`, `/recall-inspect`,\n  `/recall-rebuild`, `/recall-promote`, `/recall-metrics`, `/recall-cost`, `/recall-topics`,\n  `/recall-health`.\n\nEach surface is independently disable-able. Convention-based discovery: the plugin manifest\ndeclares no hook/skill/command/mcp keys — Claude Code picks them up from the sibling directories.\n\n## Storage layout\n\nEverything stays under `${CLAUDE_PLUGIN_DATA}/total-recall/` (env-resolved by Claude Code; do not\nhardcode the path). Typical contents:\n\n```\n${CLAUDE_PLUGIN_DATA}/total-recall/\n  index.db                       SQLite (FTS5 for keyword recall)\n  vec.db                         sqlite-vec embeddings (only if [vec] extra installed)\n  state.json                     last-indexed offsets per session file\n  .bootstrapping                 lockfile present during first-run backfill\n  .bootstrap_banner_shown        marker so the first-run banner is only shown once\n  logs/\n    hooks.log                    hook invocations + errors\n    bootstrap.log                background backfill output (setsid-detached)\n    events.jsonl                 NDJSON event stream (10MB rotation → events.jsonl.1.gz, .2.gz, …)\n```\n\n`index.db` schema by version:\n\n- **v0.1:** `sessions`, `records`, `extractions` (+ FTS5 virtual tables).\n- **v0.2:** adds `turns`, `compactions`, `ingest_runs` for per-turn and ingest-run accounting.\n- **v0.3:** adds `operator_profile`, `voice_profile`, `standing_decisions`, `bans`,\n  `failed_attempts`, `goal_stack`, `projects`, `machines`, `vocabulary`.\n- **v0.5:** adds `source` + `dedup_superseded_by_source` columns for multi-CLI ingest —\n  one index now spans Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Continue, Cline, and\n  Aider (cross-source dedup keeps the highest-priority copy of duplicated turns).\n\nThe session JSONLs themselves are never written to.\n\n## Privacy\n\n- **Read-only** on `~/.claude/projects/*.jsonl`. The Claude Code harness owns those files;\n  `total-recall` only opens them with `O_RDONLY`.\n- **Local-only.** No network calls. Embeddings (if enabled) run in-process via `fastembed`.\n- **No re-uploading.** Transcripts contain secrets, internal URLs, and private code. They never\n  leave the machine.\n\n## Optional local-LLM refinement\n\n**It just works.** On first install, total-recall automatically sets up a small\nlocal model (qwen3.5:2b) in the background — nothing for you to do.\n\nThe bootstrap process (which runs once, detached, when you install the plugin)\nfetches the ollama binary (~38 MB, no `sudo`, into the plugin data dir) and\npulls the default model (~2.7 GB). A one-time banner in your first session\nannounces that setup is in progress. Subsequent sessions get the benefit\nautomatically.\n\n**Privacy is unchanged and paramount.** Everything stays on your machine:\nthe model runs on-device via ollama, and your transcripts are never uploaded\nanywhere. Cloud APIs are deliberately not supported — they would break the\nno-reupload guarantee.\n\n### What refinement improves\n\nRefinement runs on the cold path only (during `rebuild`). If ollama is not yet\nready, the heuristic baseline runs instead and nothing breaks.\n\n| What gets refined | Heuristic baseline | With qwen3.5:2b |\n|---|---|---|\n| Machine-name extraction | Pattern-based NER | Precision 1.0, Recall 1.0 |\n| Vocabulary definitions | Absent (terms listed, undefined) | ~60% coverage |\n| Project narratives | N/A | Short, accurate summaries |\n\n### Opt-outs and overrides\n\n| Env var | Default | Description |\n|---|---|---|\n| `TOTAL_RECALL_LLM_PROVIDER` | `auto` | `none` disables the entire LLM layer (no download, no daemon, no refinement). `ollama` forces the ollama path. |\n| `TOTAL_RECALL_LLM_MODEL` | `qwen3.5:2b` | Override the model. `qwen3.5:4b` or larger (e.g. a ≥9B model) gives higher vocabulary coverage at the cost of more RAM and slower runs. |\n| `TOTAL_RECALL_LLM_REFINE_TEXT` | `1` | Set to `0` to disable text-gen refinement (vocab + narratives) while keeping machine-name extraction. |\n| `TOTAL_RECALL_LLM_BASE_URL` | `http://localhost:11434` | Ollama API endpoint. |\n\nTo disable everything: add `TOTAL_RECALL_LLM_PROVIDER=none` to your environment\nbefore the plugin starts. No download, no daemon, no refinement — pure heuristics.\n\nThe `/total-recall:llm-setup` slash command still exists as a manual fallback if\nauto-provisioning fails (e.g. disk space constraints, network issue during install).\nSee [`docs/llm-refinement.md`](docs/llm-refinement.md) for troubleshooting.\n\n## Relation to amnesia\n\n`amnesia` and `total-recall` are complements, not competitors:\n\n| | amnesia | total-recall |\n|--|--|--|\n| Scope | One session, across compaction | Across sessions, across projects |\n| Trigger | PostCompact / Stop hooks | SessionStart + on-demand MCP |\n| Storage | Per-project `memory/` snapshots | Mined index from JSONL history |\n| Owns | The *current* working state | The *historical* record |\n\nIf `amnesia` is installed, `total-recall` reads its `memory/` snapshots as a high-signal extra\nsource — it doesn't duplicate or overwrite them.\n\n## Development\n\n```bash\npip install -e .[dev,vec]\nruff check .\nmypy total_recall\npytest\n```\n\nThe architecture is a flat 4-layer pipeline; see [`docs/architecture.md`](docs/architecture.md).\n\n## License\n\n[Functional Source License, Version 1.1, ALv2 Future License](LICENSE.md)\n(`FSL-1.1-ALv2`).\n\nIn plain English: free to use, copy, modify, and redistribute for any purpose\n*except* a Competing Use — i.e. offering this software (or a substantially\nsimilar substitute) as a commercial product or service. Each released version\nautomatically converts to the Apache License 2.0 on the second anniversary of\nits release date.\n\nFor commercial-use inquiries that fall outside the Permitted Purpose:\nclaude@cryptoandcoffee.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F88plug%2Ftotal-recall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F88plug%2Ftotal-recall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F88plug%2Ftotal-recall/lists"}