cogos

command module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 20, 2026 License: MIT Imports: 102 Imported by: 0

README

CogOS

A cognitive daemon for AI agents. Written in Go. Runs locally. Gives Claude Code, Cursor, and other AI tools persistent memory, scored context, and workspace continuity.

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

What it does

  • Foveated context assembly -- A live hook (UserPromptSubmit) fires on every Claude Code prompt, scores all available documents by relevance, and injects a focused context window. No manual @-file selection; the system decides what matters.

  • Learned retrieval via TRM -- A 2.3M-parameter Mamba SSM (Tiny Recursive Model) trained to 0.878 mean NDCG@10 (0.900 peak) through 500+ tracked experiments. Scores documents by temporal salience, edit recency, and semantic relevance. Runs inference locally in ~6KB of state. See docs/EVALUATION.md for full methodology.

  • Persistent memory -- Hierarchical memory system 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.

  • 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.

  • Content-addressed storage -- CogBlock protocol for content-addressed, hash-chained records. Every routing decision, context assembly, and state transition is recorded in an append-only ledger (SHA-256, RFC 8785).

  • Library extraction -- Seven importable Go packages in pkg/ covering the core type system: content-addressed blocks, coordination primitives, BEP wire protocol, reconciliation framework, modality bus, field graph types, and URI parsing. All usable independently of the kernel.

  • Native agent harness -- A homeostatic agent loop that runs as a goroutine inside the kernel process. Calls Gemma E4B via Ollama's native /api/chat endpoint 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. Exposes 8 tools: 4 kernel-native (memory search/read/write, coherence check) and 4 Mod3 voice tools bridged through the kernel.

  • Anthropic Messages API proxy -- Transparent proxy at POST /v1/messages that forwards to the real Anthropic API with streaming SSE passthrough. Enables cog claude to route Claude Code through the kernel via ANTHROPIC_BASE_URL.

  • Foveated decomposition pipeline -- cog decompose processes any input through E4B into four tiers: Tier 0 (one-sentence, ~15 tokens), Tier 1 (paragraph, ~100 tokens), Tier 2 (full CogDoc with sections and embeddings), Tier 3 (raw, gated). Includes an interactive workbench TUI (--workbench), embedding co-generation via nomic-embed-text, content-addressed CogDoc storage, and bus event emission for observability. This is the DECOMPOSE stage of the CogOS Hypercycle.

Architecture

CogOS runs as a single Go binary daemon. The kernel has three layers:

┌──────────────────────────────────────────────────────────┐
│  Membrane          HTTP API · MCP Server · Provider Router│
├──────────────────────────────────────────────────────────┤
│  Workspace          Context Engine · Memory · Ledger      │
│                     Salience Scorer · Blob Store          │
├──────────────────────────────────────────────────────────┤
│  Nucleus            Process Loop · Identity · State FSM   │
│                     Agent Harness · CogBus                │
└──────────────────────────────────────────────────────────┘

Membrane -- The API surface. Serves OpenAI and Anthropic-compatible chat endpoints, an MCP Streamable HTTP server, the Anthropic Messages API proxy, and foveated context assembly. Routes inference requests to local or cloud providers.

Workspace -- 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. Memory persists across sessions.

Nucleus -- The process loop. Runs continuously through four states (Active, Receptive, Consolidating, Dormant). Manages identity, consolidation, workspace lifecycle, and the homeostatic agent harness.

How foveated context works

When you submit a prompt in Claude Code, the UserPromptSubmit hook fires and calls the CogOS daemon. The context engine:

  1. Scores all workspace documents using TRM + git-derived salience
  2. Ranks by a composite signal (edit recency, semantic match, structural importance)
  3. Assembles a context window organized into stability zones:
Zone Contents Behavior
0 -- Nucleus Identity, system config Always present, never evicted
1 -- Knowledge Workspace docs, indexed memory Shifts slowly, high cache hit rate
2 -- History Conversation turns Scored by relevance, evictable
3 -- Current The current message Always present
  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.

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.

Package What it provides
pkg/cogblock Content-addressed block format, CogBlockKind enum, provenance/trust types, EventEnvelope, ledger (RFC 8785 canonicalization, hash chain, verify)
pkg/coordination Claim/Handoff/Broadcast types, 13 coordination functions, AgentID
pkg/bep BEP wire protocol types, TLS/DeviceID, index/version vectors, events, Engine/SyncProvider interfaces
pkg/reconcile Reconcilable interface (7 methods), State/Plan/Action types, registry, Kahn's topological sort, meta-orchestrator
pkg/modality Module interface, Bus, wire protocol (D2), events, salience tracker, channels, ProcessSupervisor
pkg/cogfield Node/Edge/Graph types, Block, BlockAdapter interface, conditions, signals, sessions, documents
pkg/uri URI struct, Parse/Format, 35 namespaces, ExtractInlineRefs, error types

