cogg.cpp

A C++20 runtime for AI agents with durable state, bounded scheduling and recoverable model execution.

cogg.cpp stores an agent's state, memory, inbox and logical clock in SQLite. A model proposes a transition; the kernel checks its limits and commits accepted changes atomically to a SHA-256 history chain. After a process crash, the host can reopen the database and continue from the last committed state. Interrupted inference may run again and produce different text.

Status: experimental, v0.11.0. The project originated in the Physalia Gyre research program and can be embedded independently. Logical clocks and stored self-state are runtime mechanisms; they do not establish subjective experience.

• Durable transitions: atomic state and inbox updates, idempotent input, admission accounting and verifiable commit history.
• Bounded waking: model-requested wake times constrained by host intervals and attempt quotas.
• Memory: typed deposits, protected open tasks, version-aware lexical retrieval and source-linked compaction.
• Executor choices: a native CPU llama.cpp adapter, optional Ollama/Chat Completions adapters, or a custom C++ backend.
• Recovery: compatible native KV checkpoints can be restored; missing or incompatible caches cause reconstruction from committed state. HTTP executors reconstruct context and do not transfer native KV.
• Optional host modules: guarded self-state, a separate terminal client and host, and image observation with retained memory.

Recover one request by its idempotency key, read bounded history pages, open a database read-only, and explicitly recover from task memory pressure. See request recovery and memory budgets for examples. Existing schema-5 histories keep their original records.

Dependencies: C++20 compiler, CMake 3.20+, SQLite3 with FTS5, OpenSSL libcrypto and nlohmann/json 3.10+. CI runs on Ubuntu 24.04.

sudo apt-get install g++ cmake ninja-build libsqlite3-dev libssl-dev nlohmann-json3-dev
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j2
ctest --test-dir build --output-on-failure

The default build needs no model service. Python 3 enables additional process tests. Dockerfile.build provides a Debian build environment.

Options default to OFF. See validation for the full CI configuration and real-model tests.

This demo uses a deterministic backend. Run it with a new database:

./build/cogg-cli init demo.db explorer 100 100 60000
./build/cogg-cli send demo.db explorer greeting-1 "Hello, world!"
./build/cogg-cli run demo.db explorer 5 100
./build/cogg-cli inspect demo.db explorer
./build/cogg-cli verify demo.db explorer

For actual inference, follow Local models or HTTP executors. For an interactive session, see Terminal interface.

The embedding tutorial introduces cogg::Store, cogg::Backend and cogg::Runtime. Public headers live in include/cogg. The documentation index covers each implemented module; ARCHITECTURE.md preserves the broader research roadmap and includes proposals beyond the current implementation.

Current limits include CPU-only native inference, lexical retrieval misses, model-dependent answer quality, and incomplete long-duration scheduling validation. Audio, subject signatures and broader cognitive integration remain research work. See validation and limitations.

See CONTRIBUTING.md for checks and issue reports. MIT; see LICENSE. Dependencies retain their own licenses.