Memory Vault

Memory Vault

[](https://github.com/MihaiBuilds/memory-vault/actions/workflows/test.yml)

The memory database for AI applications. Self-hosted Postgres + pgvector with hybrid search, MCP-native, and a knowledge graph baked in.

Every conversation with Claude or ChatGPT starts from zero. No memory of what you built last week, what decisions you made last month, what problems you've already solved. You either re-explain everything from scratch, or paste in a wall of context and hope it fits in the window.

Memory Vault is the persistent layer underneath. It stores what you want your AI to remember — decisions, conversations, notes, project context — in a single Postgres database with hybrid semantic + keyword search. Claude can recall and store memories during any session via MCP, you can chat with your own memories through a local LLM, or you can build your own AI tool on top of the REST API.

---

> Chat with your vault using a local LLM. Every answer shows the exact memories it was grounded in — click any source to verify.

---

Status

v1.0 — released 2026-05-07. First stable release of Memory Vault. M1-M7 (hybrid search, Docker, MCP, REST API, dashboard, knowledge graph, local LLM chat) all shipped and stable.

Release notes: GitHub Releases.

Semver from here forward — the public surface (REST API endpoints, MCP tool signatures, DB schema) is stable. Breaking changes only on a major version bump.

---

Quick Start (Docker)

git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault
docker compose up -d

That's it. PostgreSQL + pgvector + Memory Vault, running and ready. Migrations run automatically on first start.

# Check it's working
docker compose exec app memory-vault status

# Ingest a file
docker compose exec app memory-vault ingest /path/to/file.md --space default

# Search
docker compose exec app memory-vault search "your query here"

Data persists in a Docker volume — docker compose down and up again, your memories are still there.

Open http://localhost:8000 in your browser to use the dashboard (Chat, Search, Browse, Graph, Ingest, Stats).

> Windows users: clone into WSL2, not a Windows path, and read [docs/windows.md](docs/windows.md) if you hit a line-ending error.

---

No-Docker quick start

If you prefer running without Docker:

Prerequisites

• Python 3.11+
• PostgreSQL 16 with pgvector extension

Setup

# Clone
git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Configure
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Run migrations
memory-vault migrate

# Verify
memory-vault status

Usage

# Ingest a file
memory-vault ingest notes.md --space default

# Search memories
memory-vault search "hybrid search architecture" --limit 5

# Check status
memory-vault status

---

Features

• Hybrid search — semantic similarity + keyword matching combined, so you find the right memory even when you don't remember the exact words
• MCP integration — four tools (recall, remember, forget, memory_status) that Claude can use natively during any session
• Local LLM chat — query your own memories through LM Studio without sending anything to the cloud, with sources shown for every answer
• Knowledge graph — entities and relationships extracted automatically, connections between things emerge over time
• Memory spaces — separate namespaces for different projects or domains
• REST API — integrate AI memory into any application
• One-command setup — docker compose up and it's running
• Self-hosted — your data stays on your machine, always

---

Architecture

> Postgres + pgvector at the core. The same memory layer is reachable from MCP (Claude), the dashboard chat page, the REST API, and any app you build on top.

Three things are deliberate about this stack:

• One database, not two. Vector embeddings, full-text indexes, and relational data all live in Postgres. No separate vector DB to keep in sync.
• Frontend-agnostic. The dashboard is one consumer of the API, not the API itself. MCP, REST, CLI, and your own apps are equal first-class clients.
• CPU-only by default. No GPU required. Embeddings (sentence-transformers) and entity extraction (spaCy) both run on a normal laptop.

---

Tech Stack

• PostgreSQL 16 + pgvector — vector storage and hybrid search in one database
• Python 3.11+ — async backend with psycopg 3
• sentence-transformers — all-MiniLM-L6-v2 embeddings (384-d, runs on CPU)
• spaCy — en_core_web_sm for entity extraction (CPU-only, no LLM calls)
• FastAPI — REST API with bearer auth, rate limiting, and OpenAPI docs
• React 19 + Vite + TanStack Query — web dashboard, baked into the main Docker image
• Cytoscape.js + cose-bilkent — force-directed knowledge graph rendering on the dashboard
• Docker — one-command deployment with docker compose up
• MCP — Claude integration via FastMCP (stdio transport)

---

MCP Integration (Claude Desktop & Claude Code)

Memory Vault exposes four tools via the Model Context Protocol so Claude can read and write memories during any conversation.

Tools

| Tool | Description | |------|-------------| | recall | Search memories with hybrid search (vector + full-text + RRF) | | remember | Store a new memory — auto-classified and embedded | | forget | Soft-delete a memory by chunk ID | | memory_status | Database health, chunk counts, embedding model info |

Resources

| Resource | Description | |----------|-------------| | memory://spaces | List all memory spaces with chunk counts | | memory://stats | Current system statistics |

Setup — Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "memory-vault": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/memory-vault",
      "env": {
        "PYTHONPATH": "/path/to/memory-vault",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "memory_vault",
        "DB_USER": "memory_vault",
        "DB_PASSWORD": "memory_vault"
      }
    }
  }
}

