Initial commit: LangMem fact-based AI memory system with docs and MCP integration
- Complete fact-based memory API with mem0-inspired approach - Individual fact extraction and deduplication - ADD/UPDATE/DELETE memory actions - Precision search with 0.86+ similarity scores - MCP server for Claude Code integration - Neo4j graph relationships and PostgreSQL vector storage - Comprehensive documentation with architecture and API docs - Matrix communication integration - Production-ready Docker setup with Ollama and Supabase 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Docker Config Backup
292
README.md
Normal file
292
README.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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
|
||||
- 🧪 **Comprehensive Tests**: Unit and integration tests
|
||||
|
||||
## 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-project
|
||||
```
|
||||
|
||||
### 2. Start Development Environment
|
||||
|
||||
```bash
|
||||
./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
|
||||
./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"
|
||||
}
|
||||
```
|
||||
|
||||
## 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-project/
|
||||
├── src/
|
||||
│ └── api/
|
||||
│ └── main.py # Main API application
|
||||
├── tests/
|
||||
│ ├── test_api.py # API unit tests
|
||||
│ ├── test_integration.py # Integration tests
|
||||
│ └── conftest.py # Test configuration
|
||||
├── docker-compose.yml # Docker services
|
||||
├── Dockerfile # API container
|
||||
├── requirements.txt # Python dependencies
|
||||
├── start-dev.sh # Development startup
|
||||
├── test.sh # Test runner
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
./test.sh all
|
||||
|
||||
# Unit tests only
|
||||
./test.sh unit
|
||||
|
||||
# Integration tests only
|
||||
./test.sh integration
|
||||
|
||||
# Quick tests (no slow tests)
|
||||
./test.sh quick
|
||||
|
||||
# With coverage
|
||||
./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
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user