clsplusplus 7.19.0

Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama.

CLS++ — Continuous Learning System++

Switch AI models. Never lose context.

Quick Start • MCP • Integrations • Architecture • Documentation • Deployment

---

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

Install

pip install clsplusplus          # Python SDK (lightweight: only httpx + pydantic)
npm install clsplusplus          # JavaScript / TypeScript SDK (zero runtime deps)

Optional Python extras pull in framework adapters or the full server:

pip install clsplusplus[server]      # run the FastAPI server yourself
pip install clsplusplus[crewai]      # CrewAI memory adapter
pip install clsplusplus[langgraph]   # LangGraph memory store
pip install clsplusplus[llamaindex]  # LlamaIndex memory block
pip install clsplusplus[autogen]     # Microsoft AutoGen memory provider

Both the PyPI and npm packages are named clsplusplus and ship the same Brain API. The npm package is a real TypeScript SDK (not just a CLI) — it mirrors the Python SDK method-for-method.

Python SDK

from clsplusplus import Brain

brain = Brain("alice")

# Teach it anything in natural language
brain.learn("I work at Google as a senior engineer")
brain.learn("I prefer Python over JavaScript")

# Ask it anything — semantic recall, not keyword matching
brain.ask("What's my job?")           # ["I work at Google as a senior engineer"]

# Get LLM-ready context for any prompt
brain.context("coding help")
# "Known facts about this user:\n- I work at Google..."

# Forget (GDPR right to be forgotten)
brain.forget("I work at Google as a senior engineer")

JavaScript / TypeScript SDK

import { Brain } from "clsplusplus";

const brain = new Brain("alice");

await brain.learn("I work at Google as a senior engineer");
const facts = await brain.ask("What's my job?");
const context = await brain.context("coding help");
await brain.forget("I work at Google as a senior engineer");

Use with OpenAI

from clsplusplus import Brain

brain = Brain("alice")

# Wrap any LLM function — auto-injects memory, auto-learns
@brain.wrap
def chat(system_prompt, user_message):
    return openai.chat(system=system_prompt, user=user_message)

response = chat("You are a helpful assistant", "Help me with Python")
# Brain auto-recalls relevant memory, injects into prompt,
# calls your LLM, learns from the exchange, returns response.

Full SDK API

The Brain class is identical in the Python and JS/TS SDKs (the JS methods are async). Constructor: Brain(user, api_key=None, url=None) in Python, new Brain(user, { apiKey, url }) in TypeScript. Both read CLS_API_KEY and CLS_BASE_URL from the environment when not passed; url defaults to https://www.clsplusplus.com.

Method	Description
brain.learn(fact, **meta)	Teach a fact. Returns memory ID.
brain.ask(question, limit=5)	Query for relevant facts. Returns list of strings.
brain.context(topic="", limit=8)	Get LLM-ready context string.
brain.forget(fact_or_id)	Forget by text or ID. Returns bool.
brain.absorb(content, source="document")	Bulk-learn from document, conversation, or list.
brain.who()	Auto-generated user profile dict.
brain.correct(wrong, right)	Update a belief (forget + learn).
brain.chat(message, llm_fn=None)	Full conversation handler with memory.
brain.teach(dict)	Learn from structured key/value data.
brain.watch(messages)	Learn from a list of chat messages.
brain.wrap(fn)	Wrap any LLM function with auto-memory.
brain.all(limit=50) / brain.count()	List / count what's stored.

Module-level one-liners (Python: import clsplusplus as mem; TS: import { learn, ask } from "clsplusplus") wrap a per-user Brain: learn(user, fact), ask(user, question), context(user, topic), forget(user, fact_or_id).

A lower-level CLSClient (alias CLS) is also exported for direct write / read / get_item / forget / sleep / health calls against the REST API — see the API Reference.

Connect via MCP (Claude, Cursor, Windsurf, ChatGPT)

CLS++ ships a Model Context Protocol server exposing three tools — recall_memories, store_memory, who_am_i — so any MCP client can read and write the same memory. Registry name: io.github.rajamohan1950/cls-memory.

Remote (hosted, OAuth) — add https://www.clsplusplus.com/mcp as a custom connector. The OAuth 2.1 + PKCE + Dynamic Client Registration flow handles auth; no API key to paste.

Local (stdio) — run the bundled server with an API key:

pip install clsplusplus
# one-line install for Claude Code:
claude mcp add cls-memory \
  --env CLS_API_URL=https://www.clsplusplus.com \
  --env CLS_API_KEY=cls_live_xxx \
  -- python3 -m clsplusplus.mcp_server

Or paste this into .claude/settings.json (Cursor/Windsurf use the same shape in their MCP config):

{
  "mcpServers": {
    "cls-memory": {
      "command": "python3",
      "args": ["-m", "clsplusplus.mcp_server"],
      "env": {
        "CLS_API_URL": "https://www.clsplusplus.com",
        "CLS_API_KEY": "cls_live_xxx"
      }
    }
  }
}

The dashboard's Connect button (GET /v1/mcp/connect) mints a fresh key and returns this exact block pre-filled. Create keys manually at https://www.clsplusplus.com/profile#api-keys.

Agent-framework integrations

CLS++ ships native memory adapters for four agent frameworks. Each is an optional extra and lazily imported — the base package never requires the framework. Full setup in docs/integrations.

Framework	Install	Class	Plugs in as
CrewAI	pip install clsplusplus[crewai]	clsplusplus.integrations.crewai.CLSMemoryStorage	ExternalMemory(storage=...) — docs
LangGraph	pip install clsplusplus[langgraph]	clsplusplus.integrations.langgraph.CLSMemoryStore	graph.compile(store=...) — docs
LlamaIndex	pip install clsplusplus[llamaindex]	clsplusplus.integrations.llamaindex.CLSMemoryBlock	Memory.from_defaults(memory_blocks=[...]) — docs
AutoGen	pip install clsplusplus[autogen]	clsplusplus.integrations.autogen.CLSMemory	AssistantAgent(memory=[...]) — docs

# Example: CrewAI
from crewai import Crew
from crewai.memory.external.external_memory import ExternalMemory
from clsplusplus.integrations.crewai import CLSMemoryStorage

crew = Crew(
    agents=[...], tasks=[...], memory=True,
    external_memory=ExternalMemory(storage=CLSMemoryStorage(user="my-crew")),
)

Editor integrations (Cursor, Codex, n8n) also have guides under docs/integrations.

Managed service

CLS++ runs as a fully managed service — no infrastructure to host. Install the SDK and point it at the hosted API:

pip install clsplusplus       # or: npm install clsplusplus

Get an API key and start storing memory at clsplusplus.com.

---

Try It Live

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

The Chrome extension (Web Store, v7.4.1) captures user messages from ChatGPT, Claude, and Gemini chat pages automatically and feeds them through the same memory pipeline. Host permissions: chatgpt.com, chat.openai.com, claude.ai, gemini.google.com. The Link Account popup differentiates 401 / 403 / network / unknown errors so you know whether the key is wrong, the account is unlinked, or the server is unreachable.

---

Architecture