69 files, ~10,200 lines, 190 tests across all packages.

Agent harness

The native Go agent harness (agent_harness.go, agent_tools.go, agent_serve.go) runs a homeostatic assessment loop inside the kernel process:

  • Calls Gemma E4B 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
  • Observable via GET /v1/agent/status (cycle count, last assessment, urgency)

Six kernel-native tools are available to the agent:

Tool Description
memory_search Search CogDocs by query
memory_read Read a specific memory document
memory_write Write or update a memory document
coherence_check Run drift detection on the workspace
bus_emit Emit an event to the CogBus
workspace_status Get workspace health and metrics

The agent tab in the embedded dashboard shows cycle history and an urgency sparkline.

API

Endpoint Description
POST /v1/chat/completions OpenAI-compatible chat (streaming + non-streaming)
POST /v1/messages Anthropic Messages API proxy (streaming SSE passthrough)
POST /v1/context/foveated Foveated context assembly
GET /v1/context Current attentional field
GET /v1/agent/status Agent harness status (cycle count, urgency, last assessment)
GET /health Liveness probe (identity, state, trust)
GET /dashboard Embedded web dashboard
POST /mcp MCP Streamable HTTP endpoint (JSON-RPC 2.0, session management)
DELETE /mcp MCP session termination

All endpoints serve on port 6931 by default.

MCP tools

The MCP server exposes 8 tools over Streamable HTTP:

Tool Source
cogos_memory_search Kernel native
cogos_memory_read Kernel native
cogos_memory_write Kernel native
cogos_coherence_check Kernel native
mod3_speak Bridged to Mod3 TTS
mod3_stop Bridged to Mod3 TTS
mod3_voices Bridged to Mod3 TTS
mod3_status Bridged to Mod3 TTS

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.

Getting started

Requirements
  • Go 1.24+
  • macOS or Linux
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 .
Route Claude Code through the kernel
# Launch Claude Code with kernel-mediated API routing
cog claude
# This 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

Testing

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

The kernel has 65 source files and 42 test files in internal/engine/, plus 190 tests across the pkg/ library packages.

Project layout

cmd/cogos/              Entry point (thin — delegates to internal/engine)
internal/engine/        Kernel: 65 source files, 42 test files
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
agent_harness.go        Native agent loop (Ollama /api/chat)
agent_tools.go          Kernel-native tool implementations
agent_serve.go          Agent status HTTP endpoint
decompose.go            Foveated decomposition engine (4-tier pipeline)
decompose_store.go      Embedding generation and CogDoc storage
decompose_tui.go        Interactive workbench TUI (Bubbletea)
serve_messages.go       Anthropic Messages API proxy
serve_dashboard.go      Embedded web dashboard
mcp_http.go             MCP Streamable HTTP transport
mcp_mod3.go             Mod3 voice tool bridge for MCP

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 Mamba TRM (0.878 mean NDCG@10)
  • Hash-chained append-only ledger
  • Multi-provider routing (Ollama, Anthropic, Claude Code, Codex)
  • MCP Streamable HTTP server (8 tools, JSON-RPC 2.0, sessions)
  • 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/ (69 files, ~10.2K LOC, 190 tests)
  • Content-addressed blob store
  • Git-derived salience scoring
  • Tool-call hallucination gate
  • Digestion pipeline (Claude Code + OpenClaw adapters)
  • Memory consolidation
  • OpenAI and Anthropic API compatibility
  • Workspace scaffolding and lifecycle management
  • End-to-end test suite
  • OpenTelemetry instrumentation
  • Port consolidation on 6931
Next
  • Wire digestion tailers into process loop
  • Constellation library integration (multi-node sync)
  • Multi-agent process management
  • cog CLI

Ecosystem

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

Repo Purpose Status
cogos The daemon -- this repo Active
constellation Distributed identity and workspace sync (BEP-based) Active
mod3 Modality bus -- voice I/O, TTS, channel multiplexing Active
skills Agent skill library (Claude Code compatible) Active
charts Helm charts and Docker Compose for deployment Active

Design documents

License

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

Documentation

Overview

agent_bus_inlet.go — Dashboard chat inlet for the metabolic cycle.

Wires the Mod³ dashboard to the cogos kernel's external-event channel: 

