Skip to content
Back to search

total-recall

Persistent memory plugin for Claude Code. Tiered memory system with write gates, correction propagation, and slash commands.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/davegoldblatt--total-recall/badge.svg)](/listings/davegoldblatt--total-recall)

HTML

<a href="/listings/davegoldblatt--total-recall"><img src="/api/listings/davegoldblatt--total-recall/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install as a plugin (recommended)

/plugin marketplace add davegoldblatt/recall-marketplace
/plugin install recall@recall-marketplace

Or install standalone

git clone https://github.com/davegoldblatt/total-recall.git
cd total-recall
./install.sh /path/to/your/project

After installing, restart Claude Code or run `/hooks` to activate.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 243 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Total Recall
  2. A memory system for Claude Code that remembers what matters and forgets what doesn't.
  3. ## The Problem
  4. Claude Code forgets everything between sessions. Every time you start a new conversation, it's like talking to someone with amnesia. You end up repeating yourself:
  5. - "We already tried that approach, it didn't work."
  6. - "Don't touch the auth file."
  7. - "I prefer tabs over spaces."
  8. - "The client's name is Sarah, not Sara."
  9. This gets old fast.
  10. ## What Total Recall Does
  11. It gives Claude Code a notepad that carries over between sessions, but a *picky* notepad. Not everything goes in. Before anything gets saved permanently, it has to pass a simple test: **will this matter tomorrow?**
  12. A preference you'll have for months? Saved. A decision you made and why? Saved. The fact that you ran a test five minutes ago? Not saved. The system keeps itself clean so Claude isn't wading through junk to find what's relevant.
  13. ## How It Works
  14. Think of it like a kitchen with four storage areas:
  15. **Counter** (`CLAUDE.local.md`): The stuff you reach for every day. Loads automatically, every session. Kept small on purpose, around a page of text.
  16. **Pantry** (`memory/registers/`): Organized by category. Your preferences, key decisions, project details, people you work with. Claude checks here when it needs something specific.
  17. **Daily notebook** (`memory/daily/`): Timestamped scratch notes from each day. Everything gets written here first. You decide later what's worth keeping permanently.
  18. **Storage closet** (`memory/archive/`): Old stuff that's done or outdated. Still searchable, but never loaded automatically.
  19. The key idea: **notes hit the daily notebook first, then you promote the keepers.** Claude doesn't get to decide on its own what's important enough to remember permanently. You do.
  20. ## Quick Start
  21. ### Install as a plugin (recommended)
  22. ```
  23. /plugin marketplace add davegoldblatt/recall-marketplace
  24. /plugin install recall@recall-marketplace
  25. ```
  26. ### Or install standalone
  27. ```
  28. git clone https://github.com/davegoldblatt/total-recall.git
  29. cd total-recall
  30. ./install.sh /path/to/your/project
  31. ```
  32. After installing, restart Claude Code or run `/hooks` to activate.
  33. ## Using It
  34. Here's your day-to-day:
  35. **Claude notices something worth remembering.** It writes to your daily notebook and tells you. You don't have to do anything.
  36. **You want Claude to remember something.** Just say "remember this" or use the write command:
  37. ```
  38. /recall-write Dave prefers concise error messages, no stack traces in prod
  39. ```
  40. **End of day (or whenever).** Review what piled up and promote the good stuff:
  41. ```
  42. /recall-promote
  43. ```
  44. **Find something from last week.** Search across everything:
  45. ```
  46. /recall-search authentication decision
  47. ```
  48. **You correct Claude.** The correction updates everywhere at once: daily notebook, registers, and the counter. The same mistake won't happen again.
  49. ### All Commands
  50. | Command | What it does |
  51. |---|---|
  52. | `/recall-init` | Set up the memory folders for the first time |
  53. | `/recall-write <note>` | Save a note (checks if it's worth keeping, suggests where) |
  54. | `/recall-log <note>` | Quick note to the daily notebook, no questions asked |
  55. | `/recall-search <query>` | Search everything |
  56. | `/recall-promote` | Review daily notes, move the keepers to registers |
  57. | `/recall-status` | Health check. Is everything working? |
  58. | `/recall-maintain` | Clean up stale or duplicate entries |
  59. | `/recall-forget <query>` | Mark something as outdated |
  60. | `/recall-context` | Show what memory Claude has loaded right now |
  61. If installed as a plugin, commands are namespaced: `/recall:recall-write` instead of `/recall-write`.
  62. ## The Write Gate
  63. This is the core idea. Before anything gets promoted to permanent memory, it has to pass at least one of these checks:
  64. 1. **Will it change how Claude behaves next time?** (a preference, a boundary, a pattern)
  65. 2. **Is it a commitment someone's counting on?** (a deadline, a deliverable, a follow-up)
  66. 3. **Is it a decision worth remembering the reasoning for?** (why you picked X over Y)
  67. 4. **Is it a stable fact that'll come up again?** (not something that'll be different tomorrow)
  68. 5. **Did you explicitly say "remember this"?**
  69. If none of those are true, it stays in the daily notebook and eventually ages out. This keeps memory lean. No junk drawer.
  70. ## When Corrections Happen
  71. If you tell Claude it got something wrong, it doesn't just say "sorry" and move on. It updates the daily notebook, the relevant register, and the counter, all in one shot. The old information gets marked as superseded (not deleted) so there's a trail of what changed and when.
  72. ## What Loads Automatically
  73. Only two things, every session:
  74. | What | Where | How |
  75. |---|---|---|
  76. | The rules (write gate, correction protocol) | `rules/total-recall.md` | Claude Code loads all rules files automatically |
  77. | Counter / working memory | `CLAUDE.local.md` | Claude Code loads this automatically |
  78. Everything else loads on demand: when you search, when it's relevant, or at session start via hooks.
  79. ## Hooks
  80. Two things happen automatically in the background:
  81. **When a session starts:** Claude gets a summary of open items and recent daily notes. This is the "here's where we left off" briefing.
  82. **Before memory gets compacted:** A timestamp gets written to the daily notebook so there's a record. This one is silent. Claude doesn't see it, it's just bookkeeping.
  83. Both hooks fail safely. If something goes wrong, they don't block Claude Code from working.
  84. Hooks use `$CLAUDE_PROJECT_DIR` (standalone) or `${CLAUDE_PLUGIN_ROOT}` (plugin) to resolve paths. No transcript parsing. The PreCompact hook only writes a timestamp marker to the daily log. It does not read or parse conversation transcripts.
  85. ## Architecture
  86. For those who want the technical details.
  87. ```
  88. Conversation (ephemeral, compacted/discarded)
  89. |
  90. v WRITE GATE: "Does this change future behavior?"
  91. |
  92. Daily Log (memory/daily/YYYY-MM-DD.md)
  93. All writes land here first. Raw, timestamped.
  94. |
  95. v PROMOTION: user-controlled via /recall-promote
  96. |
  97. Registers (memory/registers/*.md)
  98. Structured claims with metadata (confidence, evidence, last_verified)
  99. |
  100. v DISTILLATION: only what's essential for every session
  101. |
  102. Working Memory (CLAUDE.local.md)
  103. ~1500 words. Auto-loaded. The persistent "personality."
  104. |
  105. v EXPIRY
  106. |
  107. Archive (memory/archive/)
  108. Searchable history. Never auto-loaded.
  109. ```
  110. ### Key Mechanisms
  111. **Write Gate:** Filters out noise. Only behavior-changing facts, commitments, decisions, and explicit "remember this" requests pass through.
  112. **Daily Log First:** All writes land in the daily log. Promotion to registers is a separate step, controlled by the user. This prevents the model from prematurely solidifying inferences.
  113. **Contradiction Protocol:** Never silently overwrites. Old claims are marked `[superseded]` with date and reason. The pattern of change is preserved.
  114. **Correction Gate:** Human corrections get highest priority. One correction triggers writes to daily log + register + working memory.
  115. ### File Structure
  116. **Plugin format** (installed via `/plugin install`):
  117. ```
  118. total-recall/ # Plugin root
  119. ├── .claude-plugin/
  120. │ └── plugin.json # Plugin manifest
  121. ├── skills/ # Slash commands (namespaced)
  122. │ ├── recall-write/SKILL.md
  123. │ ├── recall-search/SKILL.md
  124. │ └── ...
  125. ├── hooks/
  126. │ ├── hooks.json # Hook configuration
  127. │ ├── session-start.sh
  128. │ └── pre-compact.sh
  129. ├── rules/
  130. │ └── total-recall.md # Protocol (auto-loaded)
  131. └── templates/ # Scaffolding templates
  132. ├── SCHEMA.md
  133. ├── CLAUDE.local.md
  134. └── registers/
  135. ```
  136. **Standalone format** (installed via `install.sh`):
  137. ```
  138. your-project/
  139. ├── .claude/
  140. │ ├── commands/recall-*.md # Slash commands
  141. │ ├── rules/total-recall.md # Protocol (auto-loaded)
  142. │ ├── hooks/*.sh # Hook scripts
  143. │ └── settings.local.json # Hook configuration
  144. ├── memory/
  145. │ ├── SCHEMA.md
  146. │ ├── daily/YYYY-MM-DD.md
  147. │ ├── registers/*.md
  148. │ └── archive/
  149. ├── CLAUDE.md
  150. └── CLAUDE.local.md # Working memory (gitignored)
  151. ```
  152. ### Compared to Other Memory Tools
  153. | | Total Recall | Auto-ingest tools |
  154. |---|---|---|
  155. | **What gets saved** | Only what passes the write gate | Everything |
  156. | **Default destination** | Daily log (promote later) | Permanent storage |
  157. | **Context cost** | ~1500 words working memory | Grows unbounded |
  158. | **Corrections** | Propagate to all tiers immediately | Varies |
  159. | **User control** | Promotion is explicit | Automatic |
  160. | **Architecture** | 4-tier with metadata | Flat or 2-tier |
  161. ## Privacy
  162. - Everything is local. No network calls, no telemetry, no external services.
  163. - All memory is plain markdown files you can read and edit yourself.
  164. - `CLAUDE.local.md` is gitignored by default (it's personal).
  165. - `memory/` is gitignored by default (it can contain personal notes).
  166. - Hooks never read your conversation transcripts.
  167. - To see exactly what's happening: check `hooks/*.sh` and `memory/`. It's all plain text.
  168. - To uninstall: delete `memory/`, `CLAUDE.local.md`, and the `.claude/` entries (or `/plugin uninstall recall`).
  169. ## Works Alongside Superpowers
  170. If you use [Superpowers](https://github.com/obra/superpowers), there are no conflicts. Superpowers handles *how* Claude works (methodology, TDD, plans). Total Recall handles *what* Claude remembers. Different jobs, same project.
  171. ## License
  172. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.