cogos

CogOS

A cognitive daemon for AI agents. Written in Go. Runs locally.

make build && ./cogos serve --workspace ~/my-project
# http://localhost:6931/health

What this is

cogos is a Go daemon that runs locally and gives AI tools persistent workspace memory, scored context per prompt, and cross-session continuity. Claude Code, Cursor, and any tool that can call a local endpoint or run a hook can plug into it.

The kernel owns workspace state. It intercepts each prompt before the model sees it, scores all workspace documents by relevance, and injects a focused context window. Externalized attention: the substrate decides what's relevant, not the model. It routes inference through local or cloud providers. It keeps a hash-chained ledger of every decision. It runs reconcilers that maintain workspace invariants (plan, apply, drift detection, topological ordering), the same shape as Kubernetes-era control loops, applied to AI workspace state.

Your codebase or project directory sits untouched. CogOS adds a .cog/ overlay alongside .git/, or in a directory by itself. Everything runs on your machine. Nothing leaves unless you choose.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Your AI tools                                          │
│  Claude Code · Cursor · custom agents · Ollama · ...    │
└────────────────────┬────────────────────────────────────┘
                     │ hooks · MCP · HTTP
                     ▼
┌─────────────────────────────────────────────────────────┐
│  CogOS kernel  (local Go daemon)                        │
│  Owns workspace state. Hosts subsystems. Exposes        │
│  protocol surfaces for whatever AI tool plugs in.       │
└────────────────────┬────────────────────────────────────┘
                     │ reads & writes
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Workspace  (any directory)                             │
│                                                         │
│    your-project/                                        │
│    ├─ src/  docs/  ...    ← your stuff, untouched       │
│    ├─ .git/               ← code history (optional)     │
│    └─ .cog/               ← cognitive overlay           │
│       ├─ mem/    cogdocs (memory)                       │
│       ├─ run/    bus events, traces                     │
│       └─ ledger/ hash-chained record                    │
└─────────────────────────────────────────────────────────┘

Three pieces:

• Your AI tools speak to the kernel through hooks, MCP, and HTTP. Anything that can call a local endpoint or run a hook can plug in.
• The CogOS kernel is one local Go daemon. It owns workspace state, hosts subsystems (context assembly, inference routing, reconcilers, event bus, ledger), and exposes the protocol surfaces.
• The workspace is any directory you point the kernel at. CogOS adds a .cog/ overlay alongside whatever else is there. Same shape regardless of what's in the directory.

How the kernel is organized internally

The kernel has three internal layers:

┌──────────────────────────────────────────────────────────────┐
│  Membrane          HTTP API · MCP Server · Provider Router   │
│                    Event Broker (SSE) · Config API           │
├──────────────────────────────────────────────────────────────┤
│  Workspace         Context Engine · Memory · Ledger          │
│                    Salience Scorer · Blob Store · Traces     │
│                    Conversation Sidecars · Kernel Slog       │
├──────────────────────────────────────────────────────────────┤
│  Nucleus           Process Loop · Identity · State FSM       │
│                    Agent Harness · CogBus · Tool-call Gate   │
└──────────────────────────────────────────────────────────────┘

Membrane is the API surface. Serves OpenAI and Anthropic-compatible chat endpoints, the always-on MCP Streamable HTTP server, the Anthropic Messages API proxy, the event broker with SSE streaming, and the config mutation API. Routes inference requests to local or cloud providers. Binds to 127.0.0.1:6931 by default; --bind or bind_addr in YAML relaxes CORS when set to a non-loopback interface.

Workspace is where state lives. The context engine scores documents and arranges them into stability zones optimized for KV cache reuse. The ledger is append-only and hash-chained. Traces capture attention, proprioceptive state, and internal request metabolites. Conversation sidecars persist full turn text. Memory persists across sessions.

Nucleus is the process loop. Runs continuously through four states (Active, Receptive, Consolidating, Dormant). Manages identity, consolidation, workspace lifecycle, the homeostatic agent harness, the tool-call hallucination gate, and emits to the kernel slog (stderr tee plus .cog/run/kernel.log.jsonl).

