Skip to content
Back to search

recall

MarketplaceWorks with Claude CodeGitHub

Stop wasting tokens and re-explaining your project every session. Recall gives Claude Code , Opencode durable memory — entirely offline.

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/raiyanyahya-recall/badge.svg)](/listings/raiyanyahya-recall)

HTML

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

Install

Install instructions from the README

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

**From the marketplace** (this repo is its own marketplace):

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

**Local dev** (no install step):

claude --plugin-dir /path/to/recall

No `pip install` — the summarizer is vendored and stdlib-only (numpy used as an optional accelerator if present). Work a session, run `/recall:save`, and open a fresh session — Recall greets you with where you left off.

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.

.claude-plugin/marketplace.json · Manifest · 20 lines

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

  1. {
  2. "name": "recall",
  3. "owner": {
  4. "name": "Raiyan Yahya"
  5. },
  6. "metadata": {
  7. "description": "Fully-local project memory for Claude Code — session logging plus a vendored TextRank summary, with no API key or external model.",
  8. "version": "0.4.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "recall",
  13. "source": ".",
  14. "description": "Fully-local project memory for Claude Code: logs each session to .recall/history.md and condenses it into .recall/context.md with a vendored TF-IDF + TextRank summarizer. No API key, no external model.",
  15. "author": {
  16. "name": "Raiyan Yahya"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 319 lines

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

  1. <h1 align="center">🔁</h1>
  2. <h3 align="center">Recall — fully-local project memory for Claude Code</h3>
  3. <p align="center">
  4. <a href="https://claude.com/claude-code"><img alt="Built for Claude Code" src="https://img.shields.io/badge/built%20for-Claude%20Code-CC785C"></a>
  5. <a href="#opencode"><img alt="OpenCode: opt-in support" src="https://img.shields.io/badge/opencode-opt--in-1a1a2e"></a>
  6. <a href="https://github.com/raiyanyahya/recall/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/raiyanyahya/recall/actions/workflows/ci.yml/badge.svg"></a>
  7. <a href="https://github.com/raiyanyahya/recall/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/raiyanyahya/recall/actions/workflows/codeql.yml/badge.svg"></a>
  8. <a href="https://codecov.io/gh/raiyanyahya/recall"><img alt="Coverage" src="https://codecov.io/gh/raiyanyahya/recall/branch/master/graph/badge.svg"></a>
  9. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
  10. </p>
  11. > Claude Code starts every session cold. Recall keeps a local log of your
  12. > sessions and condenses it into a resume-ready summary **entirely on your
  13. > machine**. No API key, no external model, nothing sent anywhere. It's built for
  14. > people running Claude Code locally on a subscription: the only AI in the loop is
  15. > Claude Code itself; the summarization is done by a classical Python summarizer.
  16. ## Why Recall
  17. - **Free on your subscription.** It solves the cold-start problem — no more
  18. re-explaining the project each session — without a metered summarizer running up
  19. a bill. The summary is a local algorithm, not an LLM call, so persistent memory
  20. costs you nothing beyond the subscription you already pay for.
  21. - **Saves your usage credits.** Two ways: (1) the summary is built locally, so
  22. capturing and updating your memory spends **zero** model tokens; and (2)
  23. resuming from a compact `context.md` (~1–2K tokens) instead of re-explaining the
  24. project from scratch each session means far fewer tokens spent per session —
  25. stretching your subscription's usage limits (or, on the API, lowering billed
  26. credits).
  27. - **Nothing leaves your machine.** Your transcripts (code, paths, sometimes
  28. secrets) are never sent to any API. Most "memory" tools pipe your context to a
  29. model endpoint; Recall makes a privacy guarantee they can't. See
  30. [PRIVACY.md](PRIVACY.md) for the full policy.
  31. - **Zero-friction.** No `pip install`, no local model to run, no key to configure,
  32. works offline. It starts working the moment the plugin loads.
  33. Two files, written into your project under `.recall/`:
  34. - **`history.md`** — *the log.* Append-only. Every session is captured here as it
  35. happens (your prompts, Claude's replies, the files touched and commands run).
  36. - **`context.md`** — *the summary.* Overwritten by the local summarizer — the
  37. condensed "where are we right now" you load into the next session: goal,
  38. summary, **next steps / open threads**, files touched, and where you left off.
  39. ## "Doesn't Claude Code already have memory?"
  40. It does — and Recall is complementary, not a replacement. The built-in options
  41. solve different problems:
  42. - **`CLAUDE.md` (and the `#` shortcut)** is *hand-written* memory: rules and notes
  43. **you** curate, loaded as **instructions Claude follows**. Great for "how I want
  44. you to work," but it's manual upkeep and it doesn't record what actually
  45. happened in a session.
  46. - **`--continue` / `--resume`** replays a *prior conversation* — full fidelity, but
  47. it reloads the whole transcript (token-heavy) and is tied to your local session
  48. history on one machine, not a portable, readable digest.
  49. - **Context compaction** condenses a conversation *within* a session; it isn't a
  50. durable record you reopen days later.
  51. Recall fills the gap between these: an **automatic, deterministic record of what
  52. each session did**, condensed into a compact resume point.
  53. | | `CLAUDE.md` / `#` | `--continue` / `--resume` | **Recall** |
  54. |---|---|---|---|
  55. | What it is | Hand-written notes & rules | Reloads a prior conversation | Auto-captured session log + local summary |
  56. | Upkeep | Manual | None (you pick the session) | None — written as you work |
  57. | Holds | Instructions to follow | The full prior transcript | Goal, files, commands, where you left off, next steps |
  58. | Cost to resume | Small | Large (replays full transcript) | ~1–2K tokens (compact digest) |
  59. | Form | Markdown you edit | Local session state | Plaintext in `.recall/` — diffable & shareable |
  60. | How Claude treats it | As instructions | As the conversation | Fenced as **untrusted reference data** |
  61. In short: `CLAUDE.md` is *how I want you to work*; Recall is *here's what we did
  62. last time and where we stopped* — produced offline, with no model tokens spent.
  63. ## How it works
  64. | Moment | What happens |
  65. |---|---|
  66. | **During the session** | The `Stop` / `SessionEnd` hooks append new activity to `.recall/history.md`. Capture is incremental (only new turns) and fully local. |
  67. | **At session start** | The `SessionStart` hook surfaces `context.md` and has Claude ask you two things: resume from the saved context? and keep logging this session? |
  68. | **Before you wrap up** | You run `/recall:save`. The **local summarizer** reads `history.md` and (over)writes `context.md`. |
  69. | **…or automatically** | Set `auto_save_context: "on_end"` and `context.md` regenerates every time a session ends — no `/recall:save` needed. |
  70. There is no LLM call anywhere — the summary is produced by **TF-IDF + TextRank**
  71. (extractive summarization) running locally.
  72. ## The summarizer
  73. `scripts/summarizer.py` ranks the most central sentences of your session:
  74. 1. TF-IDF sentence vectors
  75. 2. a cosine-similarity graph between sentences
  76. 3. **TextRank** — PageRank power iteration over that graph — to score sentences
  77. 4. the top *N* are kept in original order
  78. `context.md` wraps that summary with deterministic facts pulled straight from the
  79. transcript and git: the goal (your first ask), files touched, commands run, where
  80. you left off, and `git diff --stat`.
  81. **No installs required.** The whole TF-IDF + TextRank implementation is vendored
  82. in `summarizer.py`. If `numpy` happens to be importable it's used to vectorize the
  83. math (faster on big sessions); if not, an identical pure-Python TextRank runs
  84. instead. Same algorithm, same result — numpy is an optional accelerator, never a
  85. requirement. The save output tells you which path ran.
  86. ## Commands
  87. - `/recall:save` — run the local summarizer → (over)write `context.md`.
  88. - `/recall:show` — print `context.md`.
  89. - `/recall:log` — tail `history.md`.
  90. ## Configuration — `recall.config.json`
  91. Drop this in your project root to override defaults:
  92. | Key | Default | Purpose |
  93. |---|---|---|
  94. | `output_dir` | `".recall"` | Where `history.md` / `context.md` live. |
  95. | `capture_history` | `true` | Append session activity to `history.md`. |
  96. | `auto_save_context` | `"off"` | Regenerate `context.md` when a session ends: `"off"` or `"on_end"`. |
  97. | `summary_sentences` | `8` | How many sentences the summary keeps. |
  98. | `redact` | `true` | Strip obvious secrets before writing the md files. |
  99. | `include_git` | `true` | Add `git diff --stat` + recent commits to `context.md`. |
  100. | `max_input_chars` | `200000` | Cap on text fed to the summarizer (oldest dropped). |
  101. **Pause logging** for a project without editing config: create
  102. `.recall/.capture-paused`. Delete it to resume.
  103. ## Privacy & security
  104. Recall makes **no network calls, uses no API key, and loads no third-party
  105. model.** The summarizer is local Python; the hooks are stdlib-only (numpy is an
  106. optional accelerator). It reads your session transcript and writes only under
  107. `output_dir`. Concretely:
  108. - **No credentials, ever.** The plugin has zero references to API keys, auth,
  109. `ANTHROPIC_*`, or HTTP. If `claude` itself shows *"Invalid API key"*, that's the
  110. CLI's own auth — usually a stale `ANTHROPIC_API_KEY` env var shadowing your
  111. subscription login. `unset ANTHROPIC_API_KEY` (or run `env -u ANTHROPIC_API_KEY
  112. claude …`). It has nothing to do with Recall.
  113. - **Redaction.** A best-effort pass strips common secret shapes (API keys, tokens,
  114. `.env` assignments, PEM keys) before writing, since `context.md` / `history.md`
  115. may be committed. Best-effort, not a guarantee — review before committing.
  116. - **Hardened git.** `git diff`/`log` are run with `core.fsmonitor`,
  117. `diff.external`, hooks, and the pager disabled, so an untrusted cloned repo
  118. can't use its own git config to execute code when Recall reads ground-truth.
  119. Set `include_git: false` to skip git entirely.
  120. - **Confined writes.** `output_dir` is forced to stay inside the project; a
  121. project-shipped config can't redirect writes to an absolute path or `../..`.
  122. - **Scoped transcript.** Recall only reads the transcript for the current
  123. project (matched by cwd); it never falls back to another project's sessions.
  124. - **Trust boundary for shared memory.** `context.md` is injected into the model at
  125. session start. If you **commit `.recall/` as shared team memory**, treat it
  126. like any other shared input: a teammate (or a bad actor with repo write access)
  127. could craft a `context.md` to attempt prompt-injection. SessionStart fences the
  128. content and labels it untrusted data, and Claude asks before relying on it — but
  129. if you don't fully trust who can write the repo, keep `.recall/` git-ignored
  130. (the default).
  131. ## Committing `.recall/`
  132. Both are fine. Commit it for shared team memory, or git-ignore it for personal
  133. memory (`.gitignore` ships ignoring it by default — flip the comment to commit).
  134. ## Install
  135. **From the marketplace** (this repo is its own marketplace):
  136. ```
  137. /plugin marketplace add raiyanyahya/recall
  138. /plugin install recall@recall
  139. ```
  140. **Local dev** (no install step):
  141. ```
  142. claude --plugin-dir /path/to/recall
  143. ```
  144. No `pip install` — the summarizer is vendored and stdlib-only (numpy used as an
  145. optional accelerator if present). Work a session, run `/recall:save`, and open
  146. a fresh session — Recall greets you with where you left off.
  147. ## Other harnesses
  148. Claude Code is Recall's first-class harness — the plugin install above is the
  149. primary, fully supported path, and nothing in this section affects it. But the
  150. memory Recall writes is plain markdown in `.recall/`, not harness state, so
  151. other coding agents can produce and consume the very same files. Harness
  152. support is always **opt-in**: nothing activates unless you explicitly set it
  153. up. A nice consequence: memory is **shared across harnesses** — a Claude Code
  154. user and an opencode user on the same repo write to the same `history.md`,
  155. and either side's `context.md` resumes the other's work.
  156. ### OpenCode
  157. **How plugin installs work in opencode.** Unlike Claude Code, [opencode](https://opencode.ai)
  158. has no plugin marketplace and no in-CLI install command — there's no
  159. `/plugin install` to run inside it. Plugins are loaded from files and config:
  160. anything in a project's `.opencode/plugins/` (or the global
  161. `~/.config/opencode/plugins/`) is auto-loaded at startup, custom commands are
  162. markdown files in `.opencode/commands/`, and session-start context comes from
  163. the `instructions` list in `opencode.json`. Recall plugs into exactly those
  164. mechanisms — a small installer generates the files **once**, and opencode
  165. picks them up automatically from then on.
  166. **Set it up once per project** — not per session, not per machine boot:
  167. ```
  168. git clone https://github.com/raiyanyahya/recall ~/recall
  169. python3 ~/recall/scripts/install.py --opencode --project /path/to/your/project
  170. ```
  171. Keep the clone around — the generated plugin points at it. The only reason to
  172. ever re-run the installer is if you move the clone (or want to uninstall).
  173. The installer writes exactly three things, all inside the target project:
  174. | File | Purpose |
  175. |---|---|
  176. | `.opencode/plugins/recall.ts` | the capture shim, auto-loaded by opencode at startup |
  177. | `.opencode/commands/recall-save.md` | the `/recall-save` command |
  178. | `opencode.json` | adds `.recall/context.md` to `instructions` |
  179. **From then on, every session is automatic:**
  180. - **At session start**, opencode loads `.recall/context.md` (via
  181. `instructions`) — you resume where you left off, no re-explaining.
  182. - **After every turn** (opencode's `session.idle` event), the shim appends new
  183. activity to `.recall/history.md`. It reads the session through
  184. `opencode export` — opencode's public CLI — never its internal storage.
  185. - **Before wrapping up**, run `/recall-save` to regenerate `context.md` with
  186. the local summarizer — or set `auto_save_context: "on_end"` in
  187. `recall.config.json` and it regenerates after every turn on its own.
  188. Same guarantees as the Claude Code path: fully local, no network, no API key;
  189. capture honors `recall.config.json`, `.capture-paused`, and redaction; any
  190. failure is a silent no-op so a session is never affected. Uninstall anytime
  191. with `--opencode --uninstall` (your `.recall/` data stays), and the installer
  192. never overwrites or deletes a file it didn't generate.
  193. Two differences from the Claude Code path to be aware of:
  194. - **Instructions, not fenced data.** opencode loads `context.md` through its
  195. `instructions` mechanism, without the untrusted-data fencing the Claude Code
  196. SessionStart hook applies. If you commit `.recall/` as shared team memory,
  197. only do so with collaborators you trust.
  198. - **Tracks opencode's public CLI** (`session list`, `export`, the plugin
  199. events API), which is the stable surface — but opencode moves fast; if a
  200. release changes these, capture degrades to a silent no-op. File an issue.
  201. ### Codex and others
  202. Not supported yet. The adapter seam (`scripts/harness_opencode.py`,
  203. `--harness` on `make_context.py`) is where a new harness plugs in —
  204. contributions welcome.
  205. ## Development
  206. ```bash
  207. python -m venv .venv && . .venv/bin/activate
  208. pip install pytest ruff bandit numpy # numpy optional
  209. ruff check scripts tests benchmarks # lint
  210. bandit -c pyproject.toml -r scripts # security static analysis
  211. pytest # run the suite (also test without numpy)
  212. python benchmarks/bench.py # perf + quality numbers (human-readable)
  213. python benchmarks/bench.py --check # assert quality invariants (the CI gate)
  214. claude plugin validate . # official manifest validation
  215. ```
  216. `benchmarks/bench.py` is a stdlib-only harness: alongside latency/throughput it
  217. scores the summarizer's salient-sentence selection against lead/tail/random
  218. baselines on a labeled fixture set and checks the numpy and pure-Python cores
  219. select the **same** sentences. `--check` gates those quality invariants (it never
  220. gates wall-clock timings). Redaction quality is covered by the unit suite
  221. (`tests/test_redact.py`), so no secret-shaped fixtures live in the benchmark.
  222. CI (`.github/workflows/`) runs lint + Bandit, the test suite across Python
  223. 3.9–3.13 **with and without numpy** (both summarizer paths), the benchmark
  224. quality gate (both paths), CodeQL, secret scanning, and manifest JSON validation
  225. on every push and PR. See
  226. [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
  227. ## Layout
  228. ```
  229. recall/
  230. ├── .claude-plugin/plugin.json # manifest
  231. ├── hooks/hooks.json # SessionStart (ask/resume) · Stop+SessionEnd (capture)
  232. ├── commands/ # /recall:save · show · log
  233. ├── scripts/
  234. │ ├── summarizer.py # vendored TF-IDF + TextRank (numpy optional)
  235. │ ├── make_context.py # build/overwrite context.md (--harness claude|opencode)
  236. │ ├── capture.py # append session activity to history.md
  237. │ ├── session_start.py # surface context + ask the start questions
  238. │ ├── parse_transcript.py # transcript → events + renderers
  239. │ ├── harness_opencode.py # opencode adapter (public CLI only) + opencode_capture.py
  240. │ ├── install.py # flag-based installer for opt-in harnesses (--opencode)
  241. │ └── config.py · common.py · redact.py
  242. ├── integrations/opencode/ # generated-file templates (plugin shim, /recall-save)
  243. ├── tests/ # pytest suite (summarizer, capture, security, …)
  244. ├── benchmarks/bench.py # perf + quality harness (CI quality gate)
  245. ├── .github/ # CI, CodeQL, secret scan, dependabot
  246. ├── recall.config.json # config template / defaults
  247. ├── pyproject.toml # ruff / pytest / bandit config (no runtime deps)
  248. ├── LICENSE · SECURITY.md · CONTRIBUTING.md
  249. └── .gitignore
  250. ```
  251. ## Contributing & issues
  252. Bugs and ideas are welcome — open an [issue](https://github.com/raiyanyahya/recall/issues/new/choose)
  253. (bug-report and feature templates provided) or a pull request. See
  254. [CONTRIBUTING.md](CONTRIBUTING.md) before submitting, and report security
  255. vulnerabilities privately per [SECURITY.md](SECURITY.md) rather than in a public issue.

Ratings and comments

Sign in to rate this skill.

Sign in

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