Mod³ → POST /v1/bus/send bus_id=bus_dashboard_chat
     → appendBusEvent dispatches to in-process handlers
     → this file's handler → engine.Process.SubmitExternal

The inverse direction (kernel → Mod³) is handled by the `respond` tool (agent_tools_respond.go), which publishes to bus_dashboard_response; Mod³ subscribes via the existing /v1/events/stream SSE endpoint.

Wiring: call InstallDashboardInlet(busMgr, process) once at daemon start alongside InstallTraceEmitter. The process argument may be nil (main daemon does not currently own a *engine.Process); in that case the handler still ensures the bus exists and logs incoming messages so the wiring is observable even before the v3 process is instantiated in this binary.

agent_harness.go — Native Go agent harness for the homeostatic kernel loop.

Runs as a goroutine inside the kernel process. Calls a local model (Gemma E4B via Ollama) through the OpenAI chat completions wire protocol. The loop is: 

Observation → Assess (JSON mode) → Execute (tool loop) → Callback

No framework dependencies. Uses net/http directly against Ollama's OpenAI-compatible /v1/chat/completions endpoint.

agent_tools.go — Kernel-native tool implementations for the agent harness.

Each tool is a Go function with the ToolFunc signature that wraps existing kernel functionality. Tools are registered with the AgentHarness and dispatched when the model invokes them via tool_calls.

kernel_harness.go is the integration layer between the CogOS kernel (package main) and the inference harness (package harness).

It provides three things:

  1. kernelServicesAdapter — implements harness.KernelServices by wrapping existing kernel functions (dispatch, emitEvent, depositSignal, etc.)

  2. Type conversion functions — the kernel and harness have parallel type hierarchies (both define InferenceRequest, ContextState, etc.). These converters bridge them at the boundary.

  3. Shim functions (HarnessRunInference, HarnessRunInferenceStream) — called by serve.go and inference.go where the old RunInference/RunInferenceStream used to be called. They convert kernel→harness, delegate, then convert back.

Call flow: 

serve.go:handleChatCompletions
  → HarnessRunInference(kernelReq)          ← this file
    → toHarnessRequest(kernelReq)            ← type conversion
    → harness.Harness.RunInference(hReq)     ← harness package
    → fromHarnessResponse(hResp)             ← type conversion
  ← kernelResp

modality_hud.go — Formats modality bus state for agent context injection (zone 5).

modality_pipeline.go — Top-level orchestrator wiring all modality bus components together. Provides the single ingress/egress API surface.

Ingress: raw input -> bus.Perceive -> router.RoutePerceive -> CognitiveEvent Egress: intent -> channel lookup -> bus.Act -> router.RouteAct -> outputs

modality_router.go — EventRouter connects the ModalityBus to the kernel's event systems: ledger (persistence), listeners (streaming), salience.

trace_emit.go — Bus-publish helper for cycle-trace events (ADR-083).

This file is the bridge between the schema-only `trace` subpackage and the kernel's bus API (`busSessionManager.appendBusEvent`). Emission is best-effort and non-blocking: errors are logged, never propagated. Losing a trace event is always preferable to stalling the metabolic cycle.

Wiring:

  • At serve startup, call `InstallTraceEmitter(busManager, root)` once. That sets:
  • trace bus ensured on disk (`bus_cycle_trace`)
  • `engine.TraceEmitter` hook wired to `emitCycleEvent`
  • `engine.TraceIdentity` wired to the active identity name After that, engine/process.go and the agent harness can call `emitCycleEvent` (or the engine hook) without further setup.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cogos command
CogOS kernel — continuous process daemon for AI agents.
 CogOS kernel — continuous process daemon for AI agents.
envspec module
harness module
internal
engine
benchmark.go — foveated context benchmark runner
 benchmark.go — foveated context benchmark runner
linkfeed
Package linkfeed implements Discord link-feed ingestion + enrichment.
 Package linkfeed implements Discord link-feed ingestion + enrichment.
providers/component
Package component provides the Reconcilable provider for workspace components.
 Package component provides the Reconcilable provider for workspace components.
workspace
Package workspace resolves the active CogOS workspace root.
 Package workspace resolves the active CogOS workspace root.
pkg
cogblock module
cogfield module
coordination module
modality module
reconcile module
sdk module
Package trace defines the cycle-trace event schema emitted by the cogos kernel's homeostatic metabolic cycle onto the kernel bus (http://localhost:6931/v1/bus) for external consumers such as the Mod³ dashboard.
 Package trace defines the cycle-trace event schema emitted by the cogos kernel's homeostatic metabolic cycle onto the kernel bus (http://localhost:6931/v1/bus) for external consumers such as the Mod³ dashboard.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.