Claudex
Search Claude Code history and give it durable memory across sessions.
- Source repo
- kunwar-shah/claudex
- Stars
- ★ 97
- Last updated
- 4mo ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 69/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer working across several Claude Code projects needs to recover an earlier migration plan, command, or implementation detail from all local sessions.
- Not a fit if
- Teams not using Claude Code or without ~/.claude/projects history
- Users who need live search with automatic index updates
- Production teams needing multi-user sync or backup/migration
- Source review
- 69/100 · Some gaps
What does this agent do, and when should you use it?
Claudex is a self-hosted, full-stack conversation viewer, search service, and memory layer for Claude Code. Its Fastify backend scans JSONL sessions under ~/.claude/projects, indexes them with SQLite FTS5, and exposes project, session, search, export, and health APIs. A React interface provides conversation browsing, analytics, favorites, and specialized rendering for Markdown, code, diffs, JSON, and tool activity. The included stdio MCP server supplies Claude Code with 10 tools, three prompts, and structured memories carrying priority, confidence, and TTL metadata. It can run from npm, source, or Docker; in production, Fastify serves both the API and built frontend on port 3400 by default.
fileScanner.js discovers projects and sessions from PROJECT_ROOT, which defaults to ~/.claude/projects, while templateDetector.js and messageParser.js detect and parse V1, V2-Mixed, and V3 records. searchIndexer.js builds a SQLite FTS5 index, and searchDatabase.js supports highlighted queries filtered by project, session, role, date range, and content. The web client uses components including ProjectSelector.jsx, SessionList.jsx, ConversationThread.jsx, ClaudeMessageRenderer.jsx, and SearchPage.jsx to display conversations, tool usage, file operations, and analytics. Fastify routes such as /api/projects, /api/search, /api/search/index/build, /api/search/index/status, /api/export/session/:projectId/:sessionId, and /api/health expose the same data programmatically and produce JSON, HTML, or TXT exports. Over stdio, the MCP entry point provides project context, session search, conversation retrieval, and structured-memory CRUD, with minimal, standard, and full context-detail levels.
- A developer working across several Claude Code projects needs to recover an earlier migration plan, command, or implementation detail from all local sessions.
- A team wants Claude Code to recall established architecture decisions, coding conventions, and known error patterns when a fresh session begins.
- A QA engineer needs to inspect complete conversations, tool activity, and file operations, then export relevant sessions as JSON, HTML, or TXT.
- A researcher wants to filter Claude Code history by role, project, date, and content and examine message-distribution or session statistics.
- A user wants a locally hosted browser for Claude Code records while mounting the source project-history directory read-only in Docker.
- A long-time Claude Code user has V1, V2-Mixed, V3, or transitional history files and needs automatic format detection.
How do you install or deploy this agent?
Install Node.js 18+, npm, and Claude Code, and ensure Claude Code has created history under ~/.claude/projects. The recommended installation is:
npm install -g @kunwarshah/claudexclaudex
You can instead run npx @kunwarshah/claudex, select another port with claudex --port 3500, or select another history root with claudex --project-root ~/my-claude-projects. Register the persistent-memory MCP server with:
claude mcp add --transport stdio claudex -- claudex-mcpBefore the first search, use “Rebuild Index” in the Search page or run:
curl -X POST http://localhost:3400/api/search/index/buildFor a source install, run git clone https://github.com/kunwar-shah/claudex.git, enter the repository, install dependencies in the root, server, and client directories with npm install, and start with npm run dev. No API key or hosted-service credential is documented.
How do you use this agent?
Start claudex, then use the browser interface to select projects and sessions, read messages, view analytics, or rebuild the search index. The service and index can be checked from the shell:
curl http://localhost:3400/api/health
curl http://localhost:3400/api/search/index/statusA filtered full-text query can be submitted with:
curl -X POST http://localhost:3400/api/search -H "Content-Type: application/json" -d '{"q":"database","projectId":"my-project","role":"user","limit":20,"offset":0}'Export a session through /api/export/session/:projectId/:sessionId?format=json, changing format to html or txt when needed. Rebuild the index through the UI or POST /api/search/index/build after new conversations arrive. Once the MCP server is registered, Claude Code can access historical context and structured memories; /recall, /catchup, and /history are the three documented prompts.
What are this agent's strengths and limitations?
- Combines a web conversation viewer, SQLite FTS5 search, and a Claude Code MCP memory service in one local application.
- Explicitly handles V1, V2-Mixed, V3, and mixed migration states instead of requiring a single history schema.
- Search includes project, session, role, and date filtering plus result highlighting, going beyond raw JSONL browsing.
- Structured memories support priority from 1 to 10, confidence, TTL expiration, and three context-detail levels.
- Offers npm, source, and multi-architecture Docker deployment; the Docker setup uses a read-only history mount, health checks, and log rotation.
- Exports sessions as JSON, HTML, or TXT and exposes scriptable HTTP endpoints.
- The data source and MCP integration are Claude Code-specific; there is no documented adapter for other assistants or model platforms.
- Search is not live: the index must be rebuilt initially and after new conversations, while WebSocket updates remain a roadmap item.
- Local operation requires Node.js 18+, npm, readable Claude Code history, and a writable location for the SQLite database.
- Development mode uses separate ports 3000 and 3400, so port conflicts and filesystem permissions can require manual remediation.
- The token-cost calculator and custom-parser plugin system are not implemented yet.
- Structured memory creates additional local database state; the source documents persistent volumes but not backup, migration, or multi-user synchronization procedures.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claudex This agent | 69 · Some gaps | CLIFree | ★ 97 | 4mo ago | JavaScript | Claude Code |
| Ori Mnemos | 80 · Good | CLIFree | ★ 335 | 1mo ago | TypeScript | Claude Code · OpenAI API · Claude API |
| Obsidian Mind | 79 · Good | CLIFree | ★ 5.5k | 20d ago | TypeScript | Codex · Claude Code |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 159 | 1d ago | Python | Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows a non-root Docker user and a read-only mount for Claude project files, while PROJECT_ROOT can constrain the source directory; however, native operation scans potentially private conversations and writes a local database without finer directory, session, or field-level controls, so least_privilege is 2. Index rebuild, clearing, and export are explicit operations, and memory CRUD is exposed through named MCP tools, but no first-scan consent, sensitive-operation confirmation, or deletion safeguard is documented, so user_confirmation is 1. The README explains the source directory, SQLite index, ports, volumes, APIs, and exports, but not the complete retention lifecycle or network-exposure model, so data_flow_transparency is 2. There is no evidence of credential theft or covert exfiltration, but histories may contain secrets, source code, and personal data, while authentication, encryption, redaction, and secret filtering are not documented; sensitive_data_handling is therefore 1. Dependencies and runtime requirements are identified, but permissive ranges are used and the supplied evidence contains no lockfile, vulnerability scan, SBOM, or update policy, so dependency_security is 1. External effects are primarily local reads, database and memory writes, index clearing, and exports, and these are generally documented; the implications of binding the web service to 0.0.0.0 are not developed, so external_effects is 2. The index can be cleared or rebuilt and Docker can be stopped, but memory backups, transaction recovery, and recovery from accidental deletion are not documented, so rollback is 1. Repository, author, issue channel, and MIT copyright attribution are present, but the author email appears placeholder-like and publisher identity is unverified, so source_attribution is 2; unknown identity is not treated as suspicious.
The README, project tree, and package metadata are broadly consistent about the CLI, MCP binary, version line, and purpose, so self_consistency is 2; deductions reflect the README foregrounding 1.3.0 while package metadata says 1.3.4 and retaining older claude-viewer naming. Node.js 18+, npm, Claude Code history, ports, and installation paths are documented, and the checker is said to inspect dependencies, permissions, JSONL data, and database state, so dependency_availability is 2; no supplied lockfile or compatibility matrix establishes fully repeatable dependency resolution. Troubleshooting covers missing projects, broken search, ports, permissions, and dependencies with diagnostic commands, so failure_messages is 2; the evidence does not show structured errors from the MCP tools themselves.
Developers, QA engineers, and researchers are identified, with concrete browsing, search, analysis, export, and persistent-memory scenarios, justifying 3 for audience_and_scenarios. Features, APIs, MCP tool categories, prompts, indexing requirements, and roadmap boundaries are described, but the complete inputs, outputs, and prohibited behavior of each MCP tool are absent, so capability_boundaries is 2. Reindexing conditions and MCP setup are explicit, and operations appear to require deliberate MCP or API calls; specific per-tool trigger conditions and memory-write policy are not shown, so trigger_precision is 2. npm, source, Docker, custom ports, custom roots, Linux/macOS, and WSL2 paths are addressed, but native Windows behavior, Node/SQLite combinations, and non-Claude data sources are not established, so environment_fit is 2.
The README is thoroughly organized around quick start, configuration, architecture, formats, search, APIs, development, troubleshooting, and deployment, so information_architecture is 3. It gives actionable npm, npx, source, MCP, Docker, and production instructions, earning 3 for install_notes. CLI and package names are mostly stable, but legacy claude-viewer references and the 1.3.0 versus 1.3.4 presentation create minor drift, so naming_stability is 2. Search, API, Docker, parser-extension examples, and common-problem guidance are substantial, so examples_and_faq is 3. Manual reindexing, unfinished settings, and roadmap items are disclosed, but privacy, security, scale, concurrency, and MCP interoperability limits are not consolidated, so known_limitations is 2. The complete MIT text is supplied and agrees with package metadata, earning 3 for license. Dated release summaries and a full changelog path support 3 for versioning_changelog. The author, repository, Issues, Discussions, and contribution path are clear, but there is no maintenance team, support commitment, signed release path, or security-reporting channel, and publisher identity is unverified; maintenance_responsibility is 2.
The web UI supports conversation rendering, filtered search, analytics, and JSON/HTML/TXT exports, while MCP offers detail levels and structured memory, making the outputs directly usable and supporting 3 for output_usability. Unifying scattered Claude Code JSONL histories into a searchable web and MCP interface provides clear incremental value over manual inspection, so marginal_value is 3. The MIT license and local operation reduce acquisition cost, but installation across workspaces, index upkeep, SQLite storage, and privacy administration impose operational cost, and resource consumption is not quantified; cost_benefit is 2.
Many claims map to named directories, scripts, endpoints, binaries, and configuration, so claim_traceability is 2; stronger claims such as “enterprise-grade,” “121x faster,” and universal compatibility lack benchmarks, test results, or methodology in the supplied files. README and package metadata corroborate the product name, purpose, MCP executable, license, and version family, while LICENSE independently confirms MIT, so cross_source_corroboration is 2; only three files are supplied and no implementation, lockfile, or test contents provide broader corroboration. Marketing language is mixed with checkable facts, and performance and comprehensive-compatibility assertions are not clearly separated from demonstrated evidence, so fact_inference_separation is 1.
- Claude Code histories may contain API keys, source code, personal information, and internal decisions; add authentication, network restrictions, redaction, and retention controls before exposing Claudex beyond localhost or to multiple users.
- Structured-memory MCP operations can create, update, and delete data; back up the database and restrict write-capable tools while confirmation and recovery behavior remain undocumented.
- The supplied evidence includes no lockfile, dependency audit, SBOM, or security-update policy; pin dependencies and perform an independent vulnerability review before deployment.
- Claims such as “121x faster,” “enterprise-grade,” and comprehensive format compatibility are not sufficiently substantiated by the supplied static evidence and should not be treated as verified results.
- The publisher is not verified by the FollowAgents enterprise registry; this means maintenance identity is unknown, not that malicious behavior is evidenced.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/claudex)<a href="https://followagents.com/en/agents/claudex"><img src="https://followagents.com/badge/claudex.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.3.3 v1.3.3 — Official MCP Registry + major UX polish
Release notes excerpt
What's new This release brings two big things: 1. Official MCP Registry support — Claudex is now publishable to Anthropic's official MCP Registry at registry.modelcontextprotocol.io for canonical discovery by all MCP clients (Claude Code, Cursor, Codex, Windsurf). 2. Substantial UX polish — auto-apply settings, theme preview, error boundary, toast system, keyboard shortcuts, code-splitting, and a long bug-fix list. MCP Registry - Added mcpName: io.github.kunwar-shah/claudex to package.json - Added server.json manifest at repo root UX Polish …View on GitHub ↗ -
v1.3.2 v1.3.2 — Persistent memory MCP for Claude Code
Release notes excerpt
What's new This is a metadata refresh release — no functional code changes since v1.3.0, but a lot of housekeeping that makes Claudex easier to find and understand. Highlights - 🎬 Animated hero GIF in README (thanks @livlign for [PR #39](https://github.com/kunwar-shah/claudex/pull/39)) - 💝 GitHub Sponsors enabled — Sponsor button now visible on the repo - 🔍 Honest, MCP-focused description — "Persistent memory + FTS5 search for Claude Code conversations" …View on GitHub ↗ -
v1.3.0 v1.3.0 — MCP Server & Structured Memory
Release notes excerpt
What's New MCP Server for Claude Code Claudex now includes a Model Context Protocol (MCP) server that gives Claude Code persistent memory across sessions. Claude can remember your codebase conventions, architecture decisions, error patterns, and more. One-command setup: ```bash npm install -g @kunwarshah/claudex claude mcp add --transport stdio claudex -- claudex-mcp ``` 10 MCP Tools | Tool | Description | |------|-------------| | get_project_context | Condensed project snapshot (call this first!) | | list_projects | List all Claude Code projects | …View on GitHub ↗