A self-learning conversational AI that adapts permanently to each user — powered by the COGNET architecture.

Status: Fully implemented. All 22 COGNET components exist in 28 source files inside src/project_adam/, verified against architecture.md (564 lines) by 57 architecture compliance tests. 374 tests total. No stubs, no planned sections — the code is the architecture.

Built on Qwen2.5 (0.5B/1.5B/3B) with LoRA fine-tuning, running on consumer GPUs with 4GB+ VRAM. Optionally uses a remote API endpoint for generation while continuing to train via online distillation.

• Per-user adaptation — User detection, profiles, per-user LoRA adapters at agent_memory/adapters/{user}/
• Dual-backend generation — Local Qwen (auto-detected hardware tier) or remote API (OpenAI-compatible)
• Online distillation — Remote API responses train the local LoRA model, no separate pipeline needed
• Hardware auto-detection — Low tier (≤4GB Pascal) → API mode; Mid (8GB+ Volta) / High (24GB+ Ampere) → local mode
• Self-play learning — Autonomous background daemon thread generates (query, teacher_response) pairs from knowledge gaps
• Idle consolidation — Background thread runs 8-step cycle every 300s during conversation inactivity
• Persona generation — Create new personas via teacher API with multi-draft synthesis, auto-condensed to model tier
• 13 MCP tools — Query knowledge, teach, consolidate, switch personas, control self-play via stdio or SSE
• Persistent daemon mode — --daemon runs API + background self-play/consolidation 24/7
• Somatic markers — Damasio-style gut-feel bias that modulates fast/slow decision paths based on learned emotional associations
• DiffMemory — Compresses episodic patterns into differentiable MLP weights during consolidation, with Hebbian plasticity + STDP
• Streaming output — Tokens appear one-by-one
• Web UI — Gradio interface at localhost:7860 (--web)
• Voice mode — Speech-to-speech conversation (--voice)
• REST API — FastAPI on port 8765, includes OpenAI-compatible /v1/chat/completions (streaming + non-streaming)
• Web search — DuckDuckGo for general search, Wikipedia for knowledge (independent caches)
• Generation config — All 18 model.generate() parameters configurable via YAML, auto-detected per model size
• Reward-driven learning — Prospect-theoretic RPE (λ=2.25) broadcast to TDCore, SFL, SensoryEncoders, ProceduralMemory, SomaticMarker
• Configurable via YAML — config.yaml overrides device, model chain, quantization, generation params, backend mode

pip install -r requirements-dev.txt

# CLI chat
python3 -m project_adam

# Web UI
python3 -m project_adam --web

# Voice mode (needs mic + speakers)
python3 -m project_adam --voice

# Persistent daemon (API + background self-play + MCP SSE)
python3 -m project_adam --daemon

# REST API server (standalone)
./start_adam.sh
# or: PYTHONPATH=src uvicorn project_adam.api:app --host 0.0.0.0 --port 8765

# MCP server (stdio, for subprocess integration)
python3 -m project_adam --mcp

# Test OpenAI-compatible endpoint
curl http://localhost:8765/v1/models
curl -X POST http://localhost:8765/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"adam-cognet","messages":[{"role":"user","content":"Hello"}],"stream":false}'

export API_ENDPOINT="http://localhost:8765/v1"

Edit config.yaml:

backend:
  mode: "auto"  # auto-detects: low hardware → API, mid/high → local
  api:
    endpoint: "https://<remoteapibackend>/v1/chat/completions"
    key: ""
    model: "ai-model"

See COGNET Architecture for the full 564-line specification (10 principles, 22 components).

AgentOrchestrator ─┬─ SensoryEncoders (stacked β-VAE: text/vision/audio, precision-weighted)
                    ├─ WorkingMemory (3-buffer, PFC-gated, 7±2 chunk slots)
                    ├─ EpisodicMemory (SQLite, (s,a,r,c) tuples, SentenceTransformer)
                    ├─ SemanticMemory (schema graph, assimilation/accommodation)
                    ├─ ProceduralMemory (RL via RPE, n-gram chunking, Q-values)
                    ├─ SpatialMemory (GridCells + PlaceCells, 17 relations)
                    ├─ DiffMemory (2-layer MLP, gradient + Hebbian + STDP)
                    ├─ RLCore (TD(λ), Prospect-theoretic RPE λ=2.25)
                    ├─ SFL (7 features, Rescorla-Wagner, asymmetric loss)
                    ├─ BayesianWorldModel (conjugate priors, causal graph)
                    ├─ SomaticMarker (3-layer MLP 16→8→1, online post-RPE)
                    ├─ WebSearch (DDGS + Wikipedia, independent caches)
                    ├─ MetacognitiveController (MLP 9→32→16→5, REINFORCE)
                    ├─ LanguageInterface (dual-backend, persona builder)
                    ├─ ActionSelector (fast/slow dual-system, somatic bias)
                    ├─ OfflineConsolidator (8-step cycle: →TD→abstract+noise+Hebbian→prune→reentry→WM→procedural→re-encode)
                    ├─ SelfPlayLearner (daemon, 4 strategies, spaced repetition)
                    ├─ PersonaManager (list/load/switch/generate)
                    ├─ Persona (Markdown identity, behavioral rules)
                    ├─ MCP Server (13 tools, stdio + SSE)
                     └─ UserProfileManager (per-user state, LoRA adapters)

