{"_id":"claude-historian","_rev":"3-d26a4ddc8a0098dc4505673e134dabd4","name":"claude-historian","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"claude-historian","version":"1.0.0","keywords":["claude","claude-code","mcp","mcp-server","history","search","conversation","ai","terminal","cli","npx","zero-install"],"author":{"name":"Claude Code Community"},"license":"MIT","_id":"claude-historian@1.0.0","maintainers":[{"name":"vvkmnn","email":"vvkmnn+npm@gmail.com"}],"homepage":"https://github.com/claude-code/claude-historian#readme","bugs":{"url":"https://github.com/claude-code/claude-historian/issues"},"bin":{"claude-historian":"dist/index.js"},"dist":{"shasum":"c3078566c58f4604ec44411f8a6863cc8c0fb28f","tarball":"https://registry.npmjs.org/claude-historian/-/claude-historian-1.0.0.tgz","fileCount":31,"integrity":"sha512-7CXAIYZmmqeqLz1ZKjmnvQXzrpNQnb4ac+FsilXp6pfGmqp0tyCbf7XqozFWkFkUHD4NmTcNlMpR+t9Jf09ytQ==","signatures":[{"sig":"MEUCIQD6n4ltLChE5eUI88+NkSlwbT7mhaiMChOGNDVn69CcCAIgXED4tYM6hpcYoWvn4EJT/43uuPDbRN0r5NVQo7NKE9A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":161603},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"funding":{"url":"https://github.com/sponsors/claude-code","type":"github"},"scripts":{"dev":"tsc --watch","test":"echo \"No tests yet\" && exit 0","build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"vvkmnn","email":"vvkmnn+npm@gmail.com"},"repository":{"url":"git+https://github.com/claude-code/claude-historian.git","type":"git"},"_npmVersion":"10.9.2","description":"Zero-install MCP server for intelligent Claude Code conversation history search with beautiful terminal output","directories":{},"_nodeVersion":"22.15.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/claude-historian_1.0.0_1752469853864_0.7530493936858955","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to claude-historian-mcp. Install: npm install -g claude-historian-mcp"},"1.0.1":{"name":"claude-historian","version":"1.0.1","keywords":["claude","claude-code","mcp","mcp-server","history","search","conversation","ai","terminal","cli","npx","zero-install"],"author":{"name":"Claude Code Community"},"license":"MIT","_id":"claude-historian@1.0.1","maintainers":[{"name":"vvkmnn","email":"vvkmnn+npm@gmail.com"}],"homepage":"https://github.com/Vvkmnn/claude-historian#readme","bugs":{"url":"https://github.com/Vvkmnn/claude-historian/issues"},"bin":{"claude-historian":"dist/index.js"},"dist":{"shasum":"fb5da6806e2ef80c15d5f51e9c6c732402c8378e","tarball":"https://registry.npmjs.org/claude-historian/-/claude-historian-1.0.1.tgz","fileCount":35,"integrity":"sha512-xNcyQig48fOe4/dSb+uNgvjmoHCijBj31E69dFS5BzxZNf6K8IQwimXooWpjJ4Qm74UuPB5WQGUKPDM1pcw1ng==","signatures":[{"sig":"MEYCIQDMO8KGzHHQ1p9UI3hcFnpadt1i3NyGDFiynn/IhAskPQIhAOP9xP3fDEUkWmQna8oPkl3QOoG3Vj7tS93TvjLkC1VO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":184248},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"npm":">=10.0.0","node":">=20.0.0"},"funding":{"url":"https://github.com/sponsors/Vvkmnn","type":"github"},"gitHead":"516feafc1540ccaa34d921a0a7c3feb56c15c9ab","scripts":{"dev":"tsc --watch","lint":"eslint .","test":"node dist/index.js --help && npm run type-check","build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","format":"prettier --write src","lint:fix":"eslint . --fix","type-check":"tsc --noEmit","format:check":"prettier --check src","prepublishOnly":"npm run build && npm run lint && npm run format:check"},"_npmUser":{"name":"vvkmnn","email":"vvkmnn+npm@gmail.com"},"repository":{"url":"git+https://github.com/Vvkmnn/claude-historian.git","type":"git"},"_npmVersion":"10.9.2","description":"an MCP server for Claude Code conversation history ","directories":{},"_nodeVersion":"22.15.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.18.0","prettier":"^3.4.2","@eslint/js":"^9.18.0","typescript":"^5.7.0","@types/node":"^22.0.0","semantic-release":"^22.0.12","typescript-eslint":"^8.18.0","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/claude-historian_1.0.1_1752522824961_0.8431638745009629","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to claude-historian-mcp. Install: npm install -g claude-historian-mcp"}},"time":{"created":"2025-07-14T05:10:53.863Z","modified":"2025-12-09T06:16:35.790Z","1.0.0":"2025-07-14T05:10:54.070Z","1.0.1":"2025-07-14T19:53:45.169Z"},"bugs":{"url":"https://github.com/Vvkmnn/claude-historian/issues"},"author":{"name":"Claude Code Community"},"license":"MIT","homepage":"https://github.com/Vvkmnn/claude-historian#readme","keywords":["claude","claude-code","mcp","mcp-server","history","search","conversation","ai","terminal","cli","npx","zero-install"],"repository":{"url":"git+https://github.com/Vvkmnn/claude-historian.git","type":"git"},"description":"an MCP server for Claude Code conversation history ","maintainers":[{"name":"vvkmnn","email":"vvkmnn+npm@gmail.com"}],"readme":"# claude-historian\n\n![claude-historian](demo.gif)\n\nA Model Context Protocol (MCP) server for searching your Claude Code conversation history. Find past solutions, track file changes, and learn from previous work.\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![npm version](https://img.shields.io/npm/v/claude-historian.svg)](https://www.npmjs.com/package/claude-historian)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Vvkmnn/claude-historian?utm_source=oss&utm_medium=github&utm_campaign=Vvkmnn%2Fclaude-historian&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)\n\n## install\n\nRequirements:\n\n- [Claude Code](https://claude.ai/code)\n\nThat's it. No `npm install` needed; thare are no external dependencies or local databases; only search algorithms.\n\n**From shell:**\n\n```bash\nclaude mcp add claude-historian -- npx claude-historian\n```\n\n**From inside Claude** (restart required):\n\n```\nAdd this to our global mcp config: npx claude-historian\n\nInstall this mcp: https://github.com/Vvkmnn/claude-historian\n```\n\n**From any manually configurable `mcp.json`**: (Cursor, Windsurf, etc.)\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-historian\": {\n      \"command\": \"npx\",\n      \"args\": [\"claude-historian\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n## features\n\n[MCP server](https://modelcontextprotocol.io/) that gives Claude access to your conversation history. Fast search with smart prioritization.\n\nRuns locally (with cool shades `[⌐■_■]`):\n\n```\n[⌐■_■] search_conversations query=<query>\n  > \"How did we fix that Redis connection pooling nightmare?\"\n  > \"Docker container keeps crashing on Kubernetes deployment\"\n  > \"React infinite re-render loop - useEffect dependency hell\"\n\n[⌐□_□] find_file_context filepath=<filepath>\n  > \"package.json changes that broke everything last month\"\n  > \"When we accidentally committed .env to main branch\"\n  > \"Authentication service refactor - before/after comparison\"\n\n[⌐×_×] get_error_solutions error_pattern=<error>\n  > \"MODULE_NOT_FOUND - the classic npm/yarn version mismatch\"\n  > \"CORS preflight failing - but only on production Fridays?\"\n  > \"Database deadlock during Black Friday traffic spike\"\n\n[⌐◆_◆] find_similar_queries query=<query>\n  > \"Database queries slower than my morning coffee brewing\"\n  > \"How to implement error boundaries without losing sanity\"\n  > \"State management: Redux vs Zustand vs just useState\"\n\n[⌐○_○] list_recent_sessions\n  > \"Tuesday debugging marathon: 9pm-3am flaky test hunt\"\n  > \"Performance optimization sprint - reduced bundle 40%\"\n  > \"The great TypeScript migration of 2024\"\n\n[⌐⎚_⎚] find_tool_patterns tool_name=<tool>\n  > \"Read → Edit → Bash combo for rapid prototyping\"\n  > \"When I use Grep vs Task for different searches\"\n  > \"Git operations during feature branch management\"\n```\n\n## methodology\n\nHow claude-historian works ([source](https://github.com/Vvkmnn/claude-historian/tree/main/src)):\n\n```\n\"docker auth\" query\n      |\n      ├─> Classify: implementation query -> boost tool examples\n      |\n      ├─> Stream & Filter:\n      |   • Summary messages -> priority queue *****\n      |   • Tool usage context -> high value ****\n      |   • Error solutions -> targeted ***\n      |\n      ├─> Smart Ranking:\n      |   • \"Fixed Docker auth with Read tool\" (2h ago) *****\n      |   • \"OAuth implementation approach\" (yesterday) ****\n      |   • \"Container auth debug\" (last week) ***\n      |\n      └─> Return Claude Code optimized results\n```\n\n**Pure streaming architecture using:**\n\n- **[JSON streaming parser](https://en.wikipedia.org/wiki/Streaming_JSON)**: Reads Claude Code conversation files on-demand without full deserialization\n- **[LRU caching](<https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)>)**: In-memory cache with intelligent eviction for frequently accessed conversations\n- **[TF-IDF inspired scoring](https://en.wikipedia.org/wiki/Tf%E2%80%93idf)**: Term frequency scoring with document frequency weighting for relevance\n- **[Query classification](https://en.wikipedia.org/wiki/Text_classification)**: Naive Bayes-style classification (error/implementation/analysis/general) with adaptive limits\n- **[Edit distance](https://en.wikipedia.org/wiki/Edit_distance)**: Fuzzy matching for technical terms and typo tolerance\n- **[Exponential time decay](https://en.wikipedia.org/wiki/Exponential_decay)**: Recent messages weighted higher with configurable half-life\n\n**File access:**\n\n- Reads from: `~/.claude/conversations/`\n- Zero persistent storage or indexing\n- Never leaves your machine\n\n## development\n\n```bash\ngit clone https://github.com/vvkmnn/claude-historian && cd claude-historian\nnpm install && npm run build\nnpm test\n```\n\nContributing:\n\n- Please fork the repository and create feature branches\n- Test with large conversation histories before submitting PRs\n- Follow TypeScript strict mode and [MCP protocol](https://spec.modelcontextprotocol.io/) standards\n\nLearn from examples:\n\n- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations\n- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices\n\n## license\n\n[MIT](LICENSE)\n\n---\n\n![Claude Fauchet](https://upload.wikimedia.org/wikipedia/commons/thumb/b/bf/Claude_Fauchet_par_Thomas_de_Leu.jpg/336px-Claude_Fauchet_par_Thomas_de_Leu.jpg)\n\n_Claude Fauchet (1744-1793), French Historian_\n","readmeFilename":"README.md"}