Architecture

postgres:
  image: pgvector/pgvector:pg16
  environment:
    POSTGRES_DB: cems
    POSTGRES_USER: cems
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"

cems-server:
  build: .
  environment:
    CEMS_DATABASE_URL: postgresql://cems:${POSTGRES_PASSWORD}@postgres:5432/cems
    OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
    CEMS_ADMIN_KEY: ${CEMS_ADMIN_KEY}
  ports:
    - "8765:8765"
  depends_on:
    - postgres

cems-mcp:
  build: ./mcp-wrapper
  environment:
    CEMS_API_URL: http://cems-server:8765
  ports:
    - "8766:8766"
  depends_on:
    - cems-server

CREATE TABLE memory_documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    content TEXT NOT NULL,
    content_hash TEXT NOT NULL,  -- SHA256 for deduplication
    user_id TEXT NOT NULL,
    team_id TEXT,  -- NULL for personal, set for shared
    scope TEXT NOT NULL CHECK (scope IN ('personal', 'shared')),
    category TEXT DEFAULT 'general',
    title TEXT,
    source TEXT,  -- 'session', 'observer', 'manual', 'tool'
    source_ref TEXT,  -- 'project:myapp', 'repo:src/api.py:42'
    tags TEXT[] DEFAULT '{}',
    archived BOOLEAN DEFAULT false,
    priority REAL DEFAULT 1.0,
    pinned BOOLEAN DEFAULT false,
    pin_reason TEXT,
    pin_category TEXT,
    expires_at TIMESTAMPTZ,
    access_count INTEGER DEFAULT 0,
    last_accessed TIMESTAMPTZ DEFAULT NOW(),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes
CREATE INDEX idx_docs_user ON memory_documents(user_id);
CREATE INDEX idx_docs_team ON memory_documents(team_id);
CREATE INDEX idx_docs_scope ON memory_documents(scope);
CREATE INDEX idx_docs_category ON memory_documents(category);
CREATE INDEX idx_docs_source_ref ON memory_documents(source_ref);
CREATE INDEX idx_docs_archived ON memory_documents(archived) WHERE NOT archived;
CREATE UNIQUE INDEX idx_docs_content_hash ON memory_documents(content_hash, user_id);

CREATE TABLE memory_chunks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID NOT NULL REFERENCES memory_documents(id) ON DELETE CASCADE,
    chunk_index INTEGER NOT NULL,  -- Position in document (0-indexed)
    content TEXT NOT NULL,  -- Chunk content (up to 800 tokens)
    embedding vector(1536),  -- pgvector type (text-embedding-3-small)
    search_vector tsvector,  -- Full-text search (tsvector for BM25)
    created_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(document_id, chunk_index)
);

-- Vector similarity search (HNSW = Hierarchical Navigable Small World)
CREATE INDEX idx_chunks_embedding ON memory_chunks 
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);

-- Full-text search (GIN = Generalized Inverted Index)
CREATE INDEX idx_chunks_fts ON memory_chunks 
    USING gin (search_vector);

CREATE INDEX idx_chunks_document ON memory_chunks(document_id);

CREATE TRIGGER tsvector_update BEFORE INSERT OR UPDATE ON memory_chunks
    FOR EACH ROW EXECUTE FUNCTION
    tsvector_update_trigger(search_vector, 'pg_catalog.english', content);

CREATE TABLE users (
    id TEXT PRIMARY KEY,  -- Username
    api_key_hash TEXT NOT NULL,  -- bcrypt hash of API key
    team_id TEXT,  -- NULL for individual users
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    is_active BOOLEAN DEFAULT true
);

CREATE INDEX idx_users_team ON users(team_id);

CREATE TABLE teams (
    id TEXT PRIMARY KEY,  -- Team name
    display_name TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE category_summaries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id TEXT,
    team_id TEXT,
    category TEXT NOT NULL,
    scope TEXT NOT NULL CHECK (scope IN ('personal', 'shared')),
    summary TEXT NOT NULL,
    item_count INTEGER NOT NULL,
    last_updated TIMESTAMPTZ DEFAULT NOW(),
    version INTEGER DEFAULT 1
);

