t66_langmem/README.md

# LangMem - Long-term Memory System for LLM Projects

A comprehensive memory system that integrates with your existing Ollama and Supabase infrastructure to provide long-term memory capabilities for LLM applications.

## Architecture

LangMem uses a hybrid approach combining:
- **Vector Search**: Supabase with pgvector for semantic similarity
- **Graph Relationships**: Neo4j for contextual connections
- **Embeddings**: Ollama with nomic-embed-text model
- **API Layer**: FastAPI with async support

## Features

- 🧠 **Hybrid Memory Retrieval**: Vector + Graph search
- 🔍 **Semantic Search**: Advanced similarity matching
- 👥 **Multi-user Support**: Isolated user memories
- 📊 **Rich Metadata**: Flexible memory attributes
- 🔒 **Secure API**: Bearer token authentication
- 🐳 **Docker Ready**: Containerized deployment
- 📚 **Protected Documentation**: Basic auth-protected docs
- 🧪 **Comprehensive Tests**: Unit and integration tests
- 📈 **Analytics System**: User stats, memory relationships, clusters, trends
- 🔧 **Performance Optimization**: Database indexing and query optimization
- 💬 **Alternative Messaging**: Home Assistant Matrix integration
- 🛠️ **MCP Integration**: Model Context Protocol server for Claude Code

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Ollama running on localhost:11434
- Supabase running on localai network
- Python 3.11+ (for development)

### 1. Clone and Setup

```bash
git clone <repository>
cd langmem
```

### 2. Start Development Environment

```bash
./scripts/start-dev.sh
```

This will:
- Create required Docker network
- Start Neo4j database
- Build and start the API
- Run health checks

### 3. Test the API

```bash
./scripts/test.sh
```

## API Endpoints

### Authentication
All endpoints require Bearer token authentication:
```
Authorization: Bearer langmem_api_key_2025
```

### Core Endpoints

#### Store Memory
```bash
POST /v1/memories/store
Content-Type: application/json

{
  "content": "Your memory content here",
  "user_id": "user123",
  "session_id": "session456",
  "metadata": {
    "category": "programming",
    "importance": "high"
  }
}
```

#### Search Memories
```bash
POST /v1/memories/search
Content-Type: application/json

{
  "query": "search query",
  "user_id": "user123",
  "limit": 10,
  "threshold": 0.7,
  "include_graph": true
}
```

#### Retrieve for Conversation
```bash
POST /v1/memories/retrieve
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
  ],
  "user_id": "user123",
  "session_id": "session456"
}
```

#### Analytics Endpoints
```bash
GET /v1/analytics/user/{user_id}/stats          # User memory statistics
GET /v1/analytics/user/{user_id}/relationships  # Memory relationships
GET /v1/analytics/user/{user_id}/clusters       # Memory clusters
GET /v1/analytics/user/{user_id}/trends         # Memory trends
GET /v1/analytics/system/health                 # System health metrics
```

## Configuration

### Environment Variables

Copy `.env.example` to `.env` and configure:

```bash
# API Settings
API_KEY=langmem_api_key_2025

# Ollama Configuration
OLLAMA_URL=http://localhost:11434

# Supabase Configuration
SUPABASE_URL=http://localhost:8000
SUPABASE_KEY=your_supabase_key
SUPABASE_DB_URL=postgresql://postgres:password@localhost:5435/postgres

# Neo4j Configuration
NEO4J_URL=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=langmem_neo4j_password
```

## Development

### Project Structure

```
langmem/
├── src/                    # Source code
│   ├── api/               # FastAPI application
│   │   ├── main.py        # Main API server
│   │   ├── fact_extraction.py  # Fact-based memory logic
│   │   ├── memory_manager.py   # Memory management
│   │   ├── analytics.py   # Memory analytics system
│   │   └── performance_optimizer.py # Performance optimization
│   └── mcp/               # Model Context Protocol
│       ├── server.py      # MCP server for Claude Code
│       └── requirements.txt
├── scripts/               # Utility scripts
│   ├── start-dev.sh       # Development startup
│   ├── start-mcp-server.sh # MCP server startup
│   ├── start-docs-server.sh # Documentation server
│   ├── docs_server.py     # Authenticated docs server
│   ├── get-claude-token.py # Matrix setup utility
│   ├── test.sh            # Test runner
│   ├── claude-messaging-system.py # Matrix messaging system
│   ├── complete-signal-auth.py # Signal bridge authentication
│   ├── verify-signal-auth.py # Signal bridge verification
│   ├── send-matrix-message.py # Matrix message sender
│   └── optimize-performance.py # Performance optimization
├── tests/                 # Test suite
│   ├── test_api.py        # API tests
│   ├── test_integration.py # Integration tests
│   ├── test_fact_based_memory.py # Fact extraction tests
│   ├── debug_*.py         # Debug utilities
│   └── conftest.py        # Test configuration
├── docs/                  # Documentation website
│   ├── index.html         # Main documentation
│   ├── api/               # API documentation
│   ├── architecture/      # Architecture docs
│   └── implementation/    # Setup guides
├── config/                # Configuration files
│   ├── mcp_config.json    # MCP server config
│   ├── claude-matrix-config.json # Matrix setup
│   └── caddyfile-docs-update.txt # Caddy config
├── docker-compose.yml     # Docker services
├── Dockerfile            # API container
├── requirements.txt      # Python dependencies
├── IMPLEMENTATION_STATUS.md # Complete implementation status
└── README.md             # This file
```

