# Hanzo Memory Service

## Add memory to any AI application!

A high-performance FastAPI service that provides memory and knowledge management capabilities for AI applications. Built with InfinityDB for vector storage, FastEmbed for local embeddings, and LiteLLM for flexible LLM integration.

## Features

- **🧠 Intelligent Memory Management**: Store and retrieve contextual memories with semantic search
- **📚 Knowledge Base System**: Organize facts in hierarchical knowledge bases with parent-child relationships
- **💬 Chat History**: Store and search conversation history with de-duplication
- **🔍 Unified Search API**: Fast semantic search using FastEmbed embeddings
- **🤖 Flexible LLM Support**: Use any LLM via LiteLLM (OpenAI, Anthropic, Ollama, etc.)
- **🔐 Multi-tenancy**: Secure user and project-based data isolation
- **🚀 High Performance**: Local embeddings and efficient vector storage with InfinityDB
- **🔌 MCP Support**: Model Context Protocol server for AI tool integration
- **📦 Easy Deployment**: Docker support and uvx compatibility

## Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   FastAPI       │────▶│   InfinityDB    │────▶│   FastEmbed     │
│   Server        │     │   (Vector DB)   │     │   (Embeddings)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                                │
         ▼                                                ▼
┌─────────────────┐                              ┌─────────────────┐
│   LiteLLM       │                              │   Local Models  │
│   (LLM Bridge)  │                              │   (BGE, etc.)   │
└─────────────────┘                              └─────────────────┘
```

## Quick Start

### Install with uvx

```bash
# Install and run directly with uvx
uvx hanzo-memory

# Or install globally
uvx install hanzo-memory
```

### Install from source

```bash
# Clone the repository
git clone https://github.com/hanzoai/memory
cd memory

# Install with uv
make setup

# Run the server
make dev
```

### Docker

```bash
# Using docker-compose
docker-compose up

# Or build and run manually
docker build -t hanzo-memory .
docker run -p 4000:4000 -v $(pwd)/data:/app/data hanzo-memory
```

## Configuration

Create a `.env` file (see `.env.example`):

```env
# API Authentication
HANZO_API_KEY=your-api-key-here
HANZO_DISABLE_AUTH=false  # Set to true for local development

# LLM Configuration (choose one)
# OpenAI
HANZO_LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-openai-key

# Anthropic
HANZO_LLM_MODEL=claude-3-haiku-20240307
ANTHROPIC_API_KEY=your-anthropic-key

# Local Models (Ollama)
HANZO_LLM_MODEL=ollama/llama3.2
HANZO_LLM_API_BASE=http://localhost:11434

# Embedding Model
HANZO_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
```

## API Documentation

For complete API documentation including all endpoints, request/response formats, and examples, see [docs/API.md](docs/API.md).

### Quick API Overview

- **Memory Management**: `/v1/remember`, `/v1/memories/*`
- **Knowledge Bases**: `/v1/kb/*`, `/v1/kb/facts/*`
- **Chat Sessions**: `/v1/chat/sessions/*`, `/v1/chat/messages/*`
- **Search**: Unified semantic search across all data types
- **MCP Server**: Model Context Protocol integration for AI tools

### LLM Features

The service can:
- **Summarize content** for knowledge extraction
- **Generate knowledge update instructions** in JSON format
- **Filter search results** for relevance
- **Strip PII** from stored content

Example summarization request:
```python
llm_service.summarize_for_knowledge(
    content="Long document...",
    skip_summarization=False,  # Set to True to skip
    provided_summary="Optional pre-made summary"
)
```

Returns:
```json
{
  "summary": "Concise summary of content",
  "knowledge_instructions": {
    "action": "add_fact",
    "facts": [{"content": "Extracted fact", "metadata": {...}}],
    "reasoning": "Why these facts are important"
  }
}
```

## Development

### Running Tests

```bash
# Run all tests
make test

# Run with coverage
make test-cov

# Run specific test
uvx pytest tests/test_memory_api.py -v
```

### Code Quality

```bash
# Format code
make format

# Run linter
make lint

# Type checking
make type-check
```

### Project Structure

```
memory/
├── src/hanzo_memory/
│   ├── api/          # API authentication
│   ├── db/           # InfinityDB client
│   ├── models/       # Pydantic models
│   ├── services/     # Business logic
│   ├── config.py     # Settings
│   └── server.py     # FastAPI app
├── tests/            # Pytest tests
├── Makefile          # Build automation
└── pyproject.toml    # Project config
```

## Deployment

### Production Checklist

1. Set strong `HANZO_API_KEY`
2. Configure appropriate LLM model and API keys
3. Set `HANZO_DISABLE_AUTH=false`
4. Configure data persistence volume
5. Set up monitoring and logging
6. Configure rate limiting if needed

### Scaling Considerations

- InfinityDB embedded runs in-process (no separate DB server)
- FastEmbed generates embeddings locally (no API calls)
- LLM calls can be directed to local models for full offline operation
- Use Redis for caching in high-traffic scenarios

## Contributing

Pull requests are welcome! Please:
1. Write tests for new features
2. Follow existing code style
3. Update documentation as needed
4. Run `make check` before submitting

## License

BSD License - see LICENSE file for details.
