Installation
Requirements
- Python 3.12 or higher
- Docker (recommended for databases)
Install Package
# Enterprise mode (Postgres, OpenSearch, Neo4j, Qdrant)
pip install cogmem-kos[enterprise]
# Solo mode (SurrealDB only)
pip install cogmem-kos[solo]
# All providers
pip install cogmem-kos[all]
# Development
pip install cogmem-kos[dev]
poetry add cogmem-kos[enterprise]
uv add cogmem-kos[enterprise]
Optional Dependencies
| Extra | Packages | Use Case |
|---|---|---|
enterprise | asyncpg, opensearch-py, neo4j, qdrant-client | Production deployment |
solo | surrealdb | Single-database mode |
litellm | litellm | LLM and embedding support |
api | fastapi, uvicorn | HTTP API server |
dev | pytest, mypy, ruff | Development tools |
all | All of the above | Full installation |
Database Setup
Enterprise Mode
Postgres
Postgres
docker run -d --name kos-postgres \
-e POSTGRES_USER=kos \
-e POSTGRES_PASSWORD=kos \
-e POSTGRES_DB=cogmem_kos \
-p 5432:5432 \
postgres:16
OpenSearch
OpenSearch
docker run -d --name kos-opensearch \
-e "discovery.type=single-node" \
-e "DISABLE_SECURITY_PLUGIN=true" \
-p 9200:9200 \
opensearchproject/opensearch:2
Neo4j
Neo4j
docker run -d --name kos-neo4j \
-e NEO4J_AUTH=neo4j/password \
-p 7687:7687 -p 7474:7474 \
neo4j:5
Qdrant
Qdrant
docker run -d --name kos-qdrant \
-p 6333:6333 \
qdrant/qdrant
Solo Mode
SurrealDB
SurrealDB
# In-memory (development)
docker run -d --name kos-surrealdb \
-p 8000:8000 \
surrealdb/surrealdb:latest \
start --user root --pass root memory
# Persistent (production)
docker run -d --name kos-surrealdb \
-p 8000:8000 \
-v ./data:/data \
surrealdb/surrealdb:latest \
start --user root --pass root file:/data/cogmem.db
Docker Compose
For convenience, use Docker Compose:docker-compose.yml
version: '3.8'
services:
postgres:
image: postgres:16
environment:
POSTGRES_USER: kos
POSTGRES_PASSWORD: kos
POSTGRES_DB: cogmem_kos
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
opensearch:
image: opensearchproject/opensearch:2
environment:
- discovery.type=single-node
- DISABLE_SECURITY_PLUGIN=true
ports:
- "9200:9200"
volumes:
- opensearch_data:/usr/share/opensearch/data
neo4j:
image: neo4j:5
environment:
NEO4J_AUTH: neo4j/password
ports:
- "7687:7687"
- "7474:7474"
volumes:
- neo4j_data:/data
qdrant:
image: qdrant/qdrant
ports:
- "6333:6333"
volumes:
- qdrant_data:/qdrant/storage
volumes:
postgres_data:
opensearch_data:
neo4j_data:
qdrant_data:
docker-compose up -d
Verify Installation
# Check CLI is available
kos --help
# Initialize schema
kos init
# Check health
curl http://localhost:8000/admin/health
Next Steps
Configuration
Configure environment variables
Quick Start
Run your first search