{"id":"7227c4fd-16cb-4d27-b034-6d9f39295d32","slug":"cognitive-cortex","kind":"mcp","name":"cognitive-cortex","summary":"Autonomous observation and analysis layer for AI agents — Obsidian vault indexing, scheduled reasoning cycles, and a real-time cognitive dashboard. Built on cognitive-memory.","owner":"wkarber","repoUrl":"https://github.com/wkarber/cognitive-cortex","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-28T21:13:01.000Z","addedAt":"2026-10-21T08:37:03.888Z","logoUrl":"https://avatars.githubusercontent.com/u/105825279?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","databases","search"],"tags":["agents","autonomous-agents","cognitive-science","hybrid-search","llm","obsidian","pgvector","postgresql"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T03:29:04.397Z","sample":false,"url":"https://conduits.dev/tools/cognitive-cortex","language":"Python","transports":["stdio"],"install":{"pypi":"cognitive-cortex"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Cognitive Cortex\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://www.postgresql.org/)\n[](https://modelcontextprotocol.io/)\n\nThe observation, analysis, and action layer for autonomous AI agents. Built on [**cognitive-memory**](https://github.com/wkarber/cognitive-memory).\n\ncognitive-memory is the remembering — attention-gated encoding, activation-weighted retrieval, and autonomous consolidation. cognitive-cortex is the observing, analyzing, and acting: it gives agents searchable access to an [Obsidian](https://obsidian.md/) vault, runs an autonomous executive daemon that reasons about what it finds, and surfaces the whole cognitive state through a real-time reflection dashboard.\n\nThe key insight is the feedback loop. The daemon orients from memory, surveys the vault, cross-references with an LLM, writes analytical artifacts back into the vault, and stores a summary back to memory. Every cycle makes the system's understanding slightly deeper — observation drives analysis, analysis feeds back into memory, memory informs the next observation.\n\n## Three-layer architecture\n\n```mermaid\ngraph TB\n subgraph \"Layer 1 — Vault MCP Server\"\n VS[vault_search] --> DB[(PostgreSQL
pgvector)]\n VR[vault_read] --> VAULT[Obsidian Vault]\n VL[vault_list] --> VAULT\n VW[vault_write] --> VAULT\n VST[vault_status] --> DB\n IDX[Background Indexer] --> VAULT\n IDX --> DB\n end\n\n subgraph \"Layer 2 — Executive Daemon\"\n P1[Orient] -->|cognitive state| P2[Survey]\n P2 -->|vault context| P3[Cross-Reference]\n P3 -->|LLM analysis| P4[Produce]\n P4 -->|artifacts| P5[Close Loop]\n end\n\n subgraph \"Layer 3 — Reflection Dashboard\"\n API[FastAPI] --> PANELS[Ecosystem · Concerns
Commitments · Self-Model
Memory Landscape · Heartbeats]\n PANELS --> UI[React + Tailwind SPA]\n end\n\n CM[(cognitive-memory
MCP Server)]\n\n P1 -.->|orient| CM\n P5 -.->|experience| CM\n P2 -->|hybrid search| VS\n P4 -->|write artifacts| VW\n API -.->|orient| CM\n API -->|vault stats| DB\n UI -->|auto-refresh| API\n```\n\nEach layer is independently deployable — run just the vault server for search, add the daemon for autonomous analysis, add the dashboard for monitoring.\n\n## Layer 1 — Vault MCP Server\n\nAn [MCP](https://modelcontextprotocol.io/) server that indexes an Obsidian vault into PostgreSQL with pgvector and exposes it through 5 tools. Any MCP-compatible agent or application connects and gets hybrid semantic + keyword search, section-level file reading, directory browsing, and zone-controlled writes.\n\n### The 5 vault tools\n\n| Tool | Purpose |\n|------|---------|\n| `vault_search` | Hybrid search combining vector cosine similarity and BM25 full-text via reciprocal rank fusion. Filters by scope, path, tags, and date range |\n| `vault_read` | Read a file with optional heading-based section extraction and token-limited truncation |\n| `vault_list` | Directory listing joined with database state — file sizes, modification times, index status, tags |\n| `vault_write` | Create, append, or prepend files within configured write zones. Triggers re-indexing |\n| `vault_status` | System health: file/chunk counts, scopes, write zones, database and embedding config |\n\n### Indexing pipeline\n\nThe background indexer watches the vault for changes and maintains a searchable index:\n\n1. **Discover** — Recursive walk of `.md` files, respecting exclude patterns\n2. **Detect** — Compare disk state against database (mtime, size, content hash)\n3. **Parse** — Extract YAML frontmatter, inline tags, and Obsidian syntax (wikilinks, embeds, callouts, dataview blocks)\n4. **Chunk** — Heading-aware splitting that preserves document structure, with configurable token sizes and overlap\n5. **Embed** — Batch OpenAI embeddings (text-embedding-3-large, 2000 dimensions by default)\n6. **Store** — Transactional upsert of file metadata and chunks with vectors\n\nSearch combines vector cosine similarity (HNSW index) with BM25 full-text scoring (GIN-indexed tsvectors), merged via reciprocal rank fusion. Named scopes provide preset filter bundles so agents can search `scope: \"projects\"` instead of constructing path filters.\n\n## Layer 2 — Executive Daemon\n\nAn autonomous agent that runs scheduled reasoning cycles — the heartbeat. Every few hours (configurable), it assembles cognitive state from memory, surveys the vault for relevant changes, runs cross-referential analysis through an LLM, writes analytical artifacts, and stores a summary back to cognitive-memory.\n\n### The 5-phase heartbeat cycle\n\n| Phase | What happens |\n|-------|-------------|\n| **Orient** | Calls cognitive-memory's `orient` tool — retrieves active concerns, pending commitments, self-model, and working context |\n| **Survey** | Queries the vault: file counts, recent changes, hybrid search for each active concern, approaching commitments with related documents |\n| **Cross-Reference** | Sends cognitive state + vault observations to an LLM. Analysis identifies alignment gaps, self-model drift, stale documentation, temporal patterns, and artifacts to produce |\n| **Produce** | Writes markdown artifacts to the vault — heartbeat syntheses (always), concern briefs, and pre-event briefs (as recommended by the analysis) |\n| **Close Loop** | Stores a compact summary back to cognitive-memory via `experience`, closing the feedback loop |\n\n### What it produces\n\n- **Heartbeat syntheses** — Timestamped snapshots of overall cognitive-vault alignment, with gap analysis, drift detection, and deadline tracking\n- **Concern briefs** — Living documents per active concern: current state, key vault documents, open items, recent activity\n- **Pre-event briefs** — Preparation documents for approaching commitments with context and supporting documents\n\nAll artifacts include structured frontmatter (cycle ID, timestamp, model, concerns addressed) and are written to configurable write zones in the vault — searchable by future cycles and by any connected agent.\n\n### Example: cross-reference analysis\n\nThe LLM phase returns structured JSON analyzing the intersection of cognitive state and vault observations:\n\n```json\n{\n \"overall_assessment\": \"Active concerns around API performance are well-documented in the vault, but the self-model overestimates frontend coverage — recent vault activity is heavily backend-focused.\",\n \"alignment\": [\n {\n \"concern\": \"API latency optimization\",\n \"status\": \"aligned\",\n \"evidence\": \"3 recent vault updates with benchmarks and migration notes\"\n },\n {\n \"concern\": \"Frontend testing coverage\",\n \"status\": \"misaligned\",\n \"evidence\": \"No vault documents address this despite it being a top-3 concern\"\n }\n ],\n \"gaps\": [\n {\n \"type\": \"undocumented_concern\",\n \"description\": \"Frontend testing has no supporting documentation in the vault\",\n \"severity\": \"high\",\n \"recommendation\": \"Create a concern brief to track current state and next steps\"\n }\n ],\n \"drift\": [\n {\n \"type\": \"self_model_divergence\",\n \"description\": \"Self-model lists 'Frontend integration' as a weak domain, but recent vault activity shows no effort to address it\",\n \"evidence\": \"0 vault files modified in frontend/ in the last 2 weeks\"\n }\n ],\n \"temporal\": {\n \"approaching_deadlines\": [\n {\n \"commitment\": \"Load testing report due\",\n \"deadline\": \"2026-04-03T00:00:00Z\",\n \"preparation_status\": \"in_progress\",\n \"urgency\": \"medium\"\n }\n ],\n \"stalled_concerns\": [\"Frontend testing coverage\"],\n \"velocity_notes\": \"Backend documentation velocity is strong; frontend is stalled\"\n },\n \"artifacts_to_produce\": [\n {\n \"type\": \"concern_brief\",\n \"target_concern_or_commitment\": \"Frontend testing coverage\",\n \"suggested_content_summary\": \"Current state of frontend test infrastructure, gap analysis, recommended next steps\"\n }\n ],\n \"compact_summary\": \"Backend work is well-aligned with concerns and well-documented. Frontend testing is the primary gap — high-priority concern with zero vault support. Load testing commitment is on track but approaching deadline.\"\n}\n```\n\n## Layer 3 — Reflection Dashboard\n\nA real-time monitoring dashboard that renders the cognitive ecosystem's state — what the system is thinking about, what it's committed to, how it models its own knowledge, and what the daemon has observed.\n\n### Dashboard panels\n\n| Panel | Data source | What it shows |\n|-------|------------|---------------|\n| **Ecosystem Status** | Vault DB + daemon state | Server connections, vault file/chunk counts, last heartbeat, daemon cycle count |\n| **Active Concerns** | cognitive-memory `orient` | Priority-ordered concerns with source and last-pinged timestamps |\n| **Commitments** | cognitive-memory `orient` | Pending commitments with deadlines and overdue flags |\n| **Self-Model** | cognitive-memory `orient` | Narrative self-assessment, strong/weak domains, behavioral patterns, knowledge gaps |\n| **Memory Landscape** | cognitive-memory `orient` | Memory counts by type (episodic, semantic, procedural, prospective) and lifecycle state, association and entity totals |\n| **Heartbeat History** | Vault heartbeat files | Recent daemon cycles with timestamps, models used, concerns addressed, overall assessments |\n\nThe dashboard queries cognitive-memory via a subprocess worker (isolating the MCP client's event loop from uvicorn) and caches orient responses to prevent overlapping calls. The React frontend auto-refreshes on a configurable interval.\n\n**API endpoints:**\n- `GET /api/dashboard` — Full ecosystem snapshot (all panels)\n- `GET /api/heartbeats?limit=10` — Recent heartbeat summaries\n\n## Quick start\n\n### Prerequisites\n\n- Python 3.10+\n- PostgreSQL 16+ with [pgvector](https://github.com/pgvector/pgvector)\n- OpenAI API key (vault embeddings)\n- A running [cognitive-memory](https://github.com/wkarber/cognitive-memory) server (for Layer 2 and 3)\n\n### Install\n\n```bash\ngit clone https://github.com/wkarber/cognitive-cortex.git\ncd cognitive-cortex\npip install -e \".[dev]\"\n```\n\n### Database setup\n\n```bash\ncreatedb cognitive_cortex\n```\n\nMigrations run automatically on server startup.\n\n### Configure\n\n```bash\ncp config/config.example.yaml config.yaml\n```\n\nEdit `config.yaml` — at minimum, set `vault_path` to your Obsidian vault. Secrets go in environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"your-key\" # Required: vault embeddings\nexport CORTEX_DB_PASSWORD=\"your-password\" # If your PostgreSQL requires auth\nexport DAEMON_LLM_API_KEY=\"your-key\" # Layer 2: OpenRouter or OpenAI-compatible\nexport DAEMON_MEMORY_URL=\"http://...\" # Layer 2: cognitive-memory server URL\nexport DASHBOARD_MEMORY_URL=\"http://...\" # Layer 3: cognitive-memory server URL\n```\n\n### Run\n\n**Layer 1 — Vault server:**\n\n```bash\ncognitive-cortex\n```\n\nOr add to any MCP client:\n\n```json\n{\n \"mcpServers\": {\n \"cognitive-cortex\": {\n \"command\": \"cognitive-cortex\",\n \"env\": {\n \"OPENAI_API_KEY\": \"your-key\"\n }\n }\n }\n}\n```\n\n**Layer 2 — Executive daemon:**\n\n```bash\ncortex-daemon start # Scheduled loop (respects active_hours)\ncortex-daemon run # Single heartbeat cycle\ncortex-daemon run --dry-run # Analyze without writing artifacts\ncortex-daemon status # Print daemon state\n```\n\n**Layer 3 — Reflection dashboard:**\n\n```bash\ncortex-dashboard # http://127.0.0.1:8080\ncortex-dashboard --port 9090 # Custom port\n```\n\n## Configuration\n\nA single `config.yaml` configures all three layers. Configuration loads as Pydantic defaults → YAML overrides → environment variable overrides for secrets.\n\n```yaml\n# Layer 1\nvault_path: ~/my-vault\nscopes:\n projects: { path: \"projects/\", description: \"Project docs\" }\nwrite_zones:\n syntheses: { path: \"ai-syntheses/\", description: \"Daemon output\" }\n\n# Layer 2\ndaemon:\n enabled: true\n interval_hours: 4\n active_hours: [7, 23]\n llm:\n model: \"anthropic/claude-sonnet-4-20250514\"\n artifacts:\n write_zone: \"syntheses\"\n\n# Layer 3\ndashboard:\n enabled: true\n port: 8080\n refresh_interval_seconds: 30\n```\n\nThe LLM endpoint is **provider-agnostic** — any OpenAI-compatible API works (OpenRouter, Ollama, direct OpenAI, etc.). See [`config/config.example.yaml`](config/config.example.yaml) for the full reference.\n\n## Project status\n\nAll three layers are complete with 320 tests:\n\n- **Layer 1 — Vault MCP Server:** Markdown parsing (frontmatter, Obsidian syntax, heading-aware chunking), hybrid search (vector + BM25 + RRF), background indexing with change detection, zone-controlled writes\n- **Layer 2 — Executive Daemon:** 5-phase heartbeat cycle, multi-transport MCP client (stdio, streamable-http, SSE, httpx fallback), artifact generation with structured frontmatter, state persistence, active-hours scheduling\n- **Layer 3 — Reflection Dashboard:** FastAPI backend with subprocess-isolated orient calls, React + Tailwind + Recharts frontend, auto-refresh, heartbeat history parsing\n\nTests run without network access — all external dependencies (OpenAI, cognitive-memory, LLM endpoints) are mocked. Database-dependent tests skip gracefully when PostgreSQL is unavailable.\n\n```bash\npython3 -m pytest tests/ -v\n```\n\n### Known limitations\n\n- **No Docker** — deployment is manual (`pip install` + process management)\n- **Orient cold start** — the dashboard and daemon return empty panels if cognitive-memory has no data yet\n\n## Future directions\n\n- **Dashboard interactivity** — Write capabilities: managing concerns and commitments, testing orient responses, tuning daemon parameters directly through the UI. Turning the dashboard from a monitor into a control surface.\n- **Multi-agent orchestration and configurable identity** — Swappable identity profiles stored in the vault, so different agents can orient differently from the same memory substrate. The executive daemon could manage multiple sub-agents with distinct roles and concern sets, each drawing different working contexts from shared memory.\n- **Vault enrichment automation** — Automated backlinking, semantic similarity linking, property management, and table of contents generation. The system actively improving the vault's structure and interconnection.\n- **Metacognitive observer layer** — A cross-tier monitoring process that watches cognitive-memory's processing log to detect higher-order patterns: emerging concerns, Hebbian lock-in, self-model miscalibration. Closes the monitoring-control loop by adjusting memory parameters based on observations.\n- **Production deployment** — Docker, authentication, process management, CI/CD, notifications for drift alerts and overdue commitments.\n\n## Part of the Cognitive Ecosystem\n\ncognitive-cortex is the observation, analysis, and action layer. [**cognitive-memory**](https://github.com/wkarber/cognitive-memory) is the companion project — a shared cognitive memory substrate for AI agents with attention-gated encoding, Hebbian association graphs, LLM-driven consolidation, and activation-weighted retrieval. cognitive-memory handles remembering; cognitive-cortex handles everything that builds on top of it.\n\nThe daemon calls `orient` and `experience` to close a feedback loop between the two systems: memory informs observation, observation drives analysis, analysis feeds back into memory. Any MCP-compatible client can connect to either or both servers — context flows freely across sessions, agents, and tools.\n\n## License\n\n[MIT](LICENSE)\n"}