memrecall 1.0.0
Semantic memory system for Claude Code sessions
Requires Python: >=3.10
Keywords: claude, embeddings, lancedb, memory, semantic-search

# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

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

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

## Development

```bash
# 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](LICENSE)