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

git clone <repository>
cd langmem

2. Start Development Environment

./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

./scripts/test.sh

API Endpoints

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer langmem_api_key_2025

Core Endpoints

Store Memory

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

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

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

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:

# 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

# 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

# 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:

curl http://localhost:8765/health

Returns status for:

• Overall API health
• Ollama connectivity
• Supabase connection
• Neo4j database
• PostgreSQL database

Logs

View service logs:

# 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

# 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:

# 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:

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