memrecall 1.0.0

Semantic memory system for Claude Code sessions

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

Mode	Hooks Location	Data Location	Use Case
Global	~/.claude/hooks/memrecall/	~/.memrecall/	Single user, all projects
Project	./.claude/hooks/memrecall/	./.memrecall/	Per-project isolation

Commands

Command	Description
init	Set up hooks and skills
uninstall	Remove hooks (preserves data by default)
server	Start the memrecall server
query <text>	Semantic search
add	Add a memory with type, title, fact
note <text>	Quick capture with auto-classification
resolve <desc>	Mark a priority as completed
files <path>	Find memories by file
summary	View project summary
summary-generate	Generate/regenerate summary
recent	Show recent memories
gotchas	List known pitfalls
stats	Project statistics
projects	List all projects
health	Server health check

Memory Types

Type	Description
bugfix	Bug fixes and solutions
feature	New functionality
discovery	How things work
decision	Architecture choices
refactor	Code restructuring
optimization	Performance improvements
gotcha	Pitfalls to avoid
resolution	Completed priorities

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