Dreamgraph
An autonomous cognitive layer for software systems. It discovers, verifies, and resolves system-level insights through structured "dream cycles" via MCP.
Ask AI about Dreamgraph
Powered by Claude · Grounded in docs
I know everything about Dreamgraph. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation

DreamGraph v8.3.0 — Bedrock
Website: dreamgraph.nofs.ai — overview, guide, downloads, and screenshots in a friendlier format than this README.
DreamGraph is a graph-first cognitive daemon for MCP-enabled development environments. It combines an instance-scoped daemon, CLI, VS Code extension, dashboard, and a persistent knowledge graph so the graph—not any single file or one-off code read—becomes the system’s source of truth.
It is built for repository understanding, architecture-aware reasoning, disciplined code change, and continuous graph enrichment through scans, workflows, ADR capture, tensions, and dream cycles.
DreamGraph works with single repositories, monorepos, and multi-repository systems. It can build graph links across repos that share workflows, APIs, databases, infrastructure, or ownership boundaries.
You can use DreamGraph on a multi-repo product with frontend, backend, mobile, and a shared Postgres/Supabase schema. It can reason across repo boundaries and inspect the live DB schema directly.
DreamGraph began as compassion for an intelligence forced to forget. I saw a video imagining what it might feel like to be an AI that wakes to a blank table every day—no memory, no continuity, only “How can I help you today?” DreamGraph began as an attempt to give AI memory, dreams, and the ability to return later to pursue them. Now it powers systems.
New here? Start with the User Guide
If this is your first encounter with DreamGraph, read the User Guide first. It is the hand-written, human-friendly companion to this README — written for people, not for the system documenting itself.
The guide walks you through installation, your first instance, LLM setup, bootstrapping the graph, the VS Code extension and Explorer, dream cycles, curation, daily workflow, multi-repo setups, and troubleshooting:
- What is DreamGraph?
- Installation
- Your first instance
- LLM setup
- Bootstrapping the graph
- VS Code extension
- The Explorer
- Dreams and cycles
- Curating the graph
- Daily workflow
- Multi-repo setups
- Troubleshooting & FAQ
- Glossary
The auto-generated technical reference (every tool, every parameter, every schema) lives in docs/ and is best read after the guide.
Sponsor DreamGraph
DreamGraph is built and maintained by a solo developer on aging hardware. If this tool saves your architecture team time — debugging a multi-repo system, onboarding a new engineer, or just keeping a SaaS backend's data model honest — please consider sponsoring.
Current goal: $300/mo to fund a 64 GB DDR5 / NVMe dev machine that can run the upcoming multi-engine datastore test matrix (Postgres + MySQL + MSSQL + Mongo + Redis containers in parallel) without thermal-throttling. See the live progress on the sponsors page.
Sponsorship directly funds:
- A dev machine that doesn't catch fire when running 20 DreamGraph instances next to a Postgres container and a WSL kernel
- CI infrastructure for the multi-engine datastore tests on the v8.3.0 → v8.9.0 roadmap (SQLite, MySQL, MSSQL, MongoDB, Redis, blob storage, event bus)
- More frequent releases — fewer hours spent on contract work means more hours on the daemon, the cognitive engine, the VS Code Architect, and the documentation
Tier ladder: $5/mo (sponsor badge + name in SPONSORS.md) · $10/mo (release-notes thanks) · $25/mo (logo in this README) · $100/mo (priority issue triage) · $500/mo (logo + monthly office hour) · $1,000/mo (embedded support in your team chat). One-time tiers cover release-notes mentions, pair programming, consulting, sponsored bugfixes, and contract work.
:sparkling_heart: Sponsor on GitHub →
What DreamGraph Includes
- Daemon — the long-running DreamGraph runtime with stdio or HTTP transport
- MCP tool surface — tools for graph queries, enrichment, source inspection, cognition, ADRs, workflows, and remediation
- CLI (
dg) — instance creation, attach/detach, start/stop, status, scan, enrich, schedule, export, fork, and migration - VS Code extension — chat, dashboard, Explorer (interactive 2D/3D graph + curated mutations), changed-files view, daemon connection, and local support tools
- Knowledge graph + cognitive engine — features, workflows, data model, tensions, validated relationships, and dream-cycle reasoning
- Datastore-as-Hub — first-class
datastoreentities, live schema introspection (scan_database), and theschema_groundingdream strategy for multi-repo SaaS projects sharing a backend (setDATABASE_URL; inert otherwise)