CREATE INDEX idx_summaries_user ON category_summaries(user_id);
CREATE INDEX idx_summaries_team ON category_summaries(team_id);
CREATE UNIQUE INDEX idx_summaries_unique ON category_summaries(
    COALESCE(user_id, ''), 
    COALESCE(team_id, ''), 
    category, 
    scope
);

# Start llama.cpp server
cd llama.cpp
./llama-server \
    -m models/nomic-embed-text-v1.5.Q8_0.gguf \
    --embedding \
    --port 8080

# Configure CEMS
export CEMS_EMBEDDING_BACKEND=llamacpp_server
export CEMS_LLAMACPP_BASE_URL=http://localhost:8080
export CEMS_EMBEDDING_DIMENSION=768

async def embed_batch(texts: list[str]) -> list[list[float]]:
    """Embed multiple texts in a single API call."""
    response = await client.post(
        "/embeddings",
        json={"input": texts, "model": model}
    )
    return [item["embedding"] for item in response["data"]]

curl -X POST http://localhost:8765/admin/users \
  -H "Authorization: Bearer $CEMS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "team_id": "engineering"}'

# Response:
# {"api_key": "cems_usr_a8f7b2c1d3e4f5a6b7c8d9e0f1a2b3c4"}

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.cron import CronTrigger

scheduler = BackgroundScheduler()

# Nightly consolidation (3 AM)
scheduler.add_job(
    consolidate_duplicates,
    CronTrigger(hour=3, minute=0),
    id="consolidation"
)

# Nightly observation reflection (3:30 AM)
scheduler.add_job(
    reflect_observations,
    CronTrigger(hour=3, minute=30),
    id="observation_reflection"
)

# Weekly summarization (Sunday 4 AM)
scheduler.add_job(
    summarize_old_memories,
    CronTrigger(day_of_week="sun", hour=4, minute=0),
    id="summarization"
)

# Monthly re-indexing (1st of month, 5 AM)
scheduler.add_job(
    reindex_embeddings,
    CronTrigger(day=1, hour=5, minute=0),
    id="reindexing"
)

cems add "I prefer dark mode"           # Add memory
cems search "coding preferences"        # Search
cems list                               # List all
cems status                             # System status
cems health                             # Health check
cems setup                              # Configure IDE hooks
cems update                             # Update + re-deploy hooks
cems maintenance --job consolidation   # Run maintenance
cems uninstall                          # Remove hooks

# Start observer
cems-observer &

# Or via systemd
sudo systemctl enable cems-observer
sudo systemctl start cems-observer

# 1. Clone repository
git clone https://github.com/chocksy/cems.git && cd cems

# 2. Configure environment
cp .env.example .env
# Edit .env with OPENROUTER_API_KEY and CEMS_ADMIN_KEY

# 3. Start services
docker compose up -d

# 4. Create first user
source .env
curl -X POST http://localhost:8765/admin/users \
  -H "Authorization: Bearer $CEMS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'

OPENROUTER_API_KEY=sk_or_v1_xxx  # From https://openrouter.ai/keys
CEMS_ADMIN_KEY=$(openssl rand -hex 32)  # Admin authentication

POSTGRES_PASSWORD=cems_secure_password  # Change in production
CEMS_EMBEDDING_BACKEND=openrouter  # or llamacpp_server
CEMS_EMBEDDING_DIMENSION=1536  # 1536 for OpenRouter, 768 for llama.cpp
CEMS_RERANKER_BACKEND=disabled  # Reranker support (future)

# Backup PostgreSQL
docker exec cems-postgres pg_dump -U cems cems > backup.sql

# Restore
cat backup.sql | docker exec -i cems-postgres psql -U cems cems