How foveated context works

When you submit a prompt in Claude Code, the UserPromptSubmit hook fires and calls the CogOS daemon. The term "foveated" is borrowed from the eye, where the fovea is the high-resolution center: the context engine places what matters most in front of the model and lets the rest recede.

The context engine:

1. Scores all workspace documents using a 2.3M-parameter Mamba SSM trained as a context retrieval model, combined with git-derived salience
2. Ranks by a composite signal (edit recency, semantic match, structural importance)
3. Assembles a context window organized into stability zones:

1. Injects the assembled context into the prompt before it reaches the model

The model sees a pre-focused window instead of everything-or-nothing. Zone ordering is tuned for KV cache reuse: stable content stays at the front of the window across prompts, reducing cache misses. See docs/EVALUATION.md for the retrieval methodology.

Feature summary

Context and memory

• Externalized attention. The kernel intercepts each prompt, scores workspace documents by relevance, and injects a focused context window before the model sees it. Relevance scoring is done by the substrate, not the model.
• Foveated context assembly. A live UserPromptSubmit hook fires on every prompt. Documents are ranked and arranged into stability zones optimized for KV cache reuse.
• Workspace memory. Hierarchical memory with salience scoring and temporal attention. Your workspace remembers across sessions, models, and tools. Switch from Claude Code to Cursor and back. Same memory, same context.
• Conversation persistence. turn.completed ledger events plus a per-session sidecar at .cog/run/turns/<sessionID>.jsonl preserve full prompt and response text.
• Foveated decomposition pipeline. cog decompose processes any input through the kernel into four tiers: Tier 0 (one-sentence), Tier 1 (paragraph), Tier 2 (full CogDoc with sections and embeddings), Tier 3 (raw, gated). Includes an interactive workbench TUI (--workbench), embedding co-generation, content-addressed CogDoc storage, and bus event emission.

Inference and routing

• Multi-provider routing. OpenAI-compatible and Anthropic Messages-compatible HTTP API. Works with Ollama, LM Studio, Claude, and any OpenAI-compatible endpoint. Local models preferred by default.
• Anthropic Messages API proxy. Transparent proxy at POST /v1/messages that forwards to the Anthropic API with streaming SSE passthrough. Enables cog claude to route Claude Code through the kernel via ANTHROPIC_BASE_URL.

Observability

• Hash-chained ledger. CogBlock protocol for content-addressed, hash-chained records. Every routing decision, context assembly, state transition, turn completion, tool call, and config mutation is recorded in an append-only ledger (SHA-256, RFC 8785) with optional chain verification.
• Three observability lanes. The kernel exposes ledger (durable hash-chained events), traces (client metabolites + attention + proprioceptive state), and kernel slog (structured runtime logs) as non-overlapping surfaces. Each has a dedicated MCP tool, HTTP endpoint, and on-disk format.
• Live event bus. AppendEvent fans into an in-process broker with SSE streaming at /v1/bus/:id/events/stream. Subscribers see writes in real time; offline writers go straight to JSONL.

Coordination