Setup — Claude Desktop

Add the same config to Claude Desktop's settings (Settings → Developer → Edit Config). The server runs over stdio — no HTTP, no ports to expose.

Docker Users

If you're running Memory Vault via Docker, point DB_HOST at the Docker host:

{
  "mcpServers": {
    "memory-vault": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/memory-vault",
      "env": {
        "PYTHONPATH": "/path/to/memory-vault",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_NAME": "memory_vault",
        "DB_USER": "memory_vault",
        "DB_PASSWORD": "memory_vault"
      }
    }
  }
}

> The MCP server itself runs on the host (not inside Docker) and connects to the PostgreSQL container. Make sure port 5432 is exposed in your docker-compose.yml.

Verify It Works

Once configured, Claude will have access to the memory tools. Try:

> "Use memory_status to check the memory system."

> "Remember that we chose Redis for the session cache."

> "Recall everything about hybrid search."

---

Local LLM Chat

Memory Vault includes a chat page that lets you talk to your own memories using a local LLM — no cloud, no OpenAI key, no telemetry. The dashboard runs hybrid search against your vault, builds a context block from the top hits, and streams the answer back from a model running on your machine.

Sources are shown with every answer. Every response includes the exact chunks the LLM used, with similarity scores and content previews. Click any source to verify the answer is grounded in your data, not invented. This is the differentiator vs. opaque chat-over-docs tools — you always know what the model saw.

Setup

Memory Vault uses LM Studio as the local LLM provider in v1.0.

1. Download and install LM Studio.
2. Load a non-thinking model — Qwen2.5 (7B+), Llama 3 (8B+), or similar. Avoid Qwen3, DeepSeek-R1, and o1-style reasoning models — they emit chain-of-thought into the answer and break the RAG flow.
3. Start the local server (LM Studio → Developer tab → Start Server). Default address: http://localhost:1234.
4. Open the Memory Vault dashboard → Chat page → ⚙️ Settings → confirm the Local LLM URL points at your LM Studio instance. The model is auto-detected.

That's it. Ask a question; the dashboard retrieves relevant chunks, sends them with your question to LM Studio, and streams the answer back.

How it works

1. Hybrid search retrieves the top chunks for your question (same engine as /api/search and MCP recall)
2. Top hits are packed into a 6,000-token context budget — oldest history dropped first, then lowest-similarity chunks
3. LM Studio generates an answer streamed token-by-token via Server-Sent Events
4. Sources arrive first in the stream, so the UI shows "based on N memories" before tokens start flowing

Why LM Studio first

LM Studio's native API supports reasoning="off", which is the only reliable way to suppress chain-of-thought from thinking models in a RAG flow. Memory Vault uses the native API by default and falls back to OpenAI-compat (/v1/chat/completions) with ... stripping if the native API isn't available.

---

REST API

Every MCP tool is also exposed as an HTTP endpoint so you can integrate Memory Vault into any app, script, or language. The API is served by FastAPI at http://localhost:8000 when you run docker compose up.

• Interactive docs: http://localhost:8000/docs
• OpenAPI schema: http://localhost:8000/openapi.json

The auto-generated /docs page is the canonical API reference — it stays in sync with the code. The summary below is for orientation.

Authentication

All endpoints except /api/health require a bearer token. Create one via the CLI:

docker compose exec app memory-vault token create my-app

The plaintext token is shown once — copy it immediately. Then send it as a header:

curl -H "Authorization: Bearer mv_..." http://localhost:8000/api/spaces

Manage tokens:

memory-vault token list
memory-vault token revoke mv_abc1234

