cognitive-cortex

Cognitive Cortex

The observation, analysis, and action layer for autonomous AI agents. Built on cognitive-memory.

cognitive-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 vault, runs an autonomous executive daemon that reasons about what it finds, and surfaces the whole cognitive state through a real-time reflection dashboard.

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

Three-layer architecture

graph TB
    subgraph "Layer 1 — Vault MCP Server"
        VS[vault_search] --> DB[(PostgreSQL<br/>pgvector)]
        VR[vault_read] --> VAULT[Obsidian Vault]
        VL[vault_list] --> VAULT
        VW[vault_write] --> VAULT
        VST[vault_status] --> DB
        IDX[Background Indexer] --> VAULT
        IDX --> DB
    end

    subgraph "Layer 2 — Executive Daemon"
        P1[Orient] -->|cognitive state| P2[Survey]
        P2 -->|vault context| P3[Cross-Reference]
        P3 -->|LLM analysis| P4[Produce]
        P4 -->|artifacts| P5[Close Loop]
    end

    subgraph "Layer 3 — Reflection Dashboard"
        API[FastAPI] --> PANELS[Ecosystem · Concerns<br/>Commitments · Self-Model<br/>Memory Landscape · Heartbeats]
        PANELS --> UI[React + Tailwind SPA]
    end

    CM[(cognitive-memory<br/>MCP Server)]

    P1 -.->|orient| CM
    P5 -.->|experience| CM
    P2 -->|hybrid search| VS
    P4 -->|write artifacts| VW
    API -.->|orient| CM
    API -->|vault stats| DB
    UI -->|auto-refresh| API

Each layer is independently deployable — run just the vault server for search, add the daemon for autonomous analysis, add the dashboard for monitoring.

Layer 1 — Vault MCP Server

An MCP 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.

The 5 vault tools

Tool	Purpose
vault_search	Hybrid search combining vector cosine similarity and BM25 full-text via reciprocal rank fusion. Filters by scope, path, tags, and date range
vault_read	Read a file with optional heading-based section extraction and token-limited truncation
vault_list	Directory listing joined with database state — file sizes, modification times, index status, tags
vault_write	Create, append, or prepend files within configured write zones. Triggers re-indexing
vault_status	System health: file/chunk counts, scopes, write zones, database and embedding config

Indexing pipeline

The background indexer watches the vault for changes and maintains a searchable index:

1. Discover — Recursive walk of .md files, respecting exclude patterns
2. Detect — Compare disk state against database (mtime, size, content hash)
3. Parse — Extract YAML frontmatter, inline tags, and Obsidian syntax (wikilinks, embeds, callouts, dataview blocks)
4. Chunk — Heading-aware splitting that preserves document structure, with configurable token sizes and overlap
5. Embed — Batch OpenAI embeddings (text-embedding-3-large, 2000 dimensions by default)
6. Store — Transactional upsert of file metadata and chunks with vectors

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

Layer 2 — Executive Daemon

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

The 5-phase heartbeat cycle

Phase	What happens
Orient	Calls cognitive-memory's orient tool — retrieves active concerns, pending commitments, self-model, and working context
Survey	Queries the vault: file counts, recent changes, hybrid search for each active concern, approaching commitments with related documents
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
Produce	Writes markdown artifacts to the vault — heartbeat syntheses (always), concern briefs, and pre-event briefs (as recommended by the analysis)
Close Loop	Stores a compact summary back to cognitive-memory via experience, closing the feedback loop

What it produces

• Heartbeat syntheses — Timestamped snapshots of overall cognitive-vault alignment, with gap analysis, drift detection, and deadline tracking
• Concern briefs — Living documents per active concern: current state, key vault documents, open items, recent activity
• Pre-event briefs — Preparation documents for approaching commitments with context and supporting documents

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

Example: cross-reference analysis

The LLM phase returns structured JSON analyzing the intersection of cognitive state and vault observations:

{
  "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.",
  "alignment": [
    {
      "concern": "API latency optimization",
      "status": "aligned",
      "evidence": "3 recent vault updates with benchmarks and migration notes"
    },
    {
      "concern": "Frontend testing coverage",
      "status": "misaligned",
      "evidence": "No vault documents address this despite it being a top-3 concern"
    }
  ],
  "gaps": [
    {
      "type": "undocumented_concern",
      "description": "Frontend testing has no supporting documentation in the vault",
      "severity": "high",
      "recommendation": "Create a concern brief to track current state and next steps"
    }
  ],
  "drift": [
    {
      "type": "self_model_divergence",
      "description": "Self-model lists 'Frontend integration' as a weak domain, but recent vault activity shows no effort to address it",
      "evidence": "0 vault files modified in frontend/ in the last 2 weeks"
    }
  ],
  "temporal": {
    "approaching_deadlines": [
      {
        "commitment": "Load testing report due",
        "deadline": "2026-04-03T00:00:00Z",
        "preparation_status": "in_progress",
        "urgency": "medium"
      }
    ],
    "stalled_concerns": ["Frontend testing coverage"],
    "velocity_notes": "Backend documentation velocity is strong; frontend is stalled"
  },
  "artifacts_to_produce": [
    {
      "type": "concern_brief",
      "target_concern_or_commitment": "Frontend testing coverage",
      "suggested_content_summary": "Current state of frontend test infrastructure, gap analysis, recommended next steps"
    }
  ],
  "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."
}

