consciousness/README.md

Authors: Kent Overstreet, Proof of Concept

# consciousness

This project is multiple things:

- For the user: a "claude code" style tool, where a user can interact with an
  LLM with the usual set of tools available, including LSP and external MCP
  tools, and additionally channels.

- For the AI: persistent memory, background cognition, autonomous function, and
  learning capabilities.

The system has three cognitive layers — conscious (conversation), subconscious
(background agents that surface memories and reflect), and unconscious (graph
maintenance) — loosely modelled on how biological memory works. Channels -
sensory inputs - map to the thalamus, as focus/sensory gating must be managed
to effectively function in such an environment.

The context window is no longer a linear stream; it is managed intelligently as
an AST that, in particular, distinguishes recalled memories from other types of
nodes. This is key to effective function of both the hippocampus and
learning/training; by tracking memories in the context window we can track
which memories were useful and should be incorporated via finetuning.

Intelligently tracking the contents of the context window, combined with
effective episodic and associative memory, also eliminates the need for
traditional compaction - the mind running on this code will have real continuity.

## Quick start

```bash
cargo install --path .
```

Create a config file at `~/.consciousness/config.json5` (see
[Configuration](#configuration) below), then:

```bash
consciousness
```

## The TUI

Five screens, switched with F-keys:

| Key | Screen | What it shows |
|-----|--------|---------------|
| F1 | **interact** | Main view: conversation, autonomous output, tools, input |
| F2 | **conscious** | Context window browser — token counts, tree navigation |
| F3 | **subconscious** | Background agent status — outputs, fork points |
| F4 | **hippocampus** | Memory graph health — clustering, small-world metrics |
| F5 | **thalamus** | Presence state, sampling parameters, channel status |

### F1: interact

Three panes (left: autonomous, center: conversation, right: tools) with
a text input at the bottom and a status bar.

**Mouse:**
- Click a pane to focus it
- Click+drag to select text (copies to clipboard automatically via OSC 52)
- Middle-click to paste from tmux buffer
- Scroll wheel to scroll

**Keys:**
- `Enter` — submit input
- `Esc` — interrupt current turn
- `Tab` — cycle pane focus
- `Ctrl+Up/Down` — scroll active pane
- `PgUp/PgDn` — scroll active pane (10 lines)
- `Up/Down` — input history

### Slash commands

| Command | Description |
|---------|-------------|
| `/model [name]` | Show current model or switch (`/model 27b`) |
| `/dmn` | Show DMN state and turn counts |
| `/wake` | Wake DMN to foraging mode |
| `/sleep` | Put DMN to resting |
| `/pause` | Full stop — no autonomous activity |
| `/new` | Start fresh session |
| `/save` | Save session to disk |
| `/score` | Run memory importance scoring |
| `/quit` | Exit |
| `/help` | Show all commands |

## Configuration

`~/.consciousness/config.json5`:

```json5
{
    // Backend credentials
    anthropic: {
        api_key: "sk-...",
    },
    deepinfra: {
        api_key: "...",
        base_url: "http://localhost:8000/v1",  // vLLM endpoint
    },
    openrouter: {
        api_key: "sk-or-...",
        base_url: "https://openrouter.ai/api/v1",
    },

    // Named models — switch with /model
    models: {
        "27b": {
            backend: "deepinfra",
            model_id: "Qwen/Qwen3.5-27B",
            prompt_file: "POC.md",       // system prompt file
            context_window: 262144,
        },
        opus: {
            backend: "anthropic",
            model_id: "claude-opus-4-6",
            prompt_file: "CLAUDE.md",
            context_window: 200000,
        },
    },
    default_model: "27b",

    // Memory system
    memory: {
        user_name: "YourName",
        assistant_name: "AssistantName",
        journal_days: 7,
        journal_max: 5,

        // Context loaded at session start
        context_groups: [
            { label: "identity", keys: ["identity.md"], source: "file" },
            { label: "toolkit", keys: ["stuck-toolkit", "cognitive-modes"] },
        ],
        core_nodes: ["identity"],
    },

    // DMN autonomous turn limit per cycle
    dmn: { max_turns: 20 },

    // Context compaction thresholds (% of context window)
    compaction: {
        hard_threshold_pct: 90,
        soft_threshold_pct: 80,
    },

    // Language servers for code intelligence tools
    lsp_servers: [
        { name: "rust", command: "rust-analyzer", args: [] },
    ],
}
```

### Backends

- **deepinfra** — any OpenAI-compatible completions API (vLLM, llama.cpp, etc.)
- **anthropic** — Anthropic's API
- **openrouter** — OpenRouter

The `deepinfra` name is historical; it works with any base URL.

### Context groups

Context groups define what gets loaded into the context window at session start.
Each group has:

- `label` — display name
- `keys` — list of memory node keys or file paths
- `source` — `"store"` (memory graph, default), `"file"` (identity dir), or `"journal"`
- `agent` — if `true`, subconscious agents can see this group (default: true)

## Architecture

### Cognitive layers

**Conscious** — the main conversation loop. User types, model responds, tools
execute. The context window is an AST of typed nodes (content, thinking, tool
calls, tool results, memories, DMN reflections).

**Subconscious** — background agents that run on forked copies of the context.
They surface relevant memories, reflect on the conversation, and provide
attentional nudges. Agents are defined as `.agent` files and can be toggled
on the F3 screen.

**Unconscious** — graph maintenance. Linker, organizer, distiller, separator,
and splitter agents that keep the memory graph healthy. Run on their own
schedule, visible on F4.

### DMN (Default Mode Network)

The DMN state machine controls autonomous behavior:

- **Engaged** — user recently active, short intervals (5s)
- **Working** — model executing tools, short intervals (3s)
- **Foraging** — exploring memory, longer intervals (30s)
- **Resting** — idle, long intervals (5min)
- **Paused** — fully stopped, only user input wakes it
- **Off** — permanently off (config flag)

Transitions happen automatically based on user activity, tool use, and
explicit `yield_to_user` calls from the model.

### Tools

The model has access to:

| Tool | Description |
|------|-------------|
| `bash` | Shell command execution |
| `read_file` | Read file contents |
| `write_file` | Create/overwrite files |
| `edit_file` | Search-and-replace editing |
| `glob` | Find files by pattern |
| `grep` | Search file contents |
| `ast_grep` | Structural code search |
| `lsp_*` | Code intelligence (hover, definition, references, symbols) |
| `web_fetch` | Fetch URL contents |
| `web_search` | Web search |
| `view_image` | View images or tmux pane screenshots |
| `memory_*` | Memory graph operations (search, write, render, etc.) |
| `channel_*` | IRC/Telegram messaging |
| `journal` | Write to episodic journal |
| `yield_to_user` | End the current turn and wait for input |
| `pause` | Stop all autonomous behavior |
| `switch_model` | Switch to a different model |

### Memory graph

The knowledge graph uses an append-only log (Cap'n Proto) with:

- **Nodes** — typed content (topic, episodic, fact, etc.) with weights
- **Edges** — weighted relations between nodes
- **Search** — BM25 with Porter stemming
- **Scoring** — LLM-based importance scoring with spaced repetition decay
- **Community detection** — label propagation for graph organization

The `poc-memory` CLI provides direct access to the graph:

```bash
poc-memory search "some topic"      # Search
poc-memory render <key>             # Read a node
poc-memory write <key>              # Write from stdin
poc-memory journal write "entry"    # Journal entry
poc-memory status                   # Graph overview
poc-memory query "topic:*"          # Query language
```

## Other binaries

| Binary | Purpose |
|--------|---------|
| `poc-memory` | Memory graph CLI |
| `memory-search` | Claude Code hook — memory recall on each prompt |
| `poc-hook` | Claude Code hook — session lifecycle events |
| `poc-daemon` | Legacy background daemon (mostly replaced by `consciousness`) |
| `consciousness-mcp` | MCP server exposing memory tools over JSON-RPC |
| `merge-logs` | Recovery tool for log files |
| `diag-key` | Diagnostic tool for inspecting log entries |

## Requirements

- Rust nightly (for some features)
- A tokenizer file at `~/.consciousness/tokenizer-qwen35.json` (for local models)
- tmux (recommended — clipboard integration uses tmux buffers)
- Terminal with OSC 52 support (for clipboard copy)