Claude Integration

Overview

Cognova embeds Claude as a fully autonomous agent on your machine. Unlike typical chatbot integrations where the AI operates in a sandbox, Cognova's Claude has unrestricted access to your file system, shell, local services, and the Cognova API. It manages your tasks, organizes your vault, and remembers everything across sessions.

This integration is built on the Claude Agent SDK and extends Claude Code with a custom layer of skills, hooks, rules, and persistent memory. Together, these systems turn a stateless language model into a personal assistant with long-term continuity.

The Session Lifecycle

Every interaction with Claude -- whether through the terminal or the web dashboard chat -- follows the same lifecycle.

1. Session Start

When a Claude session opens, the SessionStart hook fires. It calls the Cognova memory API and injects relevant memories from previous sessions directly into Claude's context. If no memories exist (first session), it triggers an onboarding flow where Claude asks about your background, preferences, and goals.

2. Active Conversation

During the session, Claude has access to built-in skills:

Claude is instructed to use memory aggressively -- storing user preferences, decisions, solutions, and patterns as they come up in conversation.

3. Tool Usage Tracking

The PreToolUse and PostToolUse hooks fire around file edits and shell commands. These call the Cognova analytics API, tracking which tools Claude uses, how often, and whether any actions were blocked. This data feeds the analytics dashboard.

4. Memory Extraction

After Claude finishes a response, the Stop hook fires asynchronously. It reads the conversation transcript and sends it to the memory extraction API, which uses a separate Claude instance to identify decisions, facts, solutions, and patterns worth preserving.

5. Context Compaction

When Claude's context window fills up, the PreCompact hook fires before the conversation is summarized. This is a critical moment -- it extracts memories from the full conversation before compaction discards detail.

6. Session End

The SessionEnd hook logs the session close event for analytics. Session metadata (duration, message count, cost) is persisted to the database.

Architecture

Terminal / Web Chat
        |
        v
  Claude Agent SDK
        |
        +--- hooks/session-start.py  --> GET /api/memory/context
        +--- hooks/stop-extract.py   --> POST /api/memory/extract
        +--- hooks/pre-compact.py    --> POST /api/memory/extract
        +--- hooks/log-event.py      --> POST /api/hooks/events
        +--- hooks/session-end.py    --> POST /api/hooks/events
        |
  skills/ (invoked via slash commands)
        +--- task/task.py            --> /api/tasks/*
        +--- project/project.py     --> /api/projects/*
        +--- memory/memory.py       --> /api/memory/*
        +--- environment/environment.py --> /api/health, pm2
        +--- skill-creator/SKILL.md  (pure instruction)
        |
        v
  Cognova API (Nuxt server)
        |
        v
  PostgreSQL

All Python scripts communicate with the Cognova API using curl subprocesses, avoiding any pip dependency requirements. Authentication is handled automatically via the .api-token file generated during setup.

Two Ways to Talk to Claude

Terminal (Claude Code CLI)

Run claude from the terminal on your server. This is a direct Claude Code session with full hook and skill support. Ideal for development work, system administration, and complex multi-step tasks.

Web Dashboard Chat

The dashboard includes a chat interface that streams Claude's responses in real time through a WebSocket connection. The server bridges between the browser and the Claude Agent SDK, persisting messages and tracking costs per conversation.

Both paths trigger the same hooks, use the same skills, and write to the same memory store.

Configuration Files

Claude's behavior is defined by three files in the Claude/ directory (installed to ~/.claude/ on your machine):

Next Steps

• Skills -- the five built-in slash commands
• Hooks -- the event-driven automation layer
• Rules -- contextual instructions for document handling
• Memory System -- how Claude remembers across sessions
• Custom Skills -- build your own slash commands