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

cargo install --path .

Create a config file at ~/.consciousness/config.json5 (see Configuration below), then:

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:

{
    // 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:

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)