# hypermnesia-mcp

Local persistent memory for AI coding agents that preserves decisions and project context across sessions. Operates entirely on your machine via SQLite or PostgreSQL.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 75
- Author: cdeust
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cdeust/Cortex
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/hypermnesia-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add hypermnesia-mcp -- uvx hypermnesia-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add hypermnesia-mcp -- uvx hypermnesia-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add hypermnesia-mcp uvx hypermnesia-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from hypermnesia-mcp <command>

## When to use it
- 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
- 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

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md