Qwen2.5-3B at 4-bit NF4 (~2.1GB VRAM). Falls back to 1.5B → 0.5B if unavailable. Tries each model in model_chain until one loads.

Remote API endpoint configured in config.yaml. Falls back to local model on failure. In auto mode, low-tier hardware automatically uses the API.

LoRA adapters (r=8, target_modules=["q_proj","v_proj"], α=16) trained every 10 interactions. Data sourced from both local and API responses (online distillation). Adapters saved per user at agent_memory/adapters/{user}/. RPE-scaled loss weights prioritize high-reward episodes.

config.yaml supports all runtime options:

device: cuda                       # "cuda" or "cpu"
base_model: Qwen/Qwen2.5-3B-Instruct
model_chain:
  - Qwen/Qwen2.5-3B-Instruct
  - Qwen/Qwen2.5-1.5B-Instruct
  - Qwen/Qwen2.5-0.5B-Instruct

backend:
  mode: "auto"                     # "auto", "local", or "api"
  api:
    endpoint: "https://<remoteapibackend>/v1/chat/completions"
    key: "${API_KEY}"
    model: "ai-model"
    timeout: 60

generation:
  max_new_tokens: 128
  temperature: 0.7
  top_p: 0.9

Copy config.yaml.example to config.yaml and edit.

# Stdio mode (for subprocess integration — Claude Desktop, etc.)
python3 -m project_adam --mcp

# SSE mode (persistent — connect via HTTP while daemon runs)
# MCP client connects to: http://localhost:8765/mcp/sse
python3 -m project_adam --daemon

# All tests
PYTHONPATH=src python3 -m pytest tests/ -v

# Single file
PYTHONPATH=src python3 -m pytest tests/test_diffmemory.py -v

# Architecture compliance (57 tests)
PYTHONPATH=src python3 -m pytest tests/test_architecture.py -v

374 tests across 32 test files covering all 22 components:

• Encoder (β-VAE forward, loss, sparsity, hardware tier, precision-weighting)
• Memory (working, episodic, semantic, procedural, spatial, diffmemory)
• RL core (TD update, actor policy, eligibility traces, Prospect theory)
• SFL (Q-learning, batch, negative reward, asymmetric loss)
• Metacognitive controller (MLP policy, REINFORCE, 5 actions)
• Language interface (generate, build_prompt, behavioral rules, utterance likeness)
• Action selection (Q-values, trajectory sim, fast/slow dual system, somatic bias)
• Integration (full chat flow, user detection, reward tracking, SFL updates)
• Web search (DDGS, Wikipedia, cache, independent methods)
• Profiles, persona, persona management, API endpoints
• Self-play (metacog gate, RPE path, episodic path, no training calls)
• MCP server (13 tools registered, canonical methods only)
• Somatic marker (online post-RPE update, prediction, profile state)
• World model (Bayesian conjugate, causal graph, transition simulation)
• Architecture compliance (57 tests) — verifies all 10 principles, 22 components against architecture.md
• Dataflow audit — validates RPE broadcast targets, PFC gate circular dependency break, consolidation order

• Minimum: NVIDIA GPU with 4GB+ VRAM (Pascal or newer) — or use remote API backend
• Recommended: NVIDIA GPU with 8GB+ VRAM (Volta or newer) for local generation
• Python 3.12+
• 6GB disk for Qwen2.5-3B model (~2GB quantized)
• API key required for remote API endpoint (set key in config.yaml)

AGPL v3 with commercial option — see LICENSE.

Free to use, modify, and distribute under the AGPL v3 terms. If you use this software in a proprietary product without releasing your source code, you must purchase a commercial license.