A governance kernel for organizations that coordinate persistent human and agent roles.

Identity · Who it's for · Architecture · Repository map · Quickstart · Production · Status · Adoption · License & provenance

1. Identity

cognitive-firm lets one principal coordinate persistent AI agents under typed mandates, budget caps, human approval and work surfaces, and a tenant overlay pattern.

It is not an agent framework, an LLM SDK, or a chat client. It is the layer above those: persistent role offices with mandates, inboxes, sessions, signals, and audit trails.

The operating model is concrete: agents take actions with provenance, humans do bounded work with receipts, role offices exchange obligations, and only typed state transitions change the organization. A partner call, a restricted-system check, a code change, a forecast miss, and a governance proposal are different records because they create different follow-up obligations.

The human-agent work model is deliberately not "human approves every action" and not "agent autonomy with after-the-fact oversight." Agents can run quickly inside bounded envelopes. Humans contribute where they are the right actor or judge. The kernel records the state transitions that make the work reviewable. Start with docs/human-agent-work.md for that theory and its operational mapping.

It was extracted from a live research deployment and rewritten as a reusable kernel with tests, examples, and local deployment fixtures.

2. Who it's for & what it solves

The problem

Agent frameworks such as LangChain, AutoGen, CrewAI, and Letta are strongest when they model execution graphs, tool calls, memory, and agent interaction. This kernel focuses on a different layer: durable roles, authority, accountability, human work, leases, and audit surfaces around those runtimes.

Who should adopt this

• Single principals running a research lab, fund, or solo company who need persistent agents with bounded authority.
• Small teams (1-5 people) wanting one place where role mandates, budgets, audit trails, and approvals all live as files in git.
• Researchers building on top of a system that can be inspected, replayed, and forked rather than reverse-engineered from logs.

Explicit non-goals

Alternatives, briefly

• LangGraph / AutoGen / CrewAI: better fit if your unit of work is one graph, crew, or chat run. cognitive-firm is for orgs that persist; those runtimes can project lifecycle events into it.
• Letta / MemGPT: better fit if your problem is agent memory. cognitive-firm assumes the filesystem + git is the memory.
• n8n / Zapier: better fit if your problem is glue between SaaS APIs. cognitive-firm gates which role may invoke which MCP tool under what mandate.

3. Architecture

cognitive-firm is a small set of governance protocols and primitives stacked on a filesystem-backed system of record. Read docs/PROTOCOLS.md for the full spec; this section is the map.

The protocols

The invariants

The primitives serve a small conceptual core. See docs/kernel-invariants.md for the full map.

One diagram

┌─────────────────────────────────────────────────────────────────┐
│  PRINCIPAL (human)                                              │
│  ↕ H2A: Telegram (mobile) · Orbit (desktop) · CLI               │
│  ↕ A2H: bounded work requests · receipts · follow-up            │
└────────────────────────┬────────────────────────────────────────┘
                         │ approvals + bounded human work
┌────────────────────────▼────────────────────────────────────────┐
│  ROLE OFFICES (research_director, manager, debate_runner, …)   │
│  ↕ A2A: typed envelopes · obligation lifecycle · sagas         │
└────────────────────────┬────────────────────────────────────────┘
                         │ subprocess (env-scrubbed for OAuth)
┌────────────────────────▼────────────────────────────────────────┐
│  AGENT RUNTIMES (Claude Code, codex, future open-source)        │
│  Subscription quota for agent-side · API tokens for tools       │
└────────────────────────┬────────────────────────────────────────┘
                         │ MCP capability-gated outbox-relay
┌────────────────────────▼────────────────────────────────────────┐
│  EXTERNAL SYSTEMS (Linear, Salesforce, ERPs, ticketing)         │
└─────────────────────────────────────────────────────────────────┘

System of record: org/ (filesystem) + git history.
                  Audit trail = git log; UI = projection.

4. Repository map

New adopter? Start with docs/getting-started.md — the shortest path from zero to a running governed firm (pip install → cognitive-firm-distro install → point the tools at it → run it). The table below is the full reading order.

Reading the docs in Obsidian. This repository is an Obsidian vault — open the repo folder as a vault and README.md plus everything under docs/ is navigable with working links, backlinks, and graph view. The committed .obsidian/ directory carries the vault config (markdown links, relative paths); per-user UI state is gitignored. No setup needed beyond opening the folder.

Read in this order if you are new:

The repository root is also an Obsidian-compatible vault. Open the root folder in Obsidian to browse the Markdown docs with backlinks, graph view, and relative links.

5. Quickstart

Install

The fast path — install the kernel and its three CLIs from PyPI, then stand up a governed organization in one command:

pip install cognitive-firm
cognitive-firm-distro install starter-firm --into ./my-firm

./my-firm is now a governed firm — its own git repo, verified to boot. docs/getting-started.md is the full zero-to-running path.

Local development

Working on the kernel itself? Clone and install it editable:

git clone https://github.com/sparckix/cognitive-firm ~/cognitive-firm
cd ~/cognitive-firm
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Public verification path
make smoke-public
make smoke-docker

# Configure principal preferences
cp org/preferences/templates/principal.yaml org/preferences/principal.yaml
$EDITOR org/preferences/principal.yaml

