Qdrant Memory - Per-Directory Persistent Memory for Claude Code

A lightweight wrapper system that provides isolated, persistent memory for Claude Code sessions based on your current working directory. Each project gets its own dedicated memory space that persists across sessions.

Features

• 🧠 Per-Directory Memory: Automatic isolation of memories by project directory
• 💾 Persistent Storage: Memories survive between Claude Code sessions
• 🔒 Automatic Lock Management: Cleans up stale locks from crashed sessions
• 🌍 Global Configuration: Single MCP setup works across all projects
• 🚀 Zero Configuration: Just cd to your project and start Claude Code
• 🔍 Visual Explorer: Included claude-peek tool to inspect stored memories

How It Works

The system intercepts the standard mcp-server-qdrant calls and automatically:

1. Creates a unique Qdrant database for each directory you work in
2. Maps your current working directory to an isolated memory store
3. Manages database locks to prevent corruption
4. Provides seamless memory persistence across sessions

When you start Claude Code in /home/user/project-a, it uses a completely different memory store than when you're in /home/user/project-b.

Installation

Prerequisites

• Claude Code CLI (claude)
• uvx (Install with: curl -LsSf https://astral.sh/uv/install.sh | sh)
• lsof (Optional but recommended for automatic lock cleanup)

Quick Install

git clone https://github.com/yourusername/qdrant-memory.git
cd qdrant-memory
./install.sh

The installer will:

• Copy the wrapper script to ~/.local/bin/
• Configure Claude Code MCP with user-global scope
• Create storage directories at ~/.qdrant/sessions/
• Set up the qdrant-memory command alias

Usage

Once installed, simply start Claude Code in any directory:

cd /path/to/your/project
claude

Claude will automatically have access to:

• qdrant-store - Store information in memory
• qdrant-find - Search and retrieve from memory
• qdrant-delete - Remove specific memories

Each directory maintains its own isolated memory. Switch directories, and you switch memory contexts!

Visual Memory Explorer

Inspect what's stored in your current directory's memory:

claude-peek

This shows all stored memories with their metadata and content.

Project Structure

qdrant-memory/
├── bin/
│   ├── mcp-server-qdrant-session  # Main wrapper script
│   └── claude-peek                # Visual memory explorer
├── install.sh                     # Installation script
├── uninstall.sh                   # Uninstallation script
└── README.md                      # This file

How Memory Storage Works

Memories are stored in: ~/.qdrant/sessions/{directory-name}/

For example:

• Working in /home/user/Documents/project → ~/.qdrant/sessions/Documents-project/
• Working in /home/user/work/client-a → ~/.qdrant/sessions/work-client-a/

Uninstallation

To remove the MCP configuration and wrapper (preserves memories):

./uninstall.sh

To completely remove everything including all stored memories:

./uninstall.sh --purge

Troubleshooting

MCP Connection Issues

If Claude Code can't connect to the MCP server:

1. Check MCP status: claude mcp list
2. Verify configuration: claude mcp get qdrant
3. Restart Claude Code

Lock File Issues

If you see lock file errors, the wrapper automatically cleans stale locks. If problems persist:

rm ~/.qdrant/sessions/*/.lock

Memory Not Persisting

Ensure you're in the same directory where memories were created. The system uses the full path to determine which memory store to use.

Technical Details

• Vector Database: Qdrant (local mode)
• Embedding Model: sentence-transformers/all-MiniLM-L6-v2
• Storage Format: Qdrant native format
• Lock Management: Uses lsof to detect stale locks

License

MIT License

Copyright (c) 2024 Jack Darcy

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Created by Jack Darcy as a personal side project to enhance Claude Code with persistent, per-project memory capabilities using Qdrant vector database.