• Reconcilers. A generic plan/apply control loop (in pkg/reconcile) runs registered providers: agent, component, discord, eval, mcp-tools, and service. Each provider implements Reconcilable (seven methods: Type, LoadConfig, FetchLive, ComputePlan, ApplyPlan, BuildState, Health). The orchestrator handles plan, apply, drift detection, topological ordering (Kahn's sort), and three-axis status (Sync, Health, Operation) for all providers.
• Kernel-native session management. SessionRegistry + HandoffRegistry with atomic-claim semantics: first-wins enforced at the bus boundary, not just in the in-memory cache. Bus stays ground truth; the registries are derived views rebuilt from seq-sorted replay on startup.
• Native agent harness. A homeostatic assessment loop runs as a goroutine inside the kernel. Calls a local model via Ollama with six kernel-native tools. Adaptive interval (5m-30m) based on assessment urgency, with panic recovery.
• MCP Streamable HTTP. Full MCP transport at POST /mcp with JSON-RPC 2.0, session management, and 30-minute expiry. Always-on (no build tag). 30 tools spanning observability, agent control, config, memory, sessions, handoffs, and voice.
• Config mutation API. cog_read_config / cog_write_config / cog_rollback_config MCP tools and matching REST surface. RFC 7396 merge-patch semantics with atomic writes and rotating backups.

For endpoint and tool counts, see the HTTP API and MCP tools tables below.

Exposure surfaces

Three non-overlapping observability lanes, each with an MCP tool, HTTP endpoint, and on-disk artifact:

The live event bus is a fourth surface for real-time subscribers: SSE at /v1/bus/:id/events/stream, plus cog_tail_events and cog_query_events MCP tools. All AppendEvent writes fan through the broker.

Library packages (pkg/)

Seven importable Go packages extracted into a go.work multi-module workspace. Each has its own go.mod and can be imported independently of the kernel. Six are stdlib-only; pkg/bep requires google.golang.org/protobuf.

Agent harness

The native Go agent harness runs a homeostatic assessment loop inside the kernel process:

• Calls a local model via Ollama's native /api/chat (with think: false)
• Adaptive interval: 5m idle, scales to 30m when assessment urgency is low
• Panic recovery: a crash in the agent goroutine doesn't take down the kernel
• State and loop control over MCP (cog_list_agents, cog_get_agent_state, cog_trigger_agent_loop) and REST (/v1/agents[/...]). The singular /v1/agent/{status,traces,trigger} routes are preserved byte-for-byte for the embedded dashboard.

Six kernel-native tools are available to the agent itself:

HTTP API

All endpoints serve on port 6931 by default. --bind <addr> (or bind_addr in YAML) overrides; CORS is strict on loopback and relaxed on non-loopback binds.

MCP tools (30 total)

The always-on MCP server groups tools by surface. The mcpserver build tag was removed in #9. MCP ships in every binary.

Sessions are created on initialize and expire after 30 minutes of inactivity.

Providers

Ships with adapters for Anthropic, Ollama, Claude Code, and Codex. New providers implement six methods.

CLI

cog wraps the daemon with subcommands for the common lifecycle plus the event bus:

cog serve               # Start the daemon (--bind <addr> to expose beyond loopback)
cog claude              # Launch Claude Code with ANTHROPIC_BASE_URL set to the kernel
cog decompose ...       # Run the 4-tier foveated decomposition pipeline
cog emit ...            # Write an event through the engine (no more silent drops)
cog bus watch|tail|list # Read the event bus
cog bus send ...        # Write to the bus. Direct JSONL by default; --http for SSE broadcast

cog emit was migrated to the engine in #23 (Track 5 Phase 1): the root cmdEmit is retained for compat but the engine path fixes the silent-drop bug where hooks returned success without writing to the ledger.

Getting started

Requirements

• Go 1.25+
• macOS, Linux, or Windows

Build and run

git clone https://github.com/cogos-dev/cogos.git
cd cogos
make build

# Initialize a workspace
./cogos init --workspace ~/my-project

# Start the daemon
./cogos serve --workspace ~/my-project

# Verify it's running
curl -s http://localhost:6931/health | jq .

Cross-compile

make build-linux-amd64
make build-linux-arm64    # Unblocked in #31 (syscall.Dup2 -> unix.Dup2)
make build-darwin-arm64
make build-windows-amd64  # Added in #15; see docs for install steps

Route Claude Code through the kernel

cog claude
# Sets ANTHROPIC_BASE_URL to http://localhost:6931 and starts Claude Code

Developer setup

./scripts/setup-dev.sh    # Build, install to ~/.cogos/bin, configure PATH

Docker

make image        # Build production image
make run          # Run with workspace volume mount
make e2e          # Build + run full cold-start test in a container

A Docker Compose topology with bridge-{primary,secondary} and tailscale-{primary,secondary} siblings landed in #19.

Testing

make test         # Unit tests (with -race)
make e2e-local    # Full cold-start lifecycle test
make e2e          # Containerized e2e (Docker)

Ledger and sync-watcher tests are stable under -count>=2 (#30).

Project layout

cmd/cogos/              Entry point (thin; delegates to internal/engine)
internal/engine/        Kernel sources and tests
pkg/                    Importable library packages (go.work multi-module)
  cogblock/             Content-addressed blocks and ledger
  coordination/         Agent coordination primitives
  bep/                  BEP wire protocol types
  reconcile/            Reconciliation framework
  modality/             Modality bus and channel types
  cogfield/             Field graph types
  uri/                  URI parsing and namespaces
sdk/                    Go SDK for CogOS clients
docs/                   Specs, architecture docs, provider guide
scripts/                Setup, CLI wrapper, e2e tests, experiment harnesses

Status

v3 kernel. Ground-up rewrite after a year of daily use across Claude Code, Cursor, and custom agent harnesses.

Working

• Continuous process daemon with four-state FSM
• Foveated context assembly with a 2.3M-parameter Mamba SSM context retrieval model
• Hash-chained append-only ledger with optional chain verification
• Three-lane observability: ledger, traces, kernel slog
• Live event bus with in-process broker and SSE streaming
• Conversation persistence (turn sidecars + ledger turn.completed events)
• Tool-call observability with pending-call correlation cache (1024 / 10min)
• Config mutation API (MCP + REST, merge-patch, atomic write, rollback)
• Agent state and loop control over MCP and REST (singular routes preserved)
• Multi-provider routing (Ollama, Anthropic, Claude Code, Codex)
• Always-on MCP Streamable HTTP server (30 tools, sessions, JSON-RPC 2.0)
• Kernel-native session management with atomic handoff claim (bus-level first-wins via append-before-apply; seq-sorted replay on startup)
• Anthropic Messages API proxy with streaming SSE
• Native Go agent harness with adaptive interval and 6 kernel tools
• Embedded web dashboard with agent status, cycle history, and decomposition panel
• Foveated decomposition pipeline (cog decompose) with 4-tier output, workbench TUI, embeddings, and bus events
• Library extraction: 7 packages in pkg/
• Content-addressed blob store
• Git-derived salience scoring
• Tool-call hallucination gate (activated by NormalizeMCPRequest path in #25)
• Digestion pipeline (Claude Code + OpenClaw adapters) wired into the process loop
• Memory consolidation
• OpenAI and Anthropic API compatibility
• cog bus send subcommand for write-side symmetry (direct JSONL or opt-in SSE)
• --bind flag with non-loopback CORS relaxation
• Windows cross-compile (make build-windows-amd64) and linux/arm64
• End-to-end test suite
• OpenTelemetry instrumentation
• Port consolidation on 6931

Next

• Direct import of the cogos-dev/constellation L1 trust-node protocol via the ConstellationBridge seam (the kernel already embeds sdk/constellation/ for the Constellation memory graph of cogdocs; the external L1 peer protocol is the piece not yet wired)
• Multi-agent process management (the agent controller API is forward-compatible; only the primary instance is registered today)
• Further agent state surface (beyond the v1 trigger/state/list)

Ecosystem

CogOS is one piece of a larger system. Each component is its own repo with independent releases:

Releases & Changelog

Per-release summaries: the Releases page (auto-generated from PR titles since the previous tag). See CHANGELOG.md for the policy and the historical entries (pre-v0.4.0).

Design documents

• System Specification: Multi-level spec from ontology to deployment
• Architectural Principles: Core engineering constraints
• Writing a Provider: How to add a new inference provider
• MCP Specification: MCP server contract
• Provider Specification: Provider interface contract
• Architecture Diagrams: Cell model, topology views
• Cognitive GitOps: Substrate-coordinated repo model
• E2E Test Plan: End-to-end test strategy

License

MIT. Copyright (c) 2025-2026 Chaz Dinkle.