memrecall

Semantic memory system for Claude Code sessions. Captures learnings, stores them with vector embeddings, and provides retrieval via semantic similarity search.

Features

• Automatic Memory Capture: Hooks capture learnings from coding sessions
• Semantic Search: Find relevant past experiences using natural language
• Project Summaries: AI-generated summaries injected into new sessions
• Conflict Detection: Identifies contradictory or outdated memories
• Memory Consolidation: Merges related memories to reduce redundancy

Quick Start

Installation

# Install the package
pip install memrecall

# Initialize for all projects (global)
memrecall init --global

# Or initialize for current project only
memrecall init --project

Interactive Setup

memrecall init

This will prompt you to choose between:

1. Global - Active for ALL projects (~/.claude/)
2. Project - Active only for THIS project (./.claude/)

Basic Usage

# Search your memories
memrecall query "authentication flow"

# Add a new memory
memrecall add --type bugfix --title "Fixed timezone" --fact "Use make_naive=True"

# Quick note (auto-classifies)
memrecall note "Always use utcnow() for storage"

# View project summary
memrecall summary

# List known gotchas
memrecall gotchas

# Check server health
memrecall health

Installation Modes

Commands

Memory Types

Server

The memrecall server runs locally and provides:

• REST API for memory operations
• Web UI for browsing memories
• Background tasks for consolidation

# Start server manually
memrecall server

# With custom port
memrecall server --port 9000

# Development mode with auto-reload
memrecall server --reload

The server starts automatically when hooks fire or CLI commands run.

Architecture

~/.memrecall/
├── projects/
│   └── {encoded-project-path}/
│       ├── vector_db/       # LanceDB storage
│       ├── summary.json     # Current summary
│       └── sessions/        # Session logs
├── config.json              # Server config
└── .memrecall_mode        # Installation marker

Uninstalling

# Remove hooks, keep your data
memrecall uninstall --global

# Remove everything including memories
memrecall uninstall --global --remove-data

Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# With GPU support
pip install -e ".[full]"

Requirements

• Python 3.10+
• Claude Code CLI (for hooks)
• ~200MB disk space (FastEmbed model)

Windows

On Windows, you need the Visual C++ Redistributable for the embedding model to work:

Download and install: https://aka.ms/vs/17/release/vc_redist.x64.exe

This is required because the onnxruntime library (used for embeddings) depends on the Visual C++ Runtime.

License

MIT License - see LICENSE