hypermnesia-mcp — Claude Code MCP server: setup and overview
Local persistent memory for AI coding agents that preserves decisions and project context across sessions. Operates entirely on your machine via SQLite or PostgreSQL.
claude mcp add hypermnesia-mcp -- uvx hypermnesia-mcpWhat hypermnesia-mcp does
This server provides 57 tools and 11 lifecycle hooks to manage long-term agent memory. It tracks architectural choices, bug resolutions and code context between terminal sessions. Retrieval runs strictly offline without invoking an external LLM loop. Embedding and reranking models are pulled onto your machine during the initial launch.
By default, the server writes project history to an SQLite database located under ~/.claude/methodology/. On macOS and glibc Linux systems, it can provision a dedicated PostgreSQL runtime with pgvector and pg_trgm. If Linux lacks libxml2.so.2 or OpenSSL 3, the embedded PostgreSQL binary cannot start, forcing a fallback to SQLite.
Both Claude Code and Codex can read the same shared store. Project memory stays on your drive. Sensitive project history never touches third-party servers.
What it helps with
- retain architecture decisions and debugging history across agent sessions
- share accumulated project knowledge between Claude Code and Codex
- perform local hybrid retrieval without sending queries to external LLM providers
- set up self-hosted vector storage using SQLite or managed PostgreSQL with
pgvector
Example prompts for the agent
- Recall why we chose PostgreSQL over SQLite for this service
- Save our resolution for the session expiration bug into project memory
- Search project history for database query optimization patterns
How to install hypermnesia-mcp
Platform CLI
claude mcp add hypermnesia-mcp -- uvx hypermnesia-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>
Platform CLI
codex mcp add hypermnesia-mcp -- uvx hypermnesia-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>
Config file
{
"mcpServers": {
"hypermnesia-mcp": {
"command": "uvx",
"args": [
"hypermnesia-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>
Config file
{
"servers": {
"hypermnesia-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"hypermnesia-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>
Platform CLI
gemini mcp add hypermnesia-mcp uvx hypermnesia-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about hypermnesia-mcp
How to install hypermnesia-mcp in Claude Code?
Run claude mcp add hypermnesia-mcp -- uvx hypermnesia-mcp in your terminal. You need Python 3.10 or newer with uvx available on your system.
What does hypermnesia-mcp do?
It provides persistent local memory for coding agents through 57 dedicated tools. The system records past fixes and context across restarts, retrieving records locally without external model APIs.
Where does hypermnesia-mcp store data?
It stores records in a local SQLite file in ~/.claude/methodology/ by default. On compatible macOS and Linux environments, it can run a managed PostgreSQL instance with pgvector.
