{"id":49062989,"url":"https://github.com/cogos-dev/cogos","last_synced_at":"2026-04-20T03:09:25.052Z","repository":{"id":349609742,"uuid":"1203058844","full_name":"cogos-dev/cogos","owner":"cogos-dev","description":"Cognitive daemon for AI agents — foveated context assembly, learned retrieval (TRM), persistent memory, multi-provider routing. Written in Go.","archived":false,"fork":false,"pushed_at":"2026-04-13T22:19:43.000Z","size":1945,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T00:26:36.591Z","etag":null,"topics":["ai-agents","claude-code","context-assembly","golang","local-first","mcp"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cogos-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T17:20:02.000Z","updated_at":"2026-04-13T22:19:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cogos-dev/cogos","commit_stats":null,"previous_names":["cogos-dev/cogos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cogos-dev/cogos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogos-dev%2Fcogos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogos-dev%2Fcogos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogos-dev%2Fcogos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogos-dev%2Fcogos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cogos-dev","download_url":"https://codeload.github.com/cogos-dev/cogos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogos-dev%2Fcogos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32031079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","context-assembly","golang","local-first","mcp"],"created_at":"2026-04-20T03:09:24.251Z","updated_at":"2026-04-20T03:09:25.046Z","avatar_url":"https://github.com/cogos-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CogOS\n\nA 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.\n\n```sh\nmake build \u0026\u0026 ./cogos serve --workspace ~/my-project\n# http://localhost:6931/health\n```\n\n---\n\n## What it does\n\n- **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.\n\n- **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](docs/EVALUATION.md) for full methodology.\n\n- **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.\n\n- **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.\n\n- **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).\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **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`.\n\n- **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.\n---\n\n## Architecture\n\nCogOS runs as a single Go binary daemon. The kernel has three layers:\n\n```\n┌──────────────────────────────────────────────────────────┐\n│  Membrane          HTTP API · MCP Server · Provider Router│\n├──────────────────────────────────────────────────────────┤\n│  Workspace          Context Engine · Memory · Ledger      │\n│                     Salience Scorer · Blob Store          │\n├──────────────────────────────────────────────────────────┤\n│  Nucleus            Process Loop · Identity · State FSM   │\n│                     Agent Harness · CogBus                │\n└──────────────────────────────────────────────────────────┘\n```\n\n**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.\n\n**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.\n\n**Nucleus** -- The process loop. Runs continuously through four states (Active, Receptive, Consolidating, Dormant). Manages identity, consolidation, workspace lifecycle, and the homeostatic agent harness.\n\n### How foveated context works\n\nWhen you submit a prompt in Claude Code, the `UserPromptSubmit` hook fires and calls the CogOS daemon. The context engine:\n\n1. Scores all workspace documents using TRM + git-derived salience\n2. Ranks by a composite signal (edit recency, semantic match, structural importance)\n3. Assembles a context window organized into stability zones:\n\n| Zone | Contents | Behavior |\n|------|----------|----------|\n| 0 -- Nucleus | Identity, system config | Always present, never evicted |\n| 1 -- Knowledge | Workspace docs, indexed memory | Shifts slowly, high cache hit rate |\n| 2 -- History | Conversation turns | Scored by relevance, evictable |\n| 3 -- Current | The current message | Always present |\n\n4. Injects the assembled context into the prompt before it reaches the model\n\nThe model sees a pre-focused window instead of everything-or-nothing.\n\n---\n\n## Library packages (pkg/)\n\nSeven 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`.\n\n| Package | What it provides |\n|---------|-----------------|\n| `pkg/cogblock` | Content-addressed block format, CogBlockKind enum, provenance/trust types, EventEnvelope, ledger (RFC 8785 canonicalization, hash chain, verify) |\n| `pkg/coordination` | Claim/Handoff/Broadcast types, 13 coordination functions, AgentID |\n| `pkg/bep` | BEP wire protocol types, TLS/DeviceID, index/version vectors, events, Engine/SyncProvider interfaces |\n| `pkg/reconcile` | Reconcilable interface (7 methods), State/Plan/Action types, registry, Kahn's topological sort, meta-orchestrator |\n| `pkg/modality` | Module interface, Bus, wire protocol (D2), events, salience tracker, channels, ProcessSupervisor |\n| `pkg/cogfield` | Node/Edge/Graph types, Block, BlockAdapter interface, conditions, signals, sessions, documents |\n| `pkg/uri` | URI struct, Parse/Format, 35 namespaces, ExtractInlineRefs, error types |\n\n69 files, ~10,200 lines, 190 tests across all packages.\n\n---\n\n## Agent harness\n\nThe native Go agent harness (`agent_harness.go`, `agent_tools.go`, `agent_serve.go`) runs a homeostatic assessment loop inside the kernel process:\n\n- Calls Gemma E4B via Ollama's native `/api/chat` (with `think: false`)\n- Adaptive interval: 5m idle, scales to 30m when assessment urgency is low\n- Panic recovery -- a crash in the agent goroutine doesn't take down the kernel\n- Observable via `GET /v1/agent/status` (cycle count, last assessment, urgency)\n\nSix kernel-native tools are available to the agent:\n\n| Tool | Description |\n|------|-------------|\n| `memory_search` | Search CogDocs by query |\n| `memory_read` | Read a specific memory document |\n| `memory_write` | Write or update a memory document |\n| `coherence_check` | Run drift detection on the workspace |\n| `bus_emit` | Emit an event to the CogBus |\n| `workspace_status` | Get workspace health and metrics |\n\nThe agent tab in the embedded dashboard shows cycle history and an urgency sparkline.\n\n---\n\n## API\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /v1/chat/completions` | OpenAI-compatible chat (streaming + non-streaming) |\n| `POST /v1/messages` | Anthropic Messages API proxy (streaming SSE passthrough) |\n| `POST /v1/context/foveated` | Foveated context assembly |\n| `GET /v1/context` | Current attentional field |\n| `GET /v1/agent/status` | Agent harness status (cycle count, urgency, last assessment) |\n| `GET /health` | Liveness probe (identity, state, trust) |\n| `GET /dashboard` | Embedded web dashboard |\n| `POST /mcp` | MCP Streamable HTTP endpoint (JSON-RPC 2.0, session management) |\n| `DELETE /mcp` | MCP session termination |\n\nAll endpoints serve on port **6931** by default.\n\n### MCP tools\n\nThe MCP server exposes 8 tools over Streamable HTTP:\n\n| Tool | Source |\n|------|--------|\n| `cogos_memory_search` | Kernel native |\n| `cogos_memory_read` | Kernel native |\n| `cogos_memory_write` | Kernel native |\n| `cogos_coherence_check` | Kernel native |\n| `mod3_speak` | Bridged to Mod3 TTS |\n| `mod3_stop` | Bridged to Mod3 TTS |\n| `mod3_voices` | Bridged to Mod3 TTS |\n| `mod3_status` | Bridged to Mod3 TTS |\n\nSessions are created on `initialize` and expire after 30 minutes of inactivity.\n\n### Providers\n\nShips with adapters for Anthropic, Ollama, Claude Code, and Codex. New providers implement [six methods](docs/writing-a-provider.md).\n\n---\n\n## Getting started\n\n### Requirements\n\n- Go 1.24+\n- macOS or Linux\n\n### Build and run\n\n```sh\ngit clone https://github.com/cogos-dev/cogos.git\ncd cogos\nmake build\n\n# Initialize a workspace\n./cogos init --workspace ~/my-project\n\n# Start the daemon\n./cogos serve --workspace ~/my-project\n\n# Verify it's running\ncurl -s http://localhost:6931/health | jq .\n```\n\n### Route Claude Code through the kernel\n\n```sh\n# Launch Claude Code with kernel-mediated API routing\ncog claude\n# This sets ANTHROPIC_BASE_URL to http://localhost:6931 and starts Claude Code\n```\n\n### Developer setup\n\n```sh\n./scripts/setup-dev.sh    # Build, install to ~/.cogos/bin, configure PATH\n```\n\n### Docker\n\n```sh\nmake image        # Build production image\nmake run          # Run with workspace volume mount\nmake e2e          # Build + run full cold-start test in a container\n```\n\n---\n\n## Testing\n\n```sh\nmake test         # Unit tests (with -race)\nmake e2e-local    # Full cold-start lifecycle test\nmake e2e          # Containerized e2e (Docker)\n```\n\nThe kernel has 65 source files and 42 test files in `internal/engine/`, plus 190 tests across the `pkg/` library packages.\n\n---\n\n## Project layout\n\n```\ncmd/cogos/              Entry point (thin — delegates to internal/engine)\ninternal/engine/        Kernel: 65 source files, 42 test files\npkg/                    Importable library packages (go.work multi-module)\n  cogblock/             Content-addressed blocks and ledger\n  coordination/         Agent coordination primitives\n  bep/                  BEP wire protocol types\n  reconcile/            Reconciliation framework\n  modality/             Modality bus and channel types\n  cogfield/             Field graph types\n  uri/                  URI parsing and namespaces\nsdk/                    Go SDK for CogOS clients\ndocs/                   Specs, architecture docs, provider guide\nscripts/                Setup, CLI wrapper, e2e tests, experiment harnesses\nagent_harness.go        Native agent loop (Ollama /api/chat)\nagent_tools.go          Kernel-native tool implementations\nagent_serve.go          Agent status HTTP endpoint\ndecompose.go            Foveated decomposition engine (4-tier pipeline)\ndecompose_store.go      Embedding generation and CogDoc storage\ndecompose_tui.go        Interactive workbench TUI (Bubbletea)\nserve_messages.go       Anthropic Messages API proxy\nserve_dashboard.go      Embedded web dashboard\nmcp_http.go             MCP Streamable HTTP transport\nmcp_mod3.go             Mod3 voice tool bridge for MCP\n```\n\n---\n\n## Status\n\n**v3 kernel** -- Ground-up rewrite after a year of daily use across Claude Code, Cursor, and custom agent harnesses.\n\n### Working\n\n- Continuous process daemon with four-state FSM\n- Foveated context assembly with Mamba TRM (0.878 mean NDCG@10)\n- Hash-chained append-only ledger\n- Multi-provider routing (Ollama, Anthropic, Claude Code, Codex)\n- MCP Streamable HTTP server (8 tools, JSON-RPC 2.0, sessions)\n- Anthropic Messages API proxy with streaming SSE\n- Native Go agent harness with adaptive interval and 6 kernel tools\n- Embedded web dashboard with agent status, cycle history, and decomposition panel\n- Foveated decomposition pipeline (`cog decompose`) with 4-tier output, workbench TUI, embeddings, and bus events\n- Library extraction: 7 packages in pkg/ (69 files, ~10.2K LOC, 190 tests)\n- Content-addressed blob store\n- Git-derived salience scoring\n- Tool-call hallucination gate\n- Digestion pipeline (Claude Code + OpenClaw adapters)\n- Memory consolidation\n- OpenAI and Anthropic API compatibility\n- Workspace scaffolding and lifecycle management\n- End-to-end test suite\n- OpenTelemetry instrumentation\n- Port consolidation on 6931\n\n### Next\n\n- Wire digestion tailers into process loop\n- Constellation library integration (multi-node sync)\n- Multi-agent process management\n- `cog` CLI\n\n---\n\n## Ecosystem\n\nCogOS is one piece of a larger system. Each component is its own repo with independent releases:\n\n| Repo | Purpose | Status |\n|------|---------|--------|\n| **[cogos](https://github.com/cogos-dev/cogos)** | The daemon -- this repo | Active |\n| [constellation](https://github.com/cogos-dev/constellation) | Distributed identity and workspace sync (BEP-based) | Active |\n| [mod3](https://github.com/cogos-dev/mod3) | Modality bus -- voice I/O, TTS, channel multiplexing | Active |\n| [skills](https://github.com/cogos-dev/skills) | Agent skill library (Claude Code compatible) | Active |\n| [charts](https://github.com/cogos-dev/charts) | Helm charts and Docker Compose for deployment | Active |\n\n---\n\n## Design documents\n\n- [System Specification](docs/SYSTEM-SPEC.md) -- Multi-level spec from ontology to deployment\n- [Architectural Principles](docs/architecture/principles.md) -- Core engineering constraints\n- [Writing a Provider](docs/writing-a-provider.md) -- How to add a new inference provider\n- [MCP Specification](docs/MCP-SPEC.md) -- MCP server contract\n- [Provider Specification](docs/PROVIDER-SPEC.md) -- Provider interface contract\n- [Architecture Diagrams](docs/architecture-diagram-source.md) -- Cell model, topology views\n- [Cognitive GitOps](docs/architecture/cognitive-gitops.md) -- Substrate-coordinated repo model\n- [E2E Test Plan](docs/E2E-TEST-PLAN.md) -- End-to-end test strategy\n\n---\n\n## License\n\n[MIT](LICENSE) -- Copyright (c) 2025-2026 Chaz Dinkle\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogos-dev%2Fcogos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcogos-dev%2Fcogos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogos-dev%2Fcogos/lists"}