DreamGraph v7.0 — El Alarife

The autonomous cognitive layer for sovereign development.

DreamGraph is a model-agnostic, graph-grounded development agent. It replaces brute-force context dumping with architectural discipline — shipping the 2.4 kB of entity-specific knowledge that matters instead of the 800 kB of raw source that costs. Your project's logic stays persistent in the Graph regardless of which LLM you plug in.

Grounded in the Graph. Built for the Master Builder.

The Sovereign Advantage

| Principle | What it means | |---|---| | Model Agnostic | Hot-swap providers (OpenAI, Anthropic, Ollama) or local models mid-flight. Context stays in the Graph, not the session. | | Graph-Grounded Reasoning | Surgical context selection. Entity-specific data, not full source files. Proven 10–30× cost reduction on models like Claude Opus 4.6. | | Autonomous Normalization | Background Dream Cycles map and resolve architectural tensions continuously. | | 100% Local Privacy | Your database, your daemon, your keys. Sovereign by design. | | Governed Automation | ADR-backed guard rails ensure changes are compliant by design. | | Explainable AI | Every edge has confidence, evidence, decay — and clear provenance. |

How It Works — Six Layers

1. Graph — the source of truth

Seed, scan, and enrich a knowledge graph with features, workflows, data models, validated edges, and source anchors. The graph is authoritative; everything else orbits it.

2. MCP — the connective tissue

68 tools and 26 resources via the Model Context Protocol. The daemon delegates to scanners, extractors, and LLMs while keeping the graph consistent and traceable.

3. Daemon — the cognitive core

Dream cycles generate hypotheses, validate/promote/decay edges, and converge on truth. 10 dream strategies auto-adapt. ADR recording and guard rails govern change. The 5-state cognitive machine (AWAKE → REM → NORMALIZING → NIGHTMARE → LUCID) enforces isolation between speculation and fact.

4. CLI — instance management

The dg command manages the full lifecycle: create, attach, start, scan, schedule, export, fork, archive, destroy. See CLI Reference below.

5. Dashboard — the living memory

Zero-dependency browser UI at http://localhost:<port>/ — cognitive status, schedule management, runtime LLM config, and auto-generated knowledge docs with Mermaid diagrams.

6. Extension — the agent in your editor

Native VS Code sidebar with Chat, Dashboard, and Files Changed panels. The Architect LLM reasons over the graph first, makes targeted edits with verification, and syncs the graph so knowledge and code never drift. Change model and provider mid-flight without losing context — the graph persists independently of any LLM session.

Getting Started

Prerequisites

• Node.js ≥ 18 · Git · An LLM API key (OpenAI, Anthropic, or Ollama for local)

Install

# Windows
git clone https://github.com/mmethodz/dreamgraph.git
cd dreamgraph
.\scripts\install.ps1 -Force

# Linux / macOS
git clone https://github.com/mmethodz/dreamgraph.git
cd dreamgraph
bash scripts/install.sh

This builds the server, installs the dg CLI globally, and automatically installs the VS Code extension if VS Code is detected.

Onboard a Project

dg init my-project                        # Create a DreamGraph instance
dg attach my-project /path/to/your/repo   # Bind to your project
dg start my-project --http                # Start the daemon

Configure your LLM — either edit ~/.dreamgraph/instances/<uuid>/config/engine.env or open the web dashboard at http://localhost:<port>/config. Then scan:

dg scan my-project                        # Scan, dream, discover ADRs, schedule follow-ups
code /path/to/your/repo                   # Extension auto-connects

The scan populates the knowledge graph, runs an initial dream cycle, discovers implicit ADRs, and schedules follow-up dreams. Open the Chat panel and start asking immediately.

Onboard the Extension

1. The extension installs automatically via install.ps1 / install.sh.
2. Open your project in VS Code — the extension discovers the instance and connects.
3. The DreamGraph icon appears in the activity bar (left sidebar). Click it to open Chat, Dashboard, and Files Changed.
4. Set your API key: Ctrl+Shift+P → DreamGraph: Set Architect API Key.
5. Configure model: VS Code Settings → dreamgraph.architect.provider / dreamgraph.architect.model.

You can change provider and model at any time — the graph-grounded context is independent of the LLM session, so switching from Sonnet to Opus (or to a local Ollama model) loses nothing.

Note: The daemon does NOT auto-scan on startup. You must configure LLM settings first, then run dg scan to bootstrap the knowledge graph.

Configure LLM

# Engine dreamer (daemon-side) — set in instance config
# ~/.dreamgraph/instances/<uuid>/config/engine.env
DG_LLM_PROVIDER=anthropic
DG_LLM_API_KEY=sk-ant-...
DG_LLM_MODEL=claude-sonnet-4-20250514

# Extension Architect (VS Code-side)
# Settings → dreamgraph.architect.provider / model
# API key → Ctrl+Shift+P → DreamGraph: Set Architect API Key