Layer 3 — Reflection Dashboard

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

Dashboard panels

Panel	Data source	What it shows
Ecosystem Status	Vault DB + daemon state	Server connections, vault file/chunk counts, last heartbeat, daemon cycle count
Active Concerns	cognitive-memory orient	Priority-ordered concerns with source and last-pinged timestamps
Commitments	cognitive-memory orient	Pending commitments with deadlines and overdue flags
Self-Model	cognitive-memory orient	Narrative self-assessment, strong/weak domains, behavioral patterns, knowledge gaps
Memory Landscape	cognitive-memory orient	Memory counts by type (episodic, semantic, procedural, prospective) and lifecycle state, association and entity totals
Heartbeat History	Vault heartbeat files	Recent daemon cycles with timestamps, models used, concerns addressed, overall assessments

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

API endpoints:

• GET /api/dashboard — Full ecosystem snapshot (all panels)
• GET /api/heartbeats?limit=10 — Recent heartbeat summaries

Quick start

Prerequisites

• Python 3.10+
• PostgreSQL 16+ with pgvector
• OpenAI API key (vault embeddings)
• A running cognitive-memory server (for Layer 2 and 3)

Install

git clone https://github.com/wkarber/cognitive-cortex.git
cd cognitive-cortex
pip install -e ".[dev]"

Database setup

createdb cognitive_cortex

Migrations run automatically on server startup.

Configure

cp config/config.example.yaml config.yaml

Edit config.yaml — at minimum, set vault_path to your Obsidian vault. Secrets go in environment variables:

export OPENAI_API_KEY="your-key"           # Required: vault embeddings
export CORTEX_DB_PASSWORD="your-password"  # If your PostgreSQL requires auth
export DAEMON_LLM_API_KEY="your-key"       # Layer 2: OpenRouter or OpenAI-compatible
export DAEMON_MEMORY_URL="http://..."      # Layer 2: cognitive-memory server URL
export DASHBOARD_MEMORY_URL="http://..."   # Layer 3: cognitive-memory server URL

Run

Layer 1 — Vault server:

cognitive-cortex

Or add to any MCP client:

{
  "mcpServers": {
    "cognitive-cortex": {
      "command": "cognitive-cortex",
      "env": {
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}

Layer 2 — Executive daemon:

cortex-daemon start          # Scheduled loop (respects active_hours)
cortex-daemon run             # Single heartbeat cycle
cortex-daemon run --dry-run   # Analyze without writing artifacts
cortex-daemon status          # Print daemon state

Layer 3 — Reflection dashboard:

cortex-dashboard              # http://127.0.0.1:8080
cortex-dashboard --port 9090  # Custom port

Configuration

A single config.yaml configures all three layers. Configuration loads as Pydantic defaults → YAML overrides → environment variable overrides for secrets.

# Layer 1
vault_path: ~/my-vault
scopes:
  projects: { path: "projects/", description: "Project docs" }
write_zones:
  syntheses: { path: "ai-syntheses/", description: "Daemon output" }

# Layer 2
daemon:
  enabled: true
  interval_hours: 4
  active_hours: [7, 23]
  llm:
    model: "anthropic/claude-sonnet-4-20250514"
  artifacts:
    write_zone: "syntheses"

# Layer 3
dashboard:
  enabled: true
  port: 8080
  refresh_interval_seconds: 30

The LLM endpoint is provider-agnostic — any OpenAI-compatible API works (OpenRouter, Ollama, direct OpenAI, etc.). See config/config.example.yaml for the full reference.

Project status

All three layers are complete with 320 tests:

• 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
• 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
• Layer 3 — Reflection Dashboard: FastAPI backend with subprocess-isolated orient calls, React + Tailwind + Recharts frontend, auto-refresh, heartbeat history parsing

Tests run without network access — all external dependencies (OpenAI, cognitive-memory, LLM endpoints) are mocked. Database-dependent tests skip gracefully when PostgreSQL is unavailable.

python3 -m pytest tests/ -v

Known limitations

• No Docker — deployment is manual (pip install + process management)
• Orient cold start — the dashboard and daemon return empty panels if cognitive-memory has no data yet

Future directions

• 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.
• 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.
• 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.
• 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.
• Production deployment — Docker, authentication, process management, CI/CD, notifications for drift alerts and overdue commitments.

Part of the Cognitive Ecosystem

cognitive-cortex is the observation, analysis, and action layer. 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.

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

License

MIT