clsplusplus 4.0.0

Brain-inspired, model-agnostic persistent memory architecture for LLMs

CLS++ — Continuous Learning System++

Switch AI models. Never lose context.

Quick Start • Architecture • Documentation • Deployment • Contributing

---

What is CLS++?

Every LLM in production today operates with amnesia. Sessions end, context windows clear, and the model forgets everything—preferences, corrections, facts established over months.

CLS++ is an external memory substrate that solves this at its root. Drawing from neuroscientific Complementary Learning Systems (CLS) theory, it implements:

Feature	Description
Four-store hierarchy	L0 (Working Buffer) → L1 (Indexing) → L2 (Schema Graph) → L3 (Deep Recess)
Biological consolidation	Salience, Usage, Authority, Conflict, Surprise signals
Sleep cycle	Nightly maintenance: rank, decay, deduplicate, consolidate
Reconsolidation gate	Belief revision only with evidence quorum
Model-agnostic	Any LLM plugs in via REST API—Claude, GPT-4, Gemini, Llama

Memory is external to the model. Switch models anytime. No reset.

---

Quick Start

Option A: SDK Client Only (talk to a running CLS++ server)

pip install clsplusplus          # lightweight: only httpx + pydantic

from clsplusplus import CLS

client = CLS(base_url="http://localhost:8080", api_key="your_api_key")
client.write("User prefers dark mode", namespace="user-123")
results = client.read("user preferences", namespace="user-123")
for item in results.items:
    print(item.text, item.confidence)

Option B: Run the Full Server Locally

# Clone and install with server dependencies
git clone https://github.com/rajamohan1950/CLSplusplus.git
cd CLSplusplus
pip install -e ".[server]"

# Start infrastructure (Redis + PostgreSQL)
docker compose up -d redis postgres

# Start the API server
uvicorn clsplusplus.api:app --host 0.0.0.0 --port 8080

Create an API key

# Register an integration and get your API key
curl -X POST http://localhost:8080/v1/integrations \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "namespace": "default"}'

# Response includes your API key (shown only once):
# {"id": "...", "keys": [{"key": "cls_live_xxxxxxxx", ...}], ...}

Write and read memories

# Write a memory
curl -X POST http://localhost:8080/v1/memory/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cls_live_xxxxxxxx" \
  -d '{"text": "User prefers dark mode", "namespace": "user-123"}'

# Read memories
curl -X POST http://localhost:8080/v1/memory/read \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cls_live_xxxxxxxx" \
  -d '{"query": "user preferences", "namespace": "user-123"}'

Python SDK (3-line integration)

from clsplusplus import CLS

client = CLS(base_url="http://localhost:8080", api_key="cls_live_xxxxxxxx")
client.memories.encode(content="User prefers dark mode", agent_id="a1")
results = client.memories.retrieve(query="user preferences", agent_id="a1")

---

Try It Live

Try the demo — Tell Claude something, ask OpenAI. Same memory. No sign-up.

---

Architecture

Client (any LLM) → POST /v1/memory/read (before inference)
                        ↓
              ┌─────────────────────────┐
              │   CLS++ Core Service    │
              │   L0: Working Buffer    │   ← Prefrontal Cortex
              │   L1: Indexing Store    │   ← Hippocampus
              │   L2: Schema Graph      │   ← Neocortex
              │   L3: Deep Recess       │   ← Thalamus
              │   Plasticity Engine     │
              │   Sleep Orchestrator    │
              └─────────────────────────┘
                        ↓
              POST /v1/memory/write (after inference)

---

SaaS Mode (Memory-as-a-Service)

Enable API key auth and rate limiting for production:

export CLS_API_KEYS=cls_live_xxxxxxxxxxxxxxxxxxxxxxxx
export CLS_REQUIRE_API_KEY=true
export CLS_RATE_LIMIT_REQUESTS=100
export CLS_RATE_LIMIT_WINDOW_SECONDS=60

Product endpoints: POST /v1/memories/encode, POST /v1/memories/retrieve, DELETE /v1/memories/forget, GET /v1/health/score. See SaaS docs.

---

Deployment

Platform	Guide
Render (free tier)	Deploy in 1 click • Setup guide
AWS Free Tier	CloudFormation • Step-by-step
AWS	CloudFormation
Azure	ARM template

---

Documentation

Document	Description
API Reference	Endpoints, auth, examples
API Blueprint	SaaS API playbook (DX, security, billing)
SaaS Strategy	Memory-as-a-Service, pricing
Marketplace Integration	AWS, Azure, GCP, OCI
Productionization	Deployment, security, compliance
Commercialization	Go-to-market, licensing

---

Status

Phase 1 (Foundation) — Complete

• Four stores (L0–L3) + Plasticity Engine
• Write/Read API + Python SDK
• Docker Compose + Render deploy
• Sleep cycle orchestrator
• Reconsolidation gate
• API key auth + rate limiting
• SaaS product endpoints

---

Contributing

We welcome contributions. See CONTRIBUTING.md and the Wiki for details.

---

License

Provisional patent filed October 2025. Apache 2.0 (see LICENSE).

---

AlphaForge AI Labs • Rajamohan Jabbala • 2026