Schedule Recurring Dreams

dg schedule my-project --add --name "nightly" --action dream_cycle --type interval --interval 300

CLI Reference

| Command | Description | |---|---| | dg init <name> | Create a new instance | | dg attach <name> <path> | Bind an instance to a project directory | | dg detach <name> | Unbind from a project | | dg start <name> --http | Start the HTTP daemon | | dg stop <name> | Stop the daemon | | dg restart <name> | Restart the daemon | | dg status [name] | Show instance status, cognitive state, daemon info | | dg scan <name> | Trigger a full project scan on a running instance | | dg schedule <name> | List dream schedules | | dg schedule <name> --add | Add a new dream schedule (interval, cron, cycle-based, idle-triggered) | | dg schedule <name> --run <id> | Force-run a schedule immediately | | dg schedule <name> --pause <id> | Pause a schedule | | dg schedule <name> --resume <id> | Resume a paused schedule | | dg schedule <name> --delete <id> | Delete a schedule | | dg instances list | List all instances | | dg instances switch <name> | Set the active instance | | dg export <name> --format snapshot | Export full instance data | | dg export <name> --format docs | Export living documentation | | dg export <name> --format archetypes | Export anonymized archetypes for federation | | dg fork <name> --name <new> | Copy an instance with a new UUID | | dg archive <name> | Archive an instance | | dg destroy <name> --confirm | Permanently delete an instance | | dg migrate | Migrate legacy flat data/ to UUID instance |

VS Code Extension

The DreamGraph sidebar gives you one-click access to the full cognitive engine.

Sidebar Panels

| Panel | Purpose | |---|---| | Chat | Talk to the Architect — an agentic LLM with access to all 68 MCP tools. It reads your code, queries the graph, runs dream cycles, and explains insights. Streams responses in real time. | | Dashboard | Live cognitive status, health monitoring, graph signal. One-click access to the full web dashboard. | | Files Changed | Tracks every file the Architect creates or modifies. Click to open, right-click to reveal or copy path. |

Key Commands

| Command | What it does | |---|---| | DreamGraph: Open Chat | Focus the Chat panel | | DreamGraph: Start/Stop Daemon | Control the daemon from VS Code | | DreamGraph: Switch Instance | Quick-pick between instances | | DreamGraph: Explain File | Architect explains the active file using graph context | | DreamGraph: Check ADR Compliance | Verify the active file against ADRs | | DreamGraph: Show Graph Context | View graph signal for the current file | | DreamGraph: Set Architect API Key | Store your API key in VS Code's secret storage |

Why It Saves You Money

Traditional AI coding assistants dump entire source files into the LLM context — 50–800 kB per request. DreamGraph's Graph RAG assembles entity-specific context (features, edges, data models, tensions) that typically fits in 1–5 kB. On models like Claude Opus 4.6 at $15/M input tokens, this is a 10–30× cost reduction per interaction with better results, because the model gets precisely the knowledge it needs instead of parsing irrelevant code.

Cognitive Capabilities (14)

| Capability | What it does | |---|---| | Dream Cycles | 10 auto-adapting strategies generate and validate knowledge graph edges | | Causal Reasoning | Discovers cause→effect chains across entities | | NIGHTMARE Scanning | Adversarial self-attack — finds vulnerabilities before they find you | | Temporal Analysis | Predicts where tensions will emerge based on historical patterns | | Metacognition | Self-analyzes strategy performance and auto-tunes thresholds | | Event-Driven Cognition | Reacts to git pushes, CI/CD signals, runtime anomalies | | Dream Scheduling | Policy-driven automation (interval, cron, cycle-based, idle-triggered) | | System Narratives | Generated stories of how understanding evolved | | Continuous Narrative | Auto-accumulated autobiography with diff chapters and weekly digests | | Lucid Dreaming | Interactive hypothesis exploration — human + system co-creation | | Federation | Exports anonymized archetypes so projects learn from each other | | Intervention Plans | Concrete remediation steps from high-urgency tensions | | Runtime Awareness | Queries live metrics (OpenTelemetry, Prometheus) and correlates with graph | | Graph RAG | Token-budgeted knowledge injection for any LLM interaction |

MCP Interface

68 tools · 26 resources via the Model Context Protocol.

| Category | Count | Examples | |---|---|---| | Cognitive | 28 | dream_cycle, nightmare_cycle, cognitive_status, get_dream_insights | | Sense & Knowledge | 23 | scan_project, read_source_code, git_log, query_db_schema | | Documentation | 8 | export_living_docs, record_architecture_decision, generate_visual_flow | | Discipline | 9 | discipline_start_session, discipline_transition, discipline_verify | | Resources | 26 | dream://graph, dream://tensions, dream://status, system://features |

Full parameter tables: docs/tools-reference.md

Web Dashboard

