session-knowledge MCP
Local search across your whole Claude Code session history: decisions, commands, variable values and code you already wrote, through 13 MCP tools
- 306 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The index keeps keys and passwords from your sessions in plaintext, and get_credential hands them to the agent
- The SessionStart hook runs the index refresh script on every Claude Code start
- The server reads every Claude Code transcript and the source files from the chosen directories
Install
- Works in
Manual install
git clone https://github.com/nameforjt-afk/session-knowledge.git && cd session-knowledge && bash install.shThe script registers the MCP server and the SessionStart hook. Restart Claude Code afterwards. Python 3.10 or newer is required.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The index keeps keys and passwords from your sessions in plaintext, and get_credential hands them to the agent
- The SessionStart hook runs the index refresh script on every Claude Code start
- The server reads every Claude Code transcript and the source files from the chosen directories
This is third-party code. Review the repository files before installing.
What it does
Claude Code's memory is tied to a project directory, while the session history sits on disk in ~/.claude/projects/**/*.jsonl and is out of reach from another directory. session-knowledge indexes all of those files into local SQLite databases with full-text search and gives the agent 13 MCP tools. You ask as usual, for example how the retry logic in a deploy script worked, and Claude reaches for the right tool on its own. There are four jobs. Code is indexed with capability tags, so you can search by external service and find who already wrote payment authorization. Search over your past instructions recovers decisions and shows how a standard changed month by month. Past Bash and MCP calls come back with arguments and results, with a filter for failures only. The environment variable registry answers a question about the staging DATABASE_URL with every candidate and its call site. The index updates itself: a SessionStart hook runs an incremental refresh on every Claude Code start, usually in one or two seconds. The whole project uses the Python standard library, with no dependencies and no external APIs.
Who it is for. For developers who work in Claude Code across many projects and are tired of re-explaining past decisions and rewriting integrations they already built.
Good fit when
- You want to recall why a given authentication scheme was chosen and find your instructions on the topic across several months
- Before a new Stripe integration you want to know whether you already wrote payment authorization in another project
- You need a command that worked once, or a list of traps from failed docker and API calls
- You need the value of an environment variable from a past session, with every variant per app and environment
- You want a report of duplicate implementations across your projects and which of them are forks of each other
Not a fit when
- You work in Cursor or Copilot: only Claude Code transcripts are indexed
- Copies of secrets from sessions must not be stored on the machine: the server deliberately keeps them in a local store
- You need code search for languages other than Python, JavaScript and TypeScript: the code index reads only those files
Example request
Find in my past sessions which DATABASE_URL value I used for staging and show where it was calledMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
SESSION_KNOWLEDGE_PROJECT_DIRS- Colon-separated project directories for the code index
Limitations
The index lives in ~/.claude/session-index/ and holds, in plaintext, the credentials you pasted into sessions: without that, the question of which key was used cannot work. Never commit that directory, sync it to the cloud or send it to anyone. Redaction of the full-text index relies on patterns, so custom secret formats can slip through. Check the result with verify-redaction.
It needs Python 3.10 or newer with FTS5 in sqlite3 (the system Python on macOS sometimes lacks it). The first full index of a few hundred sessions takes 1–3 minutes. JS and TS parsing is partial and regex-based.
How to disable. Run `bash uninstall.sh` in the project directory: it removes the MCP registration and the SessionStart hook and keeps the index. `bash uninstall.sh --purge` also deletes the index along with the secret store.
FAQ
How do I install session-knowledge in Claude Code?
Clone the repository, run `bash install.sh` in its directory and restart Claude Code. The script registers the session-knowledge MCP server in ~/.claude.json and adds the refresh hook to settings.json.
Where are the secrets from my sessions stored?
Plaintext values live only in vault.db with 0600 permissions, and the index directory is locked to 0700. In the full-text index secrets are replaced with markers like ⟦SECRET:fingerprint⟧. Only an explicit get_credential call returns a value, for example creds get on the command line.
What do I do with fake keys in the candidate list?
Made-up values from documentation examples and discussions also land in the index. `python3 -m sessionmcp.cli creds forget --fingerprint <fingerprint> --reason "doc example"` deletes a value and blocklists it. Without the blocklist, the daily scan brings the value back.
How is session search better than plain grep?
Grep works when you already know the string, such as tenant_access_token. Capability tags let you search by external service, and the full-text index with BM25 covers every session, including Chinese text, which is split into character pairs.
How do I set the code index directories by hand?
By default it takes working directories with two or more sessions in the last 45 days, up to 30 of them. For newcomers with single sessions that gives an empty list, so set SESSION_KNOWLEDGE_PROJECT_DIRS, for example "~/proj-a:~/proj-b".
Discussion
No questions or reviews yet.
Related
MCP serversA local dashboard for Claude Code sessions: timelines, token costs, tools, agents, skills and live sessions
The Supermemory plugin for Claude Code: persistent memory across sessions with automatic prompt recall, conversation capture and a codebase index
Local memory for agents: stores conversations and project files verbatim and retrieves them with semantic search over MCP
An environment for Claude Code that keeps context across sessions via hooks, ledgers and handoffs, orchestrates agents and saves tokens
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
CLI and TUI that search the local session history of Claude Code, Codex, Cursor, Gemini CLI and other agents, with a --robot mode for the agents themselves
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| session-knowledge (this entry) | no | not required | 306 | |
| deja-vu | no | 1,335 | indexes sessions from 38 agents and searches them, with no variable registry or search for finished code | |
| Obelisk | no | 700 | gathers agent session history into one SQLite file for queries | |
| Context Mode | no | not required | 32,835 | keeps large tool output out of the context window and does not index past sessions |
README in short
The README warns about plaintext secrets up front. Command-line commands, a diagram of the indexes, configuration, uninstall and known limits follow.