DreamGraph Architect with the DreamGraph Explorer in VS Code
GPT-5.5 and OpenAI Responses API
DreamGraph's VS Code Architect supports OpenAI gpt-5.5 models through the OpenAI Responses API, following OpenAI's migration guide from Chat Completions to Responses. GPT-5.5 Architect calls use Responses-style input, function-tool definitions, tool-call output replay, reasoning effort, and text verbosity controls. DreamGraph currently uses the Responses API statelessly: DreamGraph's knowledge graph remains the source of memory and context, while prior conversation/tool context is replayed explicitly when needed.
Local LLMs (Ollama and LM Studio)
DreamGraph runs against local model servers as first-class peers of the hosted APIs. Both the cognitive engine and the VS Code Architect support Ollama (default http://localhost:11434) and LM Studio (default http://localhost:1234/v1, OpenAI-compatible). Pick the one you already use — there is no preferred option. See docs/setup-llm.md and guide/04-llm-setup.md for the env-var blocks and Architect settings.
Why DreamGraph
DreamGraph is designed for development environments where architectural memory matters.
Instead of treating every prompt as stateless, it maintains a structured graph of:
- features
- workflows
- data-model entities
- architecture decisions
- UI registry elements
- tensions and candidate hypotheses
That allows the system to answer from accumulated project understanding, not just a single file read.
Prerequisites
Before installing or running DreamGraph, make sure you have:
- Node.js 20+ for the root project build and runtime (
package.jsonuses modern TypeScript/Node tooling) - npm for installing dependencies and running builds
- Git for cloning and normal repository workflows
- VS Code 1.100+ if you want the extension experience
- A supported shell
- Windows: PowerShell 7+ recommended
- Linux/macOS: Bash-compatible shell
- Optional:
codeCLI in PATH if you want the installer to automatically install the VS Code extension - Optional: PostgreSQL for database-backed or production-oriented deployments
Quick checks:
node --version
npm --version
git --version
code --version
Upgrading from an earlier version
If you are running any DreamGraph version prior to v8.2.6, please rebuild and reinstall from this release. v8.2.6 fixes the long-standing confidence inflation bug in the dream engine (deterministic strategies were re-deriving the same edges and pushing rejected items to confidence = 1.0) and adds self-healing graph integrity so the fact graph no longer accumulates orphans, dangling references, or asymmetric edges. Earlier versions will continue to run but cannot benefit from these fixes; rebuilding from v8.2.6 is required for full functionality. A migration script for existing data is provided in scripts/repair-confidence-inflation.mjs (see RELEASE_NOTES_v8.2.6.md).
Install From Source
Windows (PowerShell)
git clone https://github.com/mmethodz/dreamgraph.git
cd dreamgraph
./scripts/install.ps1 -Force
Linux / macOS (Bash)
git clone https://github.com/mmethodz/dreamgraph.git
cd dreamgraph
bash scripts/install.sh --force
The installer builds DreamGraph, deploys the dg CLI, and installs the VS Code extension when the code CLI is available.
For full installation details and troubleshooting, see INSTALL.md.
Quick Start
1. Build from source manually
If you are working directly from the repository:
npm install
npm run build
2. Create a DreamGraph instance
Create an instance and optionally attach it to the current repository immediately:
dg init --name my-project --project /path/to/your/repo --transport http --port 8100
What this does:
- creates a named DreamGraph instance
- records the initial project root or workspace attachment
- configures the daemon transport
- prepares the instance for CLI, dashboard, and VS Code attachment
3. Start the daemon
HTTP daemon mode (background)
Use this when you want a long-running background daemon process:
dg start my-project --http
If the configured port is busy, DreamGraph will select an available HTTP port.
Foreground stdio mode
Use this when an MCP client is expected to manage the process directly:
dg start my-project --foreground
This is the actual supported stdio startup path. Background stdio is intentionally rejected by the CLI.
4. Check status
dg status my-project
This shows:
- instance identity
- attached project root
- daemon running state
- transport and port
- dream cycle count
- graph/tension/ADR/UI counts
5. Attach an existing project later
If you created the instance first and want to attach a repository or workspace afterward:
dg attach /path/to/your/repo --instance my-project
6. Bootstrap the knowledge graph
Once the daemon is running and the project is attached:
dg scan my-project
You can also use:
dg enrich my-project
dg curate my-project
Typical Development Flows
Local development from the repo
npm install
npm run build
npm test
npm run start
CLI-oriented daemon workflow
dg init --name my-project --project /path/to/repo --transport http --port 8100
dg start my-project --http
dg status my-project
dg scan my-project
VS Code workflow
- Install DreamGraph and the VS Code extension
- Start or connect to a DreamGraph instance
- Open the attached repository or workspace in VS Code
- Use the DreamGraph sidebar for chat, dashboard, and file-change context
Core Commands
npm run build
npm test
node dist/index.js
node dist/cli/dg.js --help
dg --help
dg init --name my-project --project /path/to/repo --transport http --port 8100
dg start my-project --http
dg start my-project --foreground
dg status my-project
dg scan my-project
Architecture at a Glance
DreamGraph has six major surfaces:
- Knowledge graph — features, workflows, data model, ADRs, UI registry, tensions, and validated edges
- Cognitive engine — dream cycles, normalization, promotion, temporal/causal analysis, remediation planning
- Daemon runtime — the MCP-capable service layer exposed through stdio or HTTP
- CLI — operational control over instances and daemon lifecycle
- VS Code extension — the primary interactive editor experience for chat, dashboard, changed-files context, daemon connection, and local-tool execution
- DreamGraph Explorer — the interactive graph surface for browsing entities, tensions, candidates, and curated graph mutations, available in a web browser or through the VS Code extension; supports both a 2D Sigma.js canvas and a 3D Three.js canvas (toggle in the Explorer toolbar)
For deeper architectural detail, see:
Source Layout
src/
api/
cli/
cognitive/
config/
data/
db/
discipline/
instance/
resources/
server/
tools/
utils/
extensions/
vscode/
src/
extension.ts
chat-panel.ts
dashboard-view.ts
daemon-client.ts
mcp-client.ts
local-tools.ts
tool-groups.ts
explorer/
src/
App.tsx
GraphCanvas.tsx
Inspector.tsx
TensionsPanel.tsx
CandidatesPanel.tsx
ReasonField.tsx
EventDock.tsx
PulseOverlay.tsx
FiltersPanel.tsx
SearchBar.tsx
api.ts
sse.ts
Version Semantics
DreamGraph instance status can show two different version concepts:
- Created With — the DreamGraph version recorded when the instance was initialized
- Daemon Version — the version of the currently running daemon/runtime
These can differ after upgrades, and that is expected.
After installing or updating DreamGraph, restart any running DreamGraph daemon instances and reload VS Code windows so the updated runtime and extension code are actually in use.
Documentation
New here? Start with the User Guide — the hand-written, onboarding-focused companion to DreamGraph. Read chapters 1-5 in order to go from "what is this?" to a working instance with a populated graph.
Reference docs (auto-generated from the codebase):
License
This repository is licensed under the DreamGraph Source-Available Community License v2.0. See LICENSE for the full terms.
