{"id":31699405,"url":"https://github.com/vvkmnn/claude-historian","last_synced_at":"2025-10-08T19:43:25.154Z","repository":{"id":304630747,"uuid":"1019286537","full_name":"Vvkmnn/claude-historian","owner":"Vvkmnn","description":"🤖 An MCP server for Claude Code conversation history","archived":false,"fork":false,"pushed_at":"2025-08-25T16:42:50.000Z","size":52240,"stargazers_count":46,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-25T17:38:56.006Z","etag":null,"topics":["anthropic","anthropic-claude","claude","claude-ai","claude-code","claude-mcp","mcp","mcp-sdk","mcp-server","mcp-tools","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-historian","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vvkmnn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T05:19:45.000Z","updated_at":"2025-08-25T16:42:53.000Z","dependencies_parsed_at":"2025-07-14T11:35:26.068Z","dependency_job_id":"248e4a13-1cfc-4761-b42c-0ce977692fae","html_url":"https://github.com/Vvkmnn/claude-historian","commit_stats":null,"previous_names":["vvkmnn/claude-historian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Vvkmnn/claude-historian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vvkmnn%2Fclaude-historian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vvkmnn%2Fclaude-historian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vvkmnn%2Fclaude-historian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vvkmnn%2Fclaude-historian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vvkmnn","download_url":"https://codeload.github.com/Vvkmnn/claude-historian/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vvkmnn%2Fclaude-historian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000703,"owners_count":26082806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","anthropic-claude","claude","claude-ai","claude-code","claude-mcp","mcp","mcp-sdk","mcp-server","mcp-tools","typescript"],"created_at":"2025-10-08T19:43:21.956Z","updated_at":"2025-10-08T19:43:25.140Z","avatar_url":"https://github.com/Vvkmnn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-historian\n\n![claude-historian](demo.gif)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for searching your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (\u0026 [Claude Desktop](https://claude.ai/download)) 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\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![npm version](https://img.shields.io/npm/v/claude-historian.svg)](https://ww.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%3D20-brightgreen)](https://nodejs.org/)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Vvkmnn/claude-historian?utm_source=oss\u0026utm_medium=github\u0026utm_campaign=Vvkmnn%2Fclaude-historian\u0026labelColor=171717\u0026color=FF570A\u0026link=https%3A%2F%2Fcoderabbit.ai\u0026label=CodeRabbit+Reviews)\n[![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude\u0026logoColor=fff)](#)\n\n## install\n\nRequirements:\n\n- [Claude Code](https://claude.ai/code)\n\n```bash\nnpm install -g claude-historian\n```\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\nThat's it; there is **no `npm install` required** as there are no external dependencies or local databases, only search algorithms.\n\nHowever, in the unlikely event that you pull the wrong package / `npx` registry is out of date, you can force resolution issues in certain environments with:\n\n```bash\nnpm install -g claude-historian\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=\u003cquery\u003e\n  \u003e \"How did we fix that Redis connection pooling nightmare?\"\n  \u003e \"Docker container keeps crashing on Kubernetes deployment\"\n  \u003e \"React infinite re-render loop - useEffect dependency hell\"\n\n[⌐□_□] find_file_context filepath=\u003cfilepath\u003e\n  \u003e \"package.json changes that broke everything last month\"\n  \u003e \"When we accidentally committed .env to main branch\"\n  \u003e \"Authentication service refactor - before/after comparison\"\n\n[⌐×_×] get_error_solutions error_pattern=\u003cerror\u003e\n  \u003e \"MODULE_NOT_FOUND - the classic npm/yarn version mismatch\"\n  \u003e \"CORS preflight failing - but only on production Fridays?\"\n  \u003e \"Database deadlock during Black Friday traffic spike\"\n\n[⌐◆_◆] find_similar_queries query=\u003cquery\u003e\n  \u003e \"Database queries slower than my morning coffee brewing\"\n  \u003e \"How to implement error boundaries without losing sanity\"\n  \u003e \"State management: Redux vs Zustand vs just useState\"\n\n[⌐○_○] list_recent_sessions\n  \u003e \"Tuesday debugging marathon: 9pm-3am flaky test hunt\"\n  \u003e \"Performance optimization sprint - reduced bundle 40%\"\n  \u003e \"The great TypeScript migration of 2024\"\n\n[⌐⎚_⎚] find_tool_patterns tool_name=\u003ctool\u003e\n  \u003e \"Read → Edit → Bash combo for rapid prototyping\"\n  \u003e \"When I use Grep vs Task for different searches\"\n  \u003e \"Git operations during feature branch management\"\n```\n\n## methodology\n\nHow [claude-historian](https://github.com/Vvkmnn/claude-historian) [works](https://github.com/Vvkmnn/claude-historian/tree/master/src):\n\n```\n\"docker auth\" query\n      |\n      ├─\u003e Parallel Processing (search.ts:949): 15 projects × 10 files concurrently\n      |   • Promise.allSettled for 6x speed improvement\n      |   • Early termination when sufficient results found\n      |   • Enhanced file coverage with comprehensive patterns\n      |\n      ├─\u003e Enhanced Classification (search.ts:294): implementation → boost tool workflows\n      |   • Workflow detection for tool sequences (Edit → Read → Bash)\n      |   • Semantic boundary preservation (never truncate mid-function)\n      |   • Claude-optimized formatting with rich metadata\n      |\n      ├─\u003e Smart Ranking (search.ts:213):\n      |   • \"Edit workflow (7x successful)\" (2h ago) *****\n      |   • \"Docker auth with context paths\" (yesterday) ****\n      |   • \"Container debugging patterns\" (last week) ***\n      |\n      └─\u003e Return Claude Code optimized results\n```\n\n**Core optimizations:**\n\n- [parallel processing](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L949): `Promise.allSettled` for 6x speed improvement across projects and files\n- [workflow detection](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L984): Captures tool sequences like \"Edit → Read → Bash\" patterns\n- [enhanced file matching](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L704): Comprehensive path variations with case-insensitive matching\n- [intelligent deduplication](https://github.com/Vvkmnn/claude-historian/blob/master/src/search-helpers.ts#L110): Content-based deduplication preserving highest-scoring results\n- [intelligent truncation](https://github.com/Vvkmnn/claude-historian/blob/master/src/formatter.ts#L89): Never truncates mid-function or mid-error\n- [Claude-optimized formatting](https://github.com/Vvkmnn/claude-historian/blob/master/src/formatter.ts#L35): Rich metadata with technical content prioritization\n\n**Search strategies:**\n\n- **[JSON streaming parser](https://en.wikipedia.org/wiki/JSON_streaming)** ([parseJsonlFile](https://github.com/Vvkmnn/claude-historian/blob/master/src/parser.ts#L16)): Reads Claude Code conversation files on-demand without full deserialization\n- **[LRU caching](\u003chttps://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)\u003e)** ([messageCache](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L13)): In-memory cache with intelligent eviction for frequently accessed conversations\n- **[TF-IDF inspired scoring](https://en.wikipedia.org/wiki/Tf%E2%80%93idf)** ([calculateRelevanceScore](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L609)): Term frequency scoring with document frequency weighting for relevance\n- **[Query classification](https://en.wikipedia.org/wiki/Text_classification)** ([classifyQueryType](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L554)): Naive Bayes-style classification (error/implementation/analysis/general) with adaptive limits\n- **[Edit distance](https://en.wikipedia.org/wiki/Edit_distance)** ([calculateQuerySimilarity](https://github.com/Vvkmnn/claude-historian/blob/master/src/search-helpers.ts#L157)): Fuzzy matching for technical terms and typo tolerance\n- **[Exponential time decay](https://en.wikipedia.org/wiki/Exponential_decay)** (getTimeRangeFilter): Recent messages weighted higher with configurable half-life\n- **[Parallel file processing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled)** ([getErrorSolutions](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L838)): Concurrent project scanning with early termination for 0.8s response times\n- **[Workflow pattern recognition](https://en.wikipedia.org/wiki/Sequential_pattern_mining)** ([getToolPatterns](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L937)): Detects tool usage sequences and related workflows for learning\n- **[Enhanced file context](\u003chttps://en.wikipedia.org/wiki/Path_(computing)\u003e)** ([findFileContext](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L666)): Multi-project search with comprehensive path matching\n- **[Content-aware truncation](https://en.wikipedia.org/wiki/Text_segmentation)** ([smartTruncation](https://github.com/Vvkmnn/claude-historian/blob/master/src/formatter.ts#L46)): Intelligent content boundaries over arbitrary character limits\n- **[Technical content prioritization](https://en.wikipedia.org/wiki/Information_extraction)** ([formatSearchResults](https://github.com/Vvkmnn/claude-historian/blob/master/src/formatter.ts#L248)): Code blocks, errors, and file paths get full preservation\n- **[Query similarity clustering](https://en.wikipedia.org/wiki/Cluster_analysis)** ([findSimilarQueries](https://github.com/Vvkmnn/claude-historian/blob/master/src/search.ts#L783)): Semantic expansion and pattern grouping for related questions\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 \u0026\u0026 cd claude-historian\nnpm install \u0026\u0026 npm run build\nnpm test\n```\n\n**Package requirements:**\n\n- **Node.js**: \u003e=20.0.0 (ES modules support)\n- **npm**: \u003e=10.0.0 (package-lock v3)\n- **Runtime**: Only `@modelcontextprotocol/sdk` dependency\n- **Zero external dependencies** for production deployment\n- **Optimized**: 50% token reduction with parallel processing\n\n**Development workflow:**\n\n```bash\nnpm run build          # TypeScript compilation with executable permissions\nnpm run dev            # Watch mode with tsc --watch\nnpm run lint           # ESLint code quality checks\nnpm run format         # Prettier formatting\nnpm run type-check     # TypeScript validation without emit\nnpm run prepublishOnly # Pre-publish validation (build + lint + format)\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://modelcontextprotocol.io/specification) 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- [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) - NPM package development guide\n\n## desktop\n\nClaude Desktop support is currently blocked by [LevelDB locks](https://github.com/Level/level#open) and [Electron sandboxing](https://www.electronjs.org/docs/latest/tutorial/sandbox). You will still search Claude Desktop from Claude Code, but **only when the Claude app is closed**.\n\nA DXT package and build is available for future compatibility; further investigations are ongoing. Feel free to test with it.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvkmnn%2Fclaude-historian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvvkmnn%2Fclaude-historian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvkmnn%2Fclaude-historian/lists"}