Metadata-Version: 2.4
Name: clsplusplus
Version: 7.0.0
Summary: Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama.
Author-email: AlphaForge AI Labs <contact@alphaforge.ai>
Maintainer-email: Rajamohan Jabbala <contact@alphaforge.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/rajamohan1950/CLSplusplus
Project-URL: Documentation, https://github.com/rajamohan1950/CLSplusplus/wiki
Project-URL: Repository, https://github.com/rajamohan1950/CLSplusplus
Project-URL: Bug Tracker, https://github.com/rajamohan1950/CLSplusplus/issues
Project-URL: Changelog, https://github.com/rajamohan1950/CLSplusplus/releases
Project-URL: API Reference, https://github.com/rajamohan1950/CLSplusplus/blob/main/docs/API_DOCUMENTATION.md
Project-URL: Source Code, https://github.com/rajamohan1950/CLSplusplus/tree/main/src
Project-URL: Download, https://github.com/rajamohan1950/CLSplusplus/releases
Keywords: llm,memory,ai,persistent-memory,model-agnostic,brain,openai,anthropic,claude,gemini,langchain,continuous-learning,semantic-search,vector-database,conversational-ai,rag,context-window
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.5.0
Provides-Extra: server
Requires-Dist: fastapi>=0.109.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "server"
Requires-Dist: redis>=5.0.0; extra == "server"
Requires-Dist: asyncpg>=0.29.0; extra == "server"
Requires-Dist: pgvector>=0.2.4; extra == "server"
Requires-Dist: sentence-transformers>=2.2.0; extra == "server"
Requires-Dist: numpy>=1.24.0; extra == "server"
Requires-Dist: pydantic-settings>=2.1.0; extra == "server"
Requires-Dist: python-multipart>=0.0.6; extra == "server"
Requires-Dist: structlog>=24.1.0; extra == "server"
Requires-Dist: apscheduler>=3.10.0; extra == "server"
Requires-Dist: PyJWT>=2.8.0; extra == "server"
Requires-Dist: bcrypt>=4.1.0; extra == "server"
Requires-Dist: stripe>=7.0.0; extra == "server"
Requires-Dist: razorpay>=1.4.0; extra == "server"
Requires-Dist: minio>=7.2.0; extra == "server"
Requires-Dist: pyarrow>=14.0.0; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: httpx>=0.26.0; extra == "dev"
Dynamic: license-file

  CLS++

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)](https://en.wikipedia.org/wiki/Complementary_learning_systems) 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

```bash
pip install clsplusplus          # Python (lightweight: only httpx + pydantic)
npm install clsplusplus          # JavaScript / TypeScript (zero dependencies)
```

### Python SDK

```python
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

```typescript
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

```python
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 API

| Method | Description |
|--------|-------------|
| `brain.learn(fact)` | Teach a fact. Returns memory ID. |
| `brain.ask(question)` | Query for relevant facts. Returns list. |
| `brain.context(topic)` | Get LLM-ready context string. |
| `brain.forget(fact)` | Forget by text or ID. |
| `brain.absorb(text)` | Bulk-learn from document or conversation. |
| `brain.who()` | Auto-generated user profile. |
| `brain.correct(old, new)` | Update a belief. |
| `brain.chat(message, llm)` | Full conversation handler with memory. |
| `brain.teach(dict)` | Learn from structured data. |
| `brain.watch(messages)` | Learn from chat message history. |
| `brain.wrap(fn)` | Wrap any LLM function with auto-memory. |

### Run the Full Server Locally

```bash
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:create_app --factory --host 0.0.0.0 --port 8080
```

---

## Try It Live

**[Try the demo](https://clsplusplus.onrender.com)** — 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:

```bash
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](docs/SAAS_MEMORY_AS_SERVICE.md).

---

## Deployment

| Platform | Guide |
|----------|-------|
| **Render** (free tier) | [Deploy in 1 click](https://render.com/deploy?repo=https://github.com/rajamohan1950/CLSplusplus) • [Setup guide](docs/DEPLOY_RENDER.md) |
| **AWS Free Tier** | [CloudFormation](infrastructure/aws/cloudformation-free-tier.yaml) • [Step-by-step](infrastructure/aws/FREE_TIER_GUIDE.md) |
| **AWS** | [CloudFormation](infrastructure/aws/cloudformation.yaml) |
| **Azure** | [ARM template](infrastructure/azure/arm-template.json) |

---

## Documentation

| Document | Description |
|----------|-------------|
| [API Reference](docs/API_DOCUMENTATION.md) | Endpoints, auth, examples |
| [API Blueprint](docs/API_BLUEPRINT.md) | SaaS API playbook (DX, security, billing) |
| [SaaS Strategy](docs/SAAS_MEMORY_AS_SERVICE.md) | Memory-as-a-Service, pricing |
| [Marketplace Integration](docs/MARKETPLACE_INTEGRATION.md) | AWS, Azure, GCP, OCI |
| [Productionization](docs/PRODUCTIONIZATION_ROADMAP.md) | Deployment, security, compliance |
| [Commercialization](docs/COMMERCIALIZATION_STRATEGY.md) | Go-to-market, licensing |

---

## Status

**Phase 1 (Foundation)** — Complete

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

---

## Contributing

We welcome contributions. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) and the [Wiki](https://github.com/rajamohan1950/CLSplusplus/wiki) for details.

---

## License

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

---

  AlphaForge AI Labs • Rajamohan Jabbala (https://github.com/rajamohan1950) • 2026

