Solo Mode

Solo mode allows CogMem to run using SurrealDB only, providing a simpler deployment option ideal for personal knowledge systems.

Overview

Mode	Databases	Best For
Enterprise	Postgres + OpenSearch + Neo4j + Qdrant	Production, high-scale
Solo	SurrealDB only	Development, small deployments

Capabilities

In solo mode, SurrealDB provides all capabilities:

Capability	Enterprise Provider	Solo Provider
Object Storage	Postgres	SurrealDB
Event Queue	Postgres	SurrealDB
Text Search	OpenSearch	SurrealDB (full-text)
Vector Search	Qdrant	SurrealDB (cosine similarity)
Graph	Neo4j	SurrealDB (RELATE edges)

Limitations

Solo mode has some limitations compared to enterprise:

Text Search: No built-in highlighting (simulated), limited faceting
Vector Search: Performance may be lower for large datasets
Graph: No APOC procedures, simpler traversal

Setup

1. Install Dependencies

pip install cogmem-kos[solo]

2. Start SurrealDB

# In-memory (development)
docker run -d --name kos-surrealdb \
  -p 8000:8000 \
  surrealdb/surrealdb:latest \
  start --user root --pass root memory

# Persistent storage
docker run -d --name kos-surrealdb \
  -p 8000:8000 \
  -v ./data:/data \
  surrealdb/surrealdb:latest \
  start --user root --pass root file:/data/cogmem.db

3. Configure Environment

.env

KOS_MODE=solo

SURREALDB_URL=ws://localhost:8000/rpc
SURREALDB_NAMESPACE=cogmem
SURREALDB_DATABASE=kos
SURREALDB_USER=root
SURREALDB_PASSWORD=root

4. Initialize Schema

kos init

Or explicitly:

kos init --mode solo

5. Start Services

# API server
kos dev-server

# Worker (in another terminal)
kos run-worker

Schema

Solo mode creates these tables in SurrealDB:

Document Tables

Table	Description
`items`	Ingested documents
`passages`	Chunked text with embeddings
`entities`	Extracted named entities
`claims`	Structured assertions with evidence
`artifacts`	Generated content (dossiers, timelines, reports)
`kernel_events`	Kernel decision logs
`outbox_events`	Event queue

Adaptive Cognitive Plane Tables

Table	Description
`memory_strategies`	Versioned knowledge organization hypotheses
`outcome_events`	Append-only feedback signals (never deleted)
`strategy_change_proposals`	Proposed restructuring with rationale and risk

Graph Edges

Edge	Description
`mentions`	Passage → Entity
`has_passage`	Item → Passage
`related_to`	Entity → Entity

API Compatibility

All API endpoints work identically in solo mode:

# Search
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "demo", "query": "machine learning"}'

# Entity page
curl http://localhost:8000/entities/entity-123?tenant_id=demo

# Health check
curl http://localhost:8000/admin/health

Switching Modes

To switch from solo to enterprise:

Update KOS_MODE=enterprise in .env
Configure enterprise database connections
Run kos init to create schema
Data migration is manual (not provided in v1)

Troubleshooting

Connection Errors

SurrealDB error: Connection refused

Ensure SurrealDB is running:

docker ps | grep surrealdb
docker start kos-surrealdb

Schema Errors

Table 'items' already exists

Use --force to recreate:

kos init --mode solo --force

Import Errors

ImportError: surrealdb not installed

Install solo dependencies:

pip install cogmem-kos[solo]

Start Here

Platform

Architecture

Solo Mode

Solo Mode

Overview

Capabilities

Limitations

Setup

1. Install Dependencies

2. Start SurrealDB

3. Configure Environment

4. Initialize Schema

5. Start Services

Schema

Document Tables

Adaptive Cognitive Plane Tables

Graph Edges

API Compatibility

Switching Modes

Troubleshooting

Next Steps

Quick Start

Configuration

​Solo Mode

​Overview

​Capabilities

​Limitations

​Setup

​1. Install Dependencies

​2. Start SurrealDB

​3. Configure Environment

​4. Initialize Schema

​5. Start Services

​Schema

​Document Tables

​Adaptive Cognitive Plane Tables

​Graph Edges

​API Compatibility

​Switching Modes

​Troubleshooting

​Next Steps

Quick Start

Configuration

Solo Mode

Overview

Capabilities

Limitations

Setup

1. Install Dependencies

2. Start SurrealDB

3. Configure Environment

4. Initialize Schema

5. Start Services

Schema

Document Tables

Adaptive Cognitive Plane Tables

Graph Edges

API Compatibility

Switching Modes

Troubleshooting

Next Steps