Skip to content
Back to search

session-knowledge

Turn your Claude Code session history into a searchable local knowledge base — 13 MCP tools, pure stdlib, nothing leaves your machine

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/nameforjt-afk--session-knowledge/badge.svg)](/listings/nameforjt-afk--session-knowledge)

HTML

<a href="/listings/nameforjt-afk--session-knowledge"><img src="/api/listings/nameforjt-afk--session-knowledge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 247 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # session-knowledge
  2. [![Tests](https://github.com/nameforjt-afk/session-knowledge/actions/workflows/tests.yml/badge.svg)](https://github.com/nameforjt-afk/session-knowledge/actions/workflows/tests.yml)
  3. ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  5. **Claude Code's memory is scoped per project directory. Your history isn't.**
  6. Every session you've ever run is already on disk in `~/.claude/projects/**/*.jsonl` —
  7. every decision, every command that worked, every credential you pasted. But open a
  8. session in a different directory and none of it is reachable. You re-ask questions you
  9. already answered, and re-implement integrations you already wrote.
  10. This indexes all of it and hands Claude 13 MCP tools to search it. You just ask normally.
  11. > *What was the retry logic in that deploy script?*
  12. > *Which DATABASE_URL did I actually use for staging?*
  13. > *Before I write the Stripe integration — has anyone here already done payment auth?*
  14. Pure Python standard library. No third-party dependencies, no embeddings, no API calls,
  15. nothing leaves your machine.
  16. ```bash
  17. git clone https://github.com/nameforjt-afk/session-knowledge.git
  18. cd session-knowledge
  19. bash install.sh
  20. ```
  21. Restart Claude Code. Done.
  22. ---
  23. ## ⚠️ Read this before installing
  24. The index lives in `~/.claude/session-index/` and **it contains plaintext credentials
  25. scraped from your sessions.** That is the precondition for "which key did I use here"
  26. to work at all.
  27. **Never commit that directory, never sync it to cloud storage, never send it to anyone.**
  28. This repo's `.gitignore` covers the default location, but if you relocate it that's on you.
  29. The full-text index itself is redacted: common credential shapes (API keys, Bearer
  30. tokens, JWTs, GitHub PATs, passwords inside connection strings) are replaced with
  31. `⟦SECRET:fingerprint⟧` before they are written. Plaintext lives only in `vault.db`
  32. at mode 0600, and only an explicit `creds get` returns it.
  33. The transcript and code indexes still contain sensitive local context even after
  34. redaction. The index directory is restricted to mode 0700; every generated SQLite
  35. database, WAL/SHM sidecar, and refresh log is restricted to mode 0600.
  36. Redaction is pattern matching, not magic. Custom-format secrets can slip through.
  37. `verify-redaction` spot-checks for leaks.
  38. ---
  39. ## What it actually solves
  40. Four things, in rough order of how often they save you:
  41. **1. "Have I already built this?"** — Search by *external service*, not by function name.
  42. `grep` only works if you already know the string to search for (you need to know it's
  43. `tenant_access_token` before you can grep for Feishu auth). Capability tags don't
  44. require that.
  45. **2. "How did we decide this?"** — The rationale is buried in thousands of past
  46. instructions. Full-text search over them, filterable to just your own instructions.
  47. **3. "How did that command go again?"** — Every Bash and MCP call, with arguments and
  48. results. Filter to only the ones that *failed*, to recall the traps.
  49. **4. "Which value does this key take?"** — Same variable name routinely has several
  50. real values (multiple apps, dev vs prod, two tables). It returns all candidates ranked,
  51. with the call site each came from, rather than silently picking one.
  52. ---
  53. ## Usage
  54. ### Day to day: nothing
  55. A hook refreshes the index incrementally on each Claude Code start (async, non-blocking,
  56. usually 1–2s). Ask questions normally; Claude reaches for the tools on its own.
  57. When an upgrade changes parsing, redaction, or tokenization, the next refresh performs one
  58. automatic full rebuild and then returns to incremental updates.
  59. Code parser and capability-rule upgrades likewise trigger one automatic full code-index
  60. rebuild, preventing unchanged source files from retaining stale symbols or tags.
  61. Deleting a transcript removes its searchable text, tool calls, metadata, and session-only
  62. credential observations on the next refresh. Credentials that still occur in another live
  63. transcript remain available.
  64. ### CLI
  65. ```bash
  66. python3 -m sessionmcp.cli index # incremental refresh
  67. python3 -m sessionmcp.cli stats # index health check
  68. python3 -m sessionmcp.cli search "deploy timeout" # full text (multi-word = AND)
  69. python3 -m sessionmcp.cli search "pricing" --kind user_instruction
  70. python3 -m sessionmcp.cli tool "docker build" # past commands and API calls
  71. python3 -m sessionmcp.cli tool "stripe" --errors # only the ones that failed
  72. python3 -m sessionmcp.cli timeline "that migration" # reconstruct how it unfolded
  73. python3 -m sessionmcp.cli synth "rate limiting" # cross-session material pack
  74. python3 -m sessionmcp.cli evolution "auth design" # how a decision changed over time
  75. python3 -m sessionmcp.cli code find --capability stripe # who implemented payment auth
  76. python3 -m sessionmcp.cli code find send_message # by symbol name
  77. python3 -m sessionmcp.cli code dup # duplicate-implementation report
  78. python3 -m sessionmcp.cli creds list # variable names only, never values
  79. python3 -m sessionmcp.cli creds get DATABASE_URL # all candidates, ranked
  80. python3 -m sessionmcp.cli creds get X --masked # masked form only
  81. python3 -m sessionmcp.cli verify-redaction # confirm no plaintext in the index
  82. ```
  83. **Search is AND. More words means fewer hits.** Use the 2–3 words you would actually
  84. have typed back then, not a sentence.
  85. ### The fake-credential problem
  86. Not every "credential" in your history is real. Doc examples, error snippets, values
  87. someone made up mid-discussion — all get extracted, and they look exactly like the real
  88. thing. A fake in your candidate list is worse than no record at all: it looks perfectly
  89. plausible, so you use it.
  90. Blacklist it permanently:
  91. ```bash
  92. python3 -m sessionmcp.cli creds forget --fingerprint <fp> --reason "doc example"
  93. ```
  94. Deleting alone does nothing — the index re-scans daily and the value comes right back.
  95. `forget` is delete **plus** blacklist.
  96. ---
  97. ## The 13 MCP tools
  98. | | |
  99. |---|---|
  100. | `search_sessions` | full-text search across every session |
  101. | `get_session` | page through one session's full transcript |
  102. | `list_sessions` | session metadata (title, project, date, turns) |
  103. | `get_timeline` | chronological reconstruction of one topic |
  104. | `synthesize_topic` | curated excerpts across sessions, for summarizing |
  105. | `track_evolution` | how a decision or standard changed, bucketed by month |
  106. | `find_tool_call` | past Bash/MCP calls with arguments; `errors_only` to recall traps |
  107. | `find_implementation` | existing code by symbol **or by external-service tag** |
  108. | `list_duplication` | what got implemented N times, and which "projects" are forks |
  109. | `list_credentials` | variable-name registry — never returns values |
  110. | `get_credential` | the actual values, all candidates ranked by trustworthiness |
  111. | `lookup_secret` | resolve a `⟦SECRET:fp⟧` fingerprint back to its variable name |
  112. | `index_stats` | coverage and freshness |
  113. ---
  114. ## How it works
  115. ```
  116. ~/.claude/projects/**/*.jsonl transcripts Claude Code already writes
  117. ↓ single pass
  118. ┌────────┴────────┐
  119. index side credential side
  120. redacted → FTS5 KEY=VALUE → vault.db (0600)
  121. ↓ ↓
  122. index.db vault.db code.db
  123. full text credential symbols +
  124. registry capability tags
  125. ```
  126. CJK search uses bigram pre-tokenization. FTS5's built-in trigram cannot match two-character
  127. Chinese words (measured: common two-char terms returned nothing), and `unicode61` doesn't
  128. segment CJK at all. So CJK text is expanded into adjacent character pairs at write time and
  129. the query is expanded the same way — exact matches work, still on the FTS5 index, BM25
  130. ranking preserved.
  131. ---
  132. ## Configuration
  133. Most of it needs none. To tune, edit `sessionmcp/config.py`:
  134. | Setting | What it does |
  135. |---|---|
  136. | `CODE_CAPABILITY_PATTERNS` | **The one worth editing.** Service tags that drive "find existing implementations by service". Drop the ones you don't use, add yours |
  137. | `PRIVATE_TITLES` | Session titles to exclude from search and retrieval, exact match |
  138. | `_PRIVATE_KEYWORDS` | Heuristic for personal content; matching sessions are hidden from search and retrieval |
  139. | `CODE_PROJECT_*` | Which directories the code index scans (auto-derived by default) |
  140. ### Which directories get code-indexed
  141. Auto-derived: working directories with **≥2 sessions** in the last 45 days, top 30 by
  142. session count. Not hard-coding a list is deliberate — a hard-coded list goes stale
  143. silently as projects come and go, and is entirely wrong on a new machine.
  144. If you're new to Claude Code and every project has exactly one session, this derives an
  145. empty list and the code index scans nothing. Override:
  146. ```bash
  147. export SESSION_KNOWLEDGE_PROJECT_DIRS="~/proj-a:~/proj-b"
  148. ```
  149. ### Claiming a canonical implementation
  150. `~/.claude/knowledge/canonical.json` lets you declare which file is the canonical
  151. implementation of a capability. The generator reads it and never overwrites it, so daily
  152. refreshes won't clobber your call. When the same logic shows up a third time, claiming
  153. one beats copying it a fourth.
  154. ---
  155. ## Uninstall
  156. ```bash
  157. bash uninstall.sh # remove MCP + hook, keep the index
  158. bash uninstall.sh --purge # remove the index too
  159. ```
  160. ---
  161. ## Known limits
  162. - **Claude Code transcripts only** (`~/.claude/projects/**/*.jsonl`). Not Cursor, not Copilot.
  163. - **Redaction is pattern matching.** Common shapes are covered; custom formats can leak.
  164. Run `verify-redaction` periodically.
  165. - **Code index reads Python/JS/TS only** (`.py .js .ts .tsx .mjs .jsx`).
  166. Files changed during reading are skipped and the refresh reports failure so a later run
  167. can retry. This update triggers a one-time full code reindex to repair cached snapshots.
  168. - **JS/TS extraction is partial.** Regex misses some arrow functions and typed declarations.
  169. Fork suggestions use shared paths and line counts; compare source before archiving copies.
  170. - **First full index** of a few hundred sessions takes 1–3 minutes. Incremental after that is 1–2s.
  171. - **Python 3.10+**, with FTS5 compiled into the bundled sqlite3. The system Python on macOS
  172. sometimes lacks it — install from python.org or `brew install python`.
  173. [中文文档](README.zh-CN.md)
  174. ## Contributing and security
  175. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. Never
  176. include real transcripts or credentials in public reports. Potential vulnerabilities
  177. should be reported privately according to [SECURITY.md](SECURITY.md).
  178. Release history is recorded in [CHANGELOG.md](CHANGELOG.md).
  179. ## License
  180. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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