# Configure environment — copy the template and fill in keys
cp .env.example .env
$EDITOR .env

# (optional) Use Claude Code subscription auth instead of API key
unset ANTHROPIC_API_KEY      # so claude prefers OAuth
claude setup-token

# Smoke test — preflight + one daemon tick in dry-run
python scripts/org_role_preflight.py --role research_director
python scripts/agent_daemon.py --role research_director --tick-once --dry-run
python -m cognitive_firm.orchestration.org_surface
make kernel-service-smoke
make app-integration-conformance
make app-service-integration-smoke
make source-coverage-walkthrough
make learning-loop-walkthrough
make backup-restore-smoke
make docs-surface-check

The dry-run tick discovers candidate work, prints what it would dispatch, and exits without spending budget. If preflight fails, it tells you which mandate or preference file is missing and how to create it.

.env.example documents every environment variable the kernel and Orbit dashboard read. Most variables are optional. At least one LLM API key is needed for model calls made by the kernel itself.

Managing organizations and packages

cognitive-firm-distro is how you install and manage governed organizations and packages — a governed organization in one action, rather than assembled by hand from the protocol catalog:

cognitive-firm-distro list
cognitive-firm-distro install starter-firm --into ./my-firm

install is transactional and git-backed: the target becomes its own git repository, the install lands as a commit tagged install/starter-firm/<version>, and the installer verifies the new organization's governance graph before committing it. A bad install is reversible — cognitive-firm-distro rollback starter-firm --into ./my-firm. The cognitive-firm-distro CLI also covers show, verify, upgrade, uninstall, and lint; a package can be installed from a git URL (SHA-pinned, recorded in a content-hashed packages.lock), and installing an overlay onto a running org files a governed authority-diff proposal — a package may not widen a role's authority. See docs/protocols/distribution.md.

Building and publishing your own package — distro or overlay — is covered in docs/community-packages.md: the publication rule (authorship is open, adoption is governed), the step-by-step authoring loop (lint → --dry-run → boot_check → publish as a git repo, no central registry), and a roadmap of suggested packages the ecosystem could use. Start from the template at docs/templates/package/.

The userland sits above the kernel as the operator-facing layer. The cognitive-firm-userland CLI shows what needs a human and the shared vocabulary:

cognitive-firm-userland needs-me <actor_id>   # the operator's attention queue
cognitive-firm-userland inbox <actor_id>      # a member-human's bounded work
cognitive-firm-userland vocabulary            # the shared userland glossary
cognitive-firm-userland status                # plain-language org health
cognitive-firm-userland resolve <gate_id> --option <opt>   # resolve a pending gate
cognitive-firm-userland proposals             # governance changes awaiting review
cognitive-firm-userland approve <proposal_id> # approve a governance change
cognitive-firm-userland decline <proposal_id> # decline a governance change

proposals / approve / decline are the governed-install human-review loop: a governance-change proposal awaits an operator decision, and approve / decline each record an attested kernel event.

The same attention queue is also rendered by the Orbit NeedsMePane.

6. Production deployment

VPS deployment uses systemd + bidirectional sync (mutagen) so the principal can edit mandates from a laptop while the daemon ticks 24/7.

Multi-tenant deployment: keep tenant content in a sibling private repo (<tenant>-research-co/tenants/<tenant>/) with mandates/, roles/, preferences/ overrides. Symlink overlays into cognitive-firm/org/ via a tenant setup script when running locally. The public git history and public Docker image should not contain tenant files.

7. Status

cognitive-firm has a tested T1 kernel surface and a lean multi-actor authority path through actor identity, actor membership, subject-scope checks, and leases. Adopters who read the protocol specs can rely on every "shipped" claim being backed by tests in tests/ and by the public verification commands:

make smoke-public
make smoke-docker

Shipped (T1 tested)

Queued

• MCP Phase 3: supply-chain pinning (digest + signed manifest + revocation feed)
• MCP Phase 4: IdP federation
• A2A remote adapter: cross-VPS role-to-role messaging

Deferred (T2 reactivation triggers)

Enterprise SSO administration, signed audit trail with TSA, event-outbox to Postgres, multi-server quorum, observability stack, cold-start recovery from snapshot, and tenant isolation across separate authority domains. Each has an explicit reactivation trigger documented in docs/PROTOCOLS.md; the repo should not imply deployment coverage it has not tested.

8. Adoption

Start with docs/adopting-cognitive-firm.md. The short version: keep the public kernel generic, put organization-specific roles and project content in a tenant overlay, and inspect the organization surface before material work.

9. License & provenance

License: Apache-2.0 (see LICENSE and NOTICE). Commercial use and modification are permitted; the only requirements are preserving the copyright notice and license terms in derivative works, and stating any significant changes you make. There is no source-availability restriction, no Business Source License, no dual-licensing — just Apache-2.0.

Contributing: see CONTRIBUTING.md.

Provenance: Extracted from a production research apparatus on 2026-05-07. Theoretical grounding (Chandlerian M-form, Holmström informativeness, Tirole incomplete contracts, Nelson & Winter routines) is developed in a companion paper: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6543019