Browser (extension/capture.js)          Any LLM client (SDK / REST)
        ↓                                       ↓
        ↓               www.clsplusplus.com (Vercel, Next.js)
        ↓                         │  rewrites /api/v1/*, /api/admin/*
        ↓                         ▼
        └──────────────►  Render-hosted FastAPI (clsplusplus-api)
                                  │  middleware: auth, rate limit, abuse-guard
                                  ▼
              ┌─────────────────────────────────────────┐
              │   CLS++ Core Service                    │
              │   L0: Redis working buffer              │ ← Prefrontal cortex
              │   L1: PostgreSQL+pgvector episodic      │ ← Hippocampus
              │   L2: Schema graph (crystallized)       │ ← Neocortex
              │   L3: Deep archive                      │ ← Thalamus
              │   PhaseMemoryEngine (gas→liquid→        │
              │     solid→glass, auto tier-compression) │
              │   SleepOrchestrator (replay + REM)      │
              │   ReconsolidationGate (belief revision) │
              │   Weblab (PostHog flags + auto-rollback)│
              │   Pricing control plane (memory-stored) │
              └─────────────────────────────────────────┘

Every user message captured in the extension and every SDK learn() call lands in L0, is promoted through the phase engine by the same thermodynamic rules, and is persisted to L1 in the background. There is no separate "explicit store" path — capture is continuous, tier compression is automatic.

---

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

# Abuse-guard (env-tunable; defaults shown)
export CLS_ABUSE_AUTHFAIL_THRESHOLD=60        # auth failures per IP per window
export CLS_ABUSE_AUTHFAIL_WINDOW_SECONDS=600  # 10 minutes
export CLS_ABUSE_WHITELIST_IPS=               # comma-separated operator IPs

Requests carrying a valid API key are exempt from auth-fail flood counting (see src/clsplusplus/abuse_guard.py).

Product endpoints: POST /v1/memories/encode, POST /v1/memories/retrieve, DELETE /v1/memories/forget, GET /v1/health/score, GET /v1/pricing, GET /v1/version, plus the in-app support desk (POST /v1/feedback, GET /v1/support/mine, POST /v1/support/{id}/rate). See SaaS docs.

Memory reads/writes are bound to the caller's own namespace server-side (_owned_namespace_for in api.py): a signed-in user can never read another tenant's memories by passing a namespace.

Pricing

CLS++ launched in India and bills via Razorpay (UPI / QR). Pricing is country-based — Indian users are billed in ₹, US in $, EU in €, resolved from the request's country (src/clsplusplus/currency.py). Published monthly tiers: Pro ₹999 / $29, Business ₹3,999 / $99, Enterprise ₹14,999 / $499, plus a free tier. Per-tier feature bundles are optimized by the bundle-pricing agent and exposed on GET /v1/pricing. The pricing control plane lives inside the CLS++ memory layer itself (reserved namespace __cls_pricing__), operator-tunable at runtime via POST /admin/pricing/config; defaults are seeded by src/clsplusplus/pricing_store.py. GET /v1/pricing is a public, abuse-exempt endpoint.

---

Deployment

CLS++ is a managed, hosted service — there's nothing to deploy. The production API runs at www.clsplusplus.com; enterprise and on-prem options are available on request.

---

Documentation

Document	Description
Architecture Overview	Components, stores, data flow, MCP
API Reference	Endpoints, auth, examples
Integrations	CrewAI, LangGraph, LlamaIndex, AutoGen, Cursor, Codex, n8n
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 (Dockerfile ships /app/scripts/ for operator tooling)
• Sleep cycle orchestrator
• Reconsolidation gate
• API key auth + rate limiting
• SaaS product endpoints
• Chrome extension (v7.4.1) capturing ChatGPT / Claude / Gemini
• Remote MCP server (OAuth 2.1 + PKCE + DCR) + stdio MCP server
• Native CrewAI / LangGraph / LlamaIndex / AutoGen memory adapters
• Abuse-guard with env-tunable thresholds and operator IP whitelist
• PostHog Weblab — staged rollouts with auto-rollback (5xx > 2% or p95 > 3s)
• Country-based pricing (₹ / $ / €) + agent-optimized feature bundles (Razorpay / UPI), memory-resident control plane
• In-app support desk ("Doctor") — agent-triaged feedback / bugs / questions with auto-resolution + per-user timeline
• Company agent platform — doctor-*, dynamic-pricing, bundle-pricing, competitive-intel, marketing-growth
• cls bench — runnable reliability reproductions (silent-loss, delete-on-conflict, dimension-switch, empty-extraction)
• Per-user memory isolation (server-side namespace binding)

Recent Architectural Decisions

• Auto-crystallization gated OFF by default. The Landauer liquid→solid pipeline produced low-quality [Schema: subject] token-soup entries that leaked into user-visible memory lists. Re-enable per process with CLS_ENABLE_AUTO_CRYSTALLIZATION=1. Melting still runs so existing schemas drain out. See src/clsplusplus/memory_phase.py.
• Pricing lives in the memory layer. Operator-tunable config (margin floor/target, infra cost, dynamic-demand toggle) and the bucketed demand history are stored as two fixed-id documents in namespace __cls_pricing__, not in env vars.
• Frontend ↔ backend topology. The Next.js frontend on Vercel (www.clsplusplus.com) rewrites /api/v1/* and /api/admin/* to the Render-hosted FastAPI. The bare onrender.com host is the internal upstream target — not the public surface.
• Integration ownership. POST /v1/integrations injects owner_email from the JWT-authed user; non-admin override returns 403. A backfill script handles legacy NULL rows.

Operator Runbooks

See docs/RUNBOOKS.md and docs/LAUNCH_RUNBOOK.md for incident response, deploy procedures, and the abuse-guard / weblab dashboards. The container ships operator scripts at /app/scripts/ (see scripts/admin_doctor.py, scripts/backfill_integration_owner_email.py).

---

Support

Questions or enterprise enquiries: clsplusplus.com or open a ticket at clsplusplus.com/tickets.

---

License

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

---

AlphaForge AI Labs • clsplusplus.com • 2026