hummbl-cognition

Cognitive Ledger Protocol (CLP) and Open Brain server for HUMMBL agent reasoning.

What this is

The cognition layer for the HUMMBL multi-agent platform. Provides:

• CLP v1.1 (Cognitive Ledger Protocol) — append-only JSONL ledger with SHA-256 hash-chaining for tamper-evident shared memory
• Open Brain — HTTP server with BM25 search and lineage graph API
• Sigil Forge — DSL compiler and execution engine for governed agent rituals
• Belonging/HRSI — belonging baseline checks and HRSI check-in tooling
• Receipt modules — 17 receipt types for audit trails (issueops, dispatcher, compliance, HIBP, etc.)
• Migration tooling — import from bus history, git log, and memory markdown

Architecture

ledger_writer.py     → append-only JSONL with O(1) hash-chaining & HMAC verification
query.py             → search and retrieve from the ledger
boot_context.py      → session startup context loading
server.py            → Open Brain HTTP server (:11435) with /lineage graph API
consolidator.py      → nightly ledger aggregation
sigil_forge/         → DSL compiler, execution engine, policy, rituals, evals

Installation

pip install hummbl-cognition

# With governance integration (kill switch, security arbiter):
pip install "hummbl-cognition[governance]"

CLI

python -m hummbl_cognition post "insight text here"
python -m hummbl_cognition query "search term"
python -m hummbl_cognition validate
python -m hummbl_cognition state
python -m hummbl_cognition boot
python -m hummbl_cognition search "pattern"
python -m hummbl_cognition reindex

Key Modules

CLP v1.1 Metadata Extensions

• previous_hash: SHA-256 hex digest of the preceding raw ledger JSONL line (cryptographic tamper-evidence)
• valid_time: ISO 8601 UTC timestamp tracking when a fact occurred in reality (bi-temporal support)
• contests: Target entry ID being disputed/refuted (explicit belief-DAG support)

State Files

• _state/cognition/ledger.jsonl — the canonical append-only ledger
• _state/cognition/state.json — current cognitive state
• _state/cognition/intent.md — current sprint intent

Dependencies

• Required: hummbl-bus (bus writer for coordination messages)
• Optional: hummbl-governance (kill switch, security arbiter — install with [governance] extra)
• Stdlib-only core — no other third-party runtime dependencies

Rules

• Ledger is APPEND-ONLY — never delete, never mutate entries
• Open Brain server binds 127.0.0.1 only
• Consolidator runs periodically via scheduler

Related

• hummbl-bus — coordination bus
• hummbl-governance — governance primitives
• hummbl-skills — agent skills registry
• hummbl-agent — governed control plane

Learn more at hummbl.io.

License

MIT.