memory-bank

memory-bank

Local vector DB for ingesting and searching Claude chat histories. Ask "what did I work on last week?" and get real answers from your past sessions — no cloud, no server, everything runs on your machine.

Contents

• Getting started
• Configuration
• Commands
  • Ingest
  • Search
  • Stats
  • Delete
  • UI
  • Hooks
  • Update
• Data sources
• Custom data source (Python API)
• Interactive search agent
• Claude Code integration
• How it works
• Project layout

Getting started

Option 1 — one-step installer (recommended)

bash <(curl -fsSL https://raw.githubusercontent.com/jdelgadoperez/memory-bank/main/install.sh)

Installs uv if needed, runs uv tool install memory-bank, wires Claude Code hooks and MCP, and runs an initial ingest. No repo clone required. When it finishes, memory-bank is available as a shell command.

PATH note: If you see zsh: command not found: memory-bank after install, ~/.local/bin is not in your PATH. Add this to your ~/.zshrc or ~/.bashrc and open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

Option 2 — manual (uv tool)

uv tool install memory-bank
memory-bank setup install
memory-bank ingest claude-code

To update: memory-bank update

Option 3 — clone (contributors / local dev)

git clone https://github.com/jdelgadoperez/memory-bank
cd memory-bank
uv sync
mkdir -p ~/.local/bin
ln -sf "$PWD/.venv/bin/memory-bank" ~/.local/bin/memory-bank
memory-bank setup install
memory-bank ingest claude-code

Skills are symlinked from the source tree in this mode — edits take effect immediately without reinstalling.

Note: On first ingest, BAAI/bge-small-en-v1.5 embedding model (~25 MB) downloads once from HuggingFace and runs fully offline after.

---

Configuration

All settings are controlled via environment variables. You can set them in your shell profile (~/.zshrc, ~/.bashrc) or prefix individual commands.

Variable	Default	Description
MEMORY_BANK_DB	~/.memory-bank/qdrant	Where the vector DB is stored on disk
CLAUDE_PROJECTS_DIR	~/.claude/projects	Path to Claude Code session logs
CLAUDE_DESKTOP_PATH	~/Library/Application Support/Claude	Path to Claude Desktop app data
ANTHROPIC_API_KEY	—	Required only for the interactive search agent
MEMORY_BANK_RECALL	—	Set to 0 to disable the recall (UserPromptSubmit) hook
QDRANT_URL	—	Override the Qdrant server URL (e.g. http://localhost:6333). Skips Docker auto-start.

Slow commands / commands hanging

If memory-bank commands hang or feel slow, it is usually because the Qdrant health check and Docker daemon probe run on startup. Each has a short timeout, but on some machines (e.g. Apple Silicon with Docker not running) the probes still add a few seconds of latency.

Option 1 — disable the recall hook (fastest, no DB access on every prompt):

export MEMORY_BANK_RECALL=0

Option 2 — point directly at a running Qdrant server (skips Docker probing):

export QDRANT_URL=http://localhost:6333

Option 3 — run memory-bank update when commands are hanging (e.g. after a fresh install before Qdrant has started):

MEMORY_BANK_RECALL=0 memory-bank update

Example: custom DB location

export MEMORY_BANK_DB=/data/my-memory-bank
memory-bank ingest claude-code
memory-bank search "my query"

Or inline per-command with --db:

memory-bank ingest claude-code --db /data/my-memory-bank
memory-bank search "my query" --db /data/my-memory-bank

Example: custom Claude Code path

# If your Claude projects live somewhere non-standard
memory-bank ingest claude-code --path /Volumes/external/claude-projects
# or permanently:
export CLAUDE_PROJECTS_DIR=/Volumes/external/claude-projects

---

Commands

Ingest

memory-bank ingest claude-code [--path PATH] [--db PATH]
memory-bank ingest claude-desktop --path PATH [--db PATH]
memory-bank ingest chatgpt --path PATH [--db PATH]
memory-bank ingest all [--db PATH]
memory-bank ingest custom                         # prints Python API usage

Ingest is idempotent — re-running skips messages already in the DB.

Claude Desktop