To disable auth entirely (local dev only), set API_AUTH_ENABLED=false.

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /api/health | Service + database health (no auth) | | GET | /api/spaces | List memory spaces with chunk counts | | POST | /api/search | Hybrid search (vector + full-text + RRF) | | GET | /api/chunks | List chunks with pagination and filters | | GET | /api/chunks/{id} | Get a single chunk | | DELETE | /api/chunks/{id} | Soft-delete (forget) a chunk | | POST | /api/ingest/text | Ingest a text string as a chunk | | POST | /api/ingest/file | Upload a file through the ingestion pipeline | | POST | /api/chat | RAG chat over hybrid search (non-streaming) | | POST | /api/chat/stream | RAG chat with token-by-token SSE streaming |

Example — search

curl -X POST http://localhost:8000/api/search \
  -H "Authorization: Bearer $MV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does hybrid search work",
    "spaces": ["default"],
    "limit": 5
  }'

Example — ingest text

curl -X POST http://localhost:8000/api/ingest/text \
  -H "Authorization: Bearer $MV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Decided to use RRF for hybrid merging", "space": "default"}'

Example — upload a file

curl -X POST http://localhost:8000/api/ingest/file \
  -H "Authorization: Bearer $MV_TOKEN" \
  -F "file=@notes.md" \
  -F "space=default"

Configuration

| Variable | Default | Description | |----------|---------|-------------| | API_HOST | 0.0.0.0 | Bind address | | API_PORT | 8000 | Port | | API_AUTH_ENABLED | true | Set false to disable bearer auth (local dev only) | | API_CORS_ORIGINS | * | Comma-separated allowed origins, or * | | API_RATE_LIMIT_PER_MIN | 120 | Per-IP request limit per minute |

---

Dashboard

Memory Vault ships with a web UI baked into the same Docker image as the API — no separate deploy, no extra port. Open http://localhost:8000 in your browser after docker compose up.

Six pages:

• Chat — talk to your vault with a local LLM, sources shown for every answer (default landing page)
• Search — hybrid search with space filter, similarity scores, expandable hit content
• Browse — paginated chunk list with space + sort filters, two-step inline delete
• Graph — force-directed knowledge graph (Cytoscape.js), pan/zoom, click a node to see its mentions and related entities, filters for space / type / min-mentions / max-nodes
• Ingest — paste text or upload files (one at a time in v1.0), per-file status, batch summary
• Stats — system health, total chunks, spaces table with visual distribution, auto-refresh every 30s

Access

The dashboard uses the same bearer token as the API. Create one and paste it into the dashboard's token screen:

docker compose exec app memory-vault token create dashboard

The plaintext token is shown once — copy it immediately. Open http://localhost:8000, paste into the prompt, and the dashboard stores it in localStorage under memory-vault-token. You won't be asked again on that browser.

Rotating or revoking

# See which tokens exist
docker compose exec app memory-vault token list

# Revoke by prefix (shown in list output)
docker compose exec app memory-vault token revoke mv_abc1234

# Create a new one
docker compose exec app memory-vault token create dashboard

After revoking, the dashboard will hit a 401 on its next request and auto-clear the stored token, forcing you to paste the new one.

Troubleshooting

• Prompted for token every reload: your browser is blocking localStorage (private mode, strict cookie settings). Use a normal window or allow storage for localhost.
• 401 on every request: the token was revoked or API_AUTH_ENABLED changed. Create a fresh token and paste it in.
• Dashboard shows but API calls fail with CORS: you're hitting the API on a different origin than the dashboard. The baked-in build avoids this — use http://localhost:8000, not the dev server, unless you know what you're doing.
• Running the dev server: cd web && npm install && npm run dev serves the UI at http://localhost:5173 with API calls proxied to :8000. For development only.
• Windows-specific issues: see [docs/windows.md](docs/windows.md).
• Reporting a bug: run docker compose exec app memory-vault diagnose (or memory-vault diagnose on the host for a fuller bundle including docker compose ps + db logs). The command writes a memory-vault-diagnostic-YYYY-MM-DD-HHMMSS.zip containing app logs, status, OS info, and redacted env vars. Bearer tokens, passwords, and mv_ tokens are auto-scrubbed — but please review the bundle before attaching it to a public GitHub issue.
• Quoting a request ID: every API response carries an X-Request-ID header (UUID hex). Include it in bug reports — it lets the maintainer grep the same request across the structured JSON logs.

---

How It Works

Hybrid Search

Memory Vault combines two search methods and merges the results:

1. Vector search — converts your query to an embedding, finds semantically similar ch

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MihaiBuilds
• Source: MihaiBuilds/memory-vault
• License: MIT
• Homepage: https://mihaibuilds.com

Install and usage instructions live in the source repository linked above.