dreamgraph

 # DreamGraph v12.2.0 — Trust Calibration and Reviewable Cognition       [](https://dreamgraph.nofs.ai/) **Website:** [dreamgraph.nofs.ai](https://dreamgraph.nofs.ai/) — overview, guide, downloads, and screenshots in a friendlier format than this README. **New here?** Use the [DreamGraph Easy Start guide](guide/00-easy-start.md) for a short path from install to Dashboard, Explorer, and Architect. DreamGraph is a governed architecture cognition layer for MCP-enabled software projects. It combines an instance-scoped daemon, CLI, architect beta, VS Code extension, dashboard, and a persistent knowledge graph so project understanding is grounded in source, ADRs, workflows, tests, runtime observations, and human review rather than any single file read or isolated chat turn. **v12.0.0 Hippodamus introduces the standalone architect beta.** From this release onward, **architect** means the daemon-served standalone browser Architect surface. The editor-integrated chat surface is the **VS Code architect**. Architect beta brings project-bound chat, selected-plan scope, runtime provenance, model/adapter route visibility, governed DreamGraph MCP tool use, and auditable tool traces into the browser while keeping the daemon, graph, ADRs, and source mutations authoritative. 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. Cognitive outputs are advisory until backed by governed evidence or explicit review, and expired, rejected, retired, or superseded ideas remain inspectable as part of the project history.  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. It has become a governed way for software systems to remember how their architecture understanding changes: what was observed, what was hypothesized, what was reviewed, what was rejected, what expired, and what superseded it. ## What do I need DreamGraph for as a developer? You need DreamGraph when your codebase has become bigger than your short-term memory. DreamGraph is not just another AI coding chat. It is an architecture cognition and review layer for your projects: part architect, part code cartographer, part release assistant, and part systems analyst. > DreamGraph helps you understand, change, and evolve software without losing the plot. For developers, that means: - Ask better questions of your codebase: “Where does auth really happen?”, “What breaks if I change this?”, “Why is this module risky?”, “What should I refactor next?” - Turn AI from a stateless assistant into a project-aware architect that tracks decisions, tensions, patterns, APIs, plugins, repos, past work, and the evidence behind each claim. - Make large changes safer by using graph context, ADRs, tool traces, schedules, cognitive cycles, and multi-repo awareness instead of relying only on grep and vibes. - Expose your system to itself: plugins, MCP tools, CLI, schedules, resources, UI panels, and cognitive engine all become connected parts of one inspectable development environment. - Support both fast vibe coding and serious engineering: prototype quickly while still accumulating structure, provenance, release notes, architectural insight, lifecycle history, and remediation plans. For vibe coders, DreamGraph is the guardrail. For app developers, it is the product-building cockpit. For system engineers, it is the architecture intelligence layer. Short version: **DreamGraph is for developers who want AI help that understands the system, explains what changed, and shows why each recommendation should be trusted, inspected, ignored, retired, or superseded.** ## New here? Start with the User Guide If this is your first encounter with DreamGraph, **read the [User Guide](guide/README.md) 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: 1. [What is DreamGraph?](guide/01-what-is-dreamgraph.md) 2. [Installation](guide/02-installation.md) 3. [Your first instance](guide/03-first-instance.md) 4. [LLM setup](guide/04-llm-setup.md) 5. [Bootstrapping the graph](guide/05-bootstrapping-the-graph.md) 6. [VS Code extension](guide/06-vs-code-extension.md) 7. [The Explorer](guide/07-the-explorer.md) 8. [Dreams and cycles](guide/08-dreams-and-cycles.md) 9. [Curating the graph](guide/09-curating-the-graph.md) 10. [Daily workflow](guide/10-daily-workflow.md) 11. [Multi-repo setups](guide/11-multi-repo.md) 12. [Troubleshooting & FAQ](guide/12-troubleshooting-faq.md) 13. [Glossary](guide/13-glossary.md) 14. [Adaptive Future Engine](guide/14-adaptive-future-engine.md) 15. [Architect beta](guide/15-architect-beta.md) The auto-generated technical reference (every tool, every parameter, every schema) lives in [`docs/`](docs/README.md) and is best read *after* the guide. **Building plugins?** The full **Plugin Developer Guide & Reference Manual** lives in [`docs/sdk/`](docs/sdk/) (Markdown source). A multi-file HTML site and a single-file PDF are produced by [`scripts/build-plugin-docs.ps1`](scripts/build-plugin-docs.ps1) into `docs/sdk/site/`. Start with [`docs/sdk/plugin-developer-guide/00-index.md`](docs/sdk/plugin-developer-guide/00-index.md) for the guide and [`docs/sdk/plugin-reference/00-index.md`](docs/sdk/plugin-reference/00-index.md) for the strict reference. Working reference plugins live at [`examples/hello-events/`](examples/hello-events/) and [`examples/action-checklist/`](examples/action-checklist/). ## 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. [](https://github.com/sponsors/mmethodz) **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](https://github.com/sponsors/mmethodz). 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`](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 →**](https://github.com/sponsors/mmethodz) ## 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 - **Architect beta** — standalone browser Architect for project-bound chat, selected-plan scope, runtime provenance, model/adapter route visibility, governed MCP tool use, and auditable tool traces - **VS Code extension** — VS Code architect 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, dream-cycle reasoning, trust calibration, evidence ledgers, and lifecycle visibility - **Adaptive Future Engine** — advisory candidate-future ranking, future-fit scoring, compact objections, and bounded audit metadata for graph-tool and cognitive-workflow decisions - **Datastore-as-Hub** — first-class `datastore` entities, live schema introspection (`scan_database`), and the `schema_grounding` dream strategy for multi-repo SaaS projects sharing a backend (set `DATABASE_URL`; inert otherwise) - **Plugin host & SDK (v9.0.0 — stable seams M0–M6)** — in-process plugin runtime (`@dreamgraph/sdk` + `@dreamgraph/host`) with manifest discovery from `<instance>/plugins/<id>/plugin.json`, capability/effect gate registry, telemetry bridge, trust banner, and `dg plugin` CLI (`list`, `inspect`, `register`, `enable`, `disable`, `trust`, `reload`, `unload`). Hot reload/disable plus enriched `system://plugins` (activation, subscriptions, contributed tools/resources). Plugin-contributed MCP tools and resources via `ctx.tools.register` / `ctx.resources.register`, gated by `tools:register` / `resources:register` capabilities and naming/namespace prefix rules. M5 ships outbound webhooks as a *core* subsystem (`dg webhook` CLI; HMAC-signed delivery; persistent dead-letter; replay). M6 adds the UI/closure seams (archetypes, policies, markdown fences, UI hooks). Standalone Architect plugins can also register declarative host-rendered tabs with explicit plan scope, daemon-owned namespaced state, governed actions, sidebar summaries, and badges. Opt-in via `DG_ALLOW_INPROCESS_PLUGINS=true` plus per-plugin `trusted: true` in `instance.json`. See `examples/hello-events/` and `examples/action-checklist/` for reference plugins and [`docs/sdk/`](docs/sdk/) for the developer guide and reference manual.  *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](https://developers.openai.com/api/docs/guides/migrate-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](docs/setup-llm.md) and [guide/04-llm-setup.md](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.json` uses 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: `code` CLI 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: ```bash 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](RELEASE_NOTES_v8.2.6.md)). ## Install From Source ### Windows (PowerShell) ```powershell git clone https://github.com/mmethodz/dreamgraph.git cd dreamgraph ./scripts/install.ps1 -Force ``` ### Linux / macOS (Bash) ```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](INSTALL.md). ## Quick Start ### 1. Build from source manually If you are working directly from the repository: ```bash npm install npm run build ``` ### 2. Create a DreamGraph instance Create an instance and optionally attach it to the current repository immediately: ```bash 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: ```bash 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: ```bash dg start my-project --foreground ``` This is the actual supported stdio startup path. Background stdio is intentionally rejected by the CLI. ### 4. Check status ```bash 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: ```bash dg attach /path/to/your/repo --instance my-project ``` ### 6. Bootstrap the knowledge graph Once the daemon is running and the project is attached: ```bash dg scan my-project ``` You can also use: ```bash dg enrich my-project dg curate my-project ``` If you need to manually trigger DreamGraph's full bootstrap flow, use `dg bootstrap my-project` (see the [bootstrapping guide](guide/05-bootstrapping-the-graph.md#dg-bootstrap--the-operator-override-v825)). This is mainly the operator escape hatch when `dg scan` / `dg enrich` are not enough. ## Typical Development Flows ### Local development from the repo ```bash npm install npm run build npm test npm run start ``` ### CLI-oriented daemon workflow ```bash 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 1. Install DreamGraph and the VS Code extension 2. Start or connect to a DreamGraph instance 3. Open the attached repository or workspace in VS Code 4. Use the DreamGraph sidebar for chat, dashboard, and file-change context ## Core Commands ```bash 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 dg plugin list my-project dg plugin inspect my-project <plugin-id> ``` ## 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 - **Adaptive Future Engine** — ranks compliant candidate futures with graph evidence, ADR/workflow/API constraints, score factors, objections, and compact audit trails - **Daemon runtime** — the MCP-capable service layer exposed through stdio or HTTP - **CLI** — operational control over instances and daemon lifecycle - **Architect beta** — the standalone browser Architect experience for daemon-authoritative project work, selected-plan chat, tool traces, and runtime provenance - **VS Code extension** — the primary interactive editor experience for VS Code architect 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: - [docs/architecture.md](docs/architecture.md) - [docs/cognitive-engine.md](docs/cognitive-engine.md) - [docs/adaptive-future-engine.md](docs/adaptive-future-engine.md) - [docs/tools-reference.md](docs/tools-reference.md) - [docs/workflows.md](docs/workflows.md) ## Source Layout ```text src/ api/ cli/ cognitive/ config/ data/ db/ discipline/ instance/ plugins/ resources/ server/ tools/ utils/ packages/ sdk/ # @dreamgraph/sdk — public plugin contracts (manifest, telemetry, reject reasons) host/ # @dreamgraph/host — in-process plugin loader, gate registry, watchdog examples/ hello-events/ # M3 reference plugin extensions/ vscode/ src/ extension.ts chat-panel.ts dashboard-view.ts daemon-client.ts mcp-client.ts local-tools.ts tool-groups.ts architect-core/ adapters/ copilot-cli/ # native GitHub Copilot CLI Architect adapter codex-cli/ # native Codex CLI Architect adapter, runner/auth recovery, ProviderPort seam, chat routing, and live MCP tool traces 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](guide/README.md)** — 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): - [Architect beta user guide](guide/15-architect-beta.md) - [INSTALL.md](INSTALL.md) - [Living Docs](docs/index.md) - [docs/architecture.md](docs/architecture.md) - [docs/setup-llm.md](docs/setup-llm.md) - [docs/tools-reference.md](docs/tools-reference.md) ## License This repository is licensed under the **DreamGraph Source-Available Community License v2.0**. See [LICENSE](LICENSE) for the full terms.