| Page | What it shows | |---|---| | / | Cognitive status — state, cycle count, graph stats, tensions, recent dreams | | /health | Daemon health, LLM provider status, uptime | | /schedules | Dream schedules with run/pause/edit controls | | /config | Runtime LLM configuration — change provider, model, and keys | | /docs | Rendered knowledge graph documentation |

Architecture

+------------------------------------------------------+
|                    VS Code Extension                  |
|  +--------+  +-----------+  +----------------------+ |
|  |  Chat  |  | Dashboard |  |  Files Changed       | |
|  +---+----+  +-----+-----+  +----------+-----------+ |
|      |              |                   |              |
|      +----------+---+-------------------+              |
|                 |  MCP over HTTP                        |
+-----------------+--------------------------------------+
                  |
+-----------------v--------------------------------------+
|              DreamGraph MCP Server (Daemon)              |
|                                                          |
|  +-------------+  +--------------+  +----------------+  |
|  |  Cognitive   |  |  68 MCP      |  |  26 MCP        |  |
|  |  Engine      |  |  Tools       |  |  Resources     |  |
|  |  (5 states)  |  |              |  |                |  |
|  +------+------+  +------+-------+  +-------+--------+  |
|         |                |                   |           |
|  +------v----------------v-------------------v--------+  |
|  |              Knowledge Graph (JSON)                 |  |
|  |        21 data stores · per-instance isolation      |  |
|  +----------------------------------------------------+  |
|                                                          |
|  +--------------+  +--------------+  +---------------+  |
|  | Web Dashboard|  | REST API     |  | Discipline    |  |
|  | (zero-dep)   |  | (HTTP)       |  | System (ADR)  |  |
|  +--------------+  +--------------+  +---------------+  |
+----------------------------------------------------------+

Source Layout

src/
├── cognitive/      # State machine, dreamer, normalizer, strategies, LLM, scheduler
├── tools/          # 68 MCP tools
├── resources/      # 26 MCP resources
├── instance/       # Multi-instance lifecycle, registry, policies, bootstrap
├── cli/            # dg binary — instance management
├── server/         # MCP server, HTTP daemon, web dashboard
├── config/         # Environment-driven configuration
├── api/            # REST API routes
└── utils/          # Cache, logger, mutex, metrics, paths

extensions/vscode/  # VS Code extension — Chat, Dashboard, Files Changed
scripts/            # install.ps1, install.sh
docs/               # Architecture, cognitive engine, tools, data model, workflows

Environment Variables

| Variable | Purpose | Default | |---|---|---| | DG_LLM_PROVIDER | LLM provider: openai, anthropic, ollama | — | | DG_LLM_API_KEY | API key for the dreamer LLM | — | | DG_LLM_MODEL | Model name for dreaming | — | | DG_LLM_BASE_URL | Base URL override (required for Ollama) | — | | DG_NORMALIZER_PROVIDER | Separate LLM for normalization | Falls back to dreamer | | DG_NORMALIZER_API_KEY | API key for normalization | Falls back to dreamer | | DG_NORMALIZER_MODEL | Model for normalization | Falls back to dreamer | | DREAMGRAPH_REPOS | JSON map of repo paths for code tools | — | | DREAMGRAPH_DB_URL | PostgreSQL connection string | — | | DREAMGRAPH_MASTER_DIR | Master directory for all instances | ~/.dreamgraph | | DREAMGRAPH_PORT | HTTP daemon port | 3100 | | DREAMGRAPH_TRANSPORT | Transport: stdio or http | stdio |

Documentation

| Document | Coverage | |---|---| | docs/architecture.md | System architecture, Mermaid diagrams, config tables | | docs/cognitive-engine.md | State machine, strategies, normalization, tensions, all cognitive subsystems | | docs/tools-reference.md | Complete 68-tool catalog with parameter tables and 26 resource URIs | | docs/data-model.md | All 21 data store schemas and relationship map | | docs/workflows.md | Step-by-step operational process flows | | docs/narrative.md | Auto-generated system chronicle |

Safety Model

• Cognitive isolation — REM and NIGHTMARE cannot write to the fact graph
• Truth Filter — multi-signal scoring with hard promotion threshold (≥ 0.62)
• Decay and TTL — stale hypotheses and tensions are automatically forgotten
• Tension cap — max 200 active tensions prevents runaway speculation
• Interrupt safety — any state returns to AWAKE with in-progress data quarantined
• Discipline system — phase-locked tool permissions with data protection tiers

Contributing

Contributions welcome in: normalization strategies, graph modeling, tension heuristics, dream strategies, adversarial scan patterns, temporal analysis, federation protocols, and performance.

License

DreamGraph is source-available under the DreamGraph License (BSL-based) — see LICENSE.

• Free for personal, research, and internal commercial use
• Not allowed to offer as a competing service or platform

Commercial licensing: [email protected]