## Alternative Messaging System

Since Signal bridge requires phone access, an alternative messaging system has been implemented using Home Assistant Matrix integration:

### Matrix Messaging Commands
- **Send messages**: `python scripts/claude-messaging-system.py send "message"`
- **Read messages**: `python scripts/claude-messaging-system.py read`
- **Monitor messages**: `python scripts/claude-messaging-system.py monitor`
- **Send notifications**: `python scripts/claude-messaging-system.py notify "message"`

### Home Assistant Integration
- **Room**: `!xZkScMybPseErYMJDz:matrix.klas.chat`
- **Access**: Available through Home Assistant Matrix room
- **Real-time**: Supports real-time communication without Signal app

### Running Tests

```bash
# All tests
./scripts/test.sh all

# Unit tests only
./scripts/test.sh unit

# Integration tests only
./scripts/test.sh integration

# Quick tests (no slow tests)
./scripts/test.sh quick

# With coverage
./scripts/test.sh coverage
```

### Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run API directly
python src/api/main.py

# Run tests
pytest tests/ -v
```

## Integration with Existing Infrastructure

### Ollama Integration
- Uses your existing Ollama instance on localhost:11434
- Leverages nomic-embed-text for embeddings
- Supports any Ollama model for embedding generation

### Supabase Integration  
- Connects to your existing Supabase instance
- Uses pgvector extension for vector storage
- Leverages existing authentication and database

### Docker Network
- Connects to your existing `localai` network
- Seamlessly integrates with other services
- Maintains network isolation and security

## API Documentation

Once running, visit:
- API Documentation: http://localhost:8765/docs
- Interactive API: http://localhost:8765/redoc
- Health Check: http://localhost:8765/health

## Monitoring

### Health Checks
The API provides comprehensive health monitoring:

```bash
curl http://localhost:8765/health
```

Returns status for:
- Overall API health
- Ollama connectivity
- Supabase connection
- Neo4j database
- PostgreSQL database

### Logs
View service logs:

```bash
# API logs
docker-compose logs -f langmem-api

# Neo4j logs
docker-compose logs -f langmem-neo4j

# All services
docker-compose logs -f
```

## Troubleshooting

### Common Issues

1. **API not starting**: Check if Ollama and Supabase are running
2. **Database connection failed**: Verify database credentials in .env
3. **Tests failing**: Ensure all services are healthy before running tests
4. **Network issues**: Confirm localai network exists and is accessible

### Debug Commands

```bash
# Check service status
docker-compose ps

# Check network
docker network ls | grep localai

# Test Ollama
curl http://localhost:11434/api/tags

# Test Supabase
curl http://localhost:8000/health

# Check logs
docker-compose logs langmem-api
```

## Production Deployment

For production deployment:

1. Update environment variables
2. Use proper secrets management
3. Configure SSL/TLS
4. Set up monitoring and logging
5. Configure backup procedures

## Documentation

The LangMem project includes comprehensive documentation with authentication protection.

### Accessing Documentation

Start the authenticated documentation server:

```bash
# Start documentation server on port 8080 (default)
./scripts/start-docs-server.sh

# Or specify a custom port
./scripts/start-docs-server.sh 8090
```

**Access Credentials:**
- **Username:** `langmem`
- **Password:** `langmem2025`

**Available Documentation:**
- 📖 **Main Docs**: System overview and features
- 🏗️ **Architecture**: Detailed system architecture  
- 📡 **API Reference**: Complete API documentation
- 🛠️ **Implementation**: Step-by-step setup guide

### Direct Server Usage

You can also run the documentation server directly:

```bash
python3 scripts/docs_server.py [port]
```

Then visit: `http://localhost:8080` (or your specified port)

Your browser will prompt for authentication credentials.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

## License

MIT License - see LICENSE file for details