forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/guides/MANUAL_REVIEW_GUIDE.md

@@ -0,0 +1,58 @@
+# Manual Review Guide
+
+Manual review remains required even when AI review tools are configured.
+
+## Workflow Boundary
+
+`/review` is an agent workflow stage. It is not currently documented as a standalone `forge review` CLI command. Use GitHub, `gh`, adapter tools, and the installed agent review skill for PR review work.
+
+Default stage context:
+
+```text
+/plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+These are the 6 workflow stages. Pre-merge is not a stage or a `/premerge` command — it is a documentation-and-handoff gate embedded in `/ship` and `/review`.
+
+## Review Inputs
+
+Check all available inputs:
+
+- GitHub Actions and required checks
+- human review comments
+- Greptile or other review-bot comments, when configured
+- SonarCloud or code-scanning findings, when configured
+- local validation evidence from `bun run check`
+- design and task artifacts under `docs/work/YYYY-MM-DD-<slug>/`
+
+## Checklist
+
+- The PR description matches the diff.
+- The change stays inside scope.
+- User-facing commands are verified against current code.
+- Security-sensitive claims are backed by code, tests, or configured CI.
+- Tests or validation evidence match the risk of the change.
+- Documentation changes do not present future roadmap work as ready now.
+- Review threads are replied to and resolved where the platform supports it.
+
+## Greptile
+
+If Greptile is configured for the repository, use the repo's review-thread resolution script when available (it handles Greptile and any other review author):
+
+```bash
+bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
+```
+
+Then reply to each thread with the fix, rejection reason, or follow-up issue.
+
+## Final State
+
+Before calling review complete:
+
+```bash
+gh pr checks <pr-number>
+gh pr view <pr-number> --json reviews,comments,statusCheckRollup
+```
+
+All completed required checks should be passing, and unresolved comments should either be fixed or explicitly answered.
+

package/docs/guides/MIGRATION.md

@@ -0,0 +1,56 @@
+# Migration Guide
+
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.0.11 public framing.
+
+## What Changed
+
+Forge is now documented as a local runtime control plane for AI-assisted engineering. The TDD-first workflow is still the default template, but it is no longer the only public explanation of Forge.
+
+## From Stage-Only Docs
+
+Old docs often describe Forge as a fixed seven-, eight-, or nine-stage workflow. Replace that with:
+
+```text
+Default template: /plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+These are the 6 workflow stages. Pre-merge is not a stage or a `/premerge` command — it is a documentation-and-handoff gate embedded in `/ship` and `/review`. A composable `research` skill runs as a phase of `/plan` or standalone. Then add the boundary:
+
+```text
+These are agent workflow stages. Not every stage is a standalone forge CLI command.
+```
+
+## From `forge setup` Only
+
+Use both entry points correctly:
+
+- `forge init` creates the `.forge/` adoption skeleton.
+- `forge setup` installs agent instructions, skills, harness files, local Beads compatibility, and optional setup material.
+- `forge setup --sync` is deprecated and retained only to remove old generated Beads/GitHub sync scaffolding when present.
+
+## From Singular Agent Flags
+
+Replace stale examples that use the old singular agent flag form with:
+
+```bash
+forge setup --agents codex
+forge setup --agents claude,cursor
+```
+
+## Version Labels
+
+- `0.0.11` is the package version for this public docs/readiness release.
+- `0.0.10` is the previous published package version.
+- Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
+
+## Safe Upgrade Path
+
+1. Update docs and examples first.
+2. Run `bun run check`.
+3. Run `npm pack --dry-run`.
+4. Open a PR.
+5. After merge, refresh DeepWiki and verify generated pages against repository docs.
+
+## Rollback
+
+If migration creates confusion, revert the release PR or open a corrective docs PR. Do not publish a package version unless README, CHANGELOG, quickstart, support docs, and package metadata agree.

package/docs/guides/SETUP.md

@@ -0,0 +1,118 @@
+# Setup Guide
+
+This guide covers supported Forge adoption paths. Use [Quickstart](../../QUICKSTART.md) for the shortest path and [Support](SUPPORT.md) when setup fails.
+
+## Prerequisites
+
+- Git
+- Node.js and Bun
+- GitHub CLI if using PR or sync workflows
+- Optional: Beads (`bd`) as an opt-out issue backend (issue commands use the built-in kernel backend by default)
+
+## Install
+
+```bash
+bun add -D forge-workflow
+```
+
+The package exposes `forge`, `forge-workflow`, and `forge-preflight`.
+
+`install.sh` is a thin bootstrapper. It installs or invokes `forge-workflow` and delegates setup to the package; it is not a separate implementation of setup behavior.
+
+## Fresh Repository Runtime Skeleton
+
+Use `forge init` when you want only the local `.forge/` adoption skeleton:
+
+```bash
+bunx forge init --profile minimal --classification standard --harness codex --yes
+```
+
+Supported options:
+
+```text
+--profile minimal|standard|full
+--classification critical|standard|refactor
+--harness claude,cursor,codex
+--yes
+--force
+--dry-run
+```
+
+`forge init` creates `.forge/config.yaml`, `.forge/patch.md`, and `.forge/protected-paths.yaml`. It does not install agent instructions.
+
+## Agent Setup
+
+Use `forge setup` when you want agent-facing files:
+
+```bash
+bunx forge setup --agents codex --yes
+```
+
+Safe examples:
+
+```bash
+bunx forge setup --agents claude,cursor
+bunx forge setup --agents claude cursor
+bunx forge setup --all --quick
+bunx forge setup --path ./my-project --agents codex --dry-run
+bunx forge setup --merge smart --agents claude,cursor
+```
+
+Use `--agents`, not `--agent`.
+
+## Agent Notes
+
+Forge currently supports Claude Code, Codex, and Cursor. Hermes support is planned.
+
+- Claude Code: installs `.claude/commands`, rules, and skills when selected.
+- Cursor: installs Cursor rules and links back to `AGENTS.md`.
+- Codex: uses `AGENTS.md` and may use Codex skills when installed.
+
+Exact generated files depend on selected agents and existing repository files. Use `--dry-run` before applying setup to a mature repo.
+
+## Issue Backend
+
+Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend by default. No install or initialization is required — a fresh clone can track issues immediately.
+
+## Beads (Opt-Out Backend)
+
+Beads (`bd`) is an optional opt-out backend for teams that prefer Dolt-backed sync internals. Select it (precedence, highest first) with `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`; only then is `bd` required. Prefer the current Beads installer documented by Beads itself and this repo's toolchain docs. On Windows, avoid stale global install examples if they hit EPERM or shim issues; use the PowerShell installer path described in [Toolchain](../reference/TOOLCHAIN.md).
+
+When Beads is selected, health checks:
+
+```bash
+bd doctor
+bd dolt status
+forge sync
+```
+
+If a feature worktree reports `database "forge" not found on Dolt server`, diagnose in the root checkout before changing issue state. This applies only to the Beads backend.
+
+## Deprecated GitHub Sync Cleanup
+
+To remove old generated GitHub/Beads sync files from an existing install:
+
+```bash
+bunx forge setup --sync
+```
+
+`forge setup --sync` is deprecated. It now removes old generated Beads/GitHub sync files instead of creating new sync workflows. Future GitHub issue sync belongs to Forge Kernel/server authority, not Beads runtime files or metadata commits.
+
+## Validate Setup
+
+```bash
+bunx forge status --json
+bunx forge board --json
+bun run check
+```
+
+## Troubleshooting
+
+Use [Support and troubleshooting](SUPPORT.md) for:
+
+- Beads/Dolt database errors
+- Windows locked files
+- protected-state blocks
+- branch-protection push failures
+- validation failures
+- DeepWiki refresh drift

package/docs/guides/SUPPORT.md

@@ -0,0 +1,185 @@
+# Support And Troubleshooting
+
+Start here when Forge setup, Beads, protected state, GitHub sync, worktrees, validation, or release readiness fails.
+
+## First Checks
+
+```bash
+git status --short --branch
+git remote show origin
+bun --version
+node --version
+bun run check
+```
+
+If the failure involves Beads:
+
+```bash
+bd doctor
+bd dolt status
+forge sync
+```
+
+If `forge` wrappers fail because Beads is unavailable, use direct `git`, `gh`, and `bd` commands only after identifying the source of truth.
+
+For branch-specific checks, resolve the default branch first:
+
+```powershell
+$defaultBranch = git remote show origin | Select-String 'HEAD branch' | ForEach-Object { $_.ToString().Split(':')[-1].Trim() }
+```
+
+## FAQ
+
+### Is DeepWiki the source of truth?
+
+No. DeepWiki is generated from the repository. Fix README, CHANGELOG, quickstart, docs, CLI files, and tests first, then refresh DeepWiki.
+
+### Is Forge only the seven-stage TDD workflow?
+
+No. The default template is TDD-first, but Forge is a runtime control plane with local state, gates, adapters, issue wrappers, validation evidence, and recovery surfaces.
+
+### Are `/review` and `/verify` CLI commands?
+
+They are agent workflow stages. Do not document them as `forge review` or `forge verify` unless those CLI commands exist in the current code.
+
+### Does protected state always block edits?
+
+Only when `scripts/protected-state-check.js` is wired into the active hook or CI path. The model is real, but enforcement depends on configuration.
+
+### Can agents publish releases?
+
+Agents can prepare a release PR and validation evidence. Publishing is out of scope unless the user explicitly requests it.
+
+## Beads And Dolt Recovery
+
+Common errors:
+
+- `Beads is not initialized in this project.`
+- `database "forge" not found on Dolt server`
+- `database locked`
+- stale `.beads/backup` data
+- Windows EPERM or locked files during worktree cleanup
+
+Triage:
+
+```bash
+bd doctor
+bd dolt status
+bd dolt pull
+bd dolt push
+```
+
+If the Dolt server is serving the wrong database or data directory, stop and diagnose before closing or rewriting issue state. Use the root checkout when the feature worktree has an incomplete `.beads` runtime.
+
+Recovery guidance:
+
+- Preserve current state first: copy `.beads/backup` or export a Beads backup if the command is available.
+- Prefer `forge sync` when Beads is configured and healthy.
+- Use `bd close`, `bd comments`, or `bd dep` directly only for operations Forge does not wrap or when wrappers fail.
+- Do not create follow-up PRs just to commit Beads runtime metadata. `.beads/` is local non-versioned state; shared state must flow through the configured sync/server authority or an explicit projection/import path.
+- Do not hand-edit `.beads` live state unless a recovery procedure explicitly requires it.
+- Success proof is concrete: `bd doctor` exits cleanly, `bd dolt status` is understandable, and `forge ready` or `forge show <id>` can read current issue state.
+
+## GitHub Sync
+
+`forge setup --sync` is deprecated and removes old generated GitHub/Beads sync scaffolding. `forge sync` still runs local Beads/Dolt sync operations when configured. Future GitHub issue sync belongs to Forge Kernel/server authority.
+
+Modern sync should use snapshot, backup, server authority, or explicit projection files, not stale examples that edit or commit live `.beads/issues.jsonl` directly.
+
+When sync fails:
+
+```bash
+gh auth status
+bd doctor
+bd dolt status
+```
+
+```powershell
+gh run list --branch $defaultBranch --limit 10
+```
+
+Check whether GitHub owns the field you are trying to update. GitHub owns shared remote issue fields; Forge/Beads owns local workflow context and recovery metadata.
+
+## Worktrees
+
+Create isolated work:
+
+```bash
+forge worktree create <slug> --branch <branch-name>
+```
+
+Remove it:
+
+```bash
+forge worktree remove <slug>
+```
+
+If removal fails on Windows:
+
+1. Stop any active `node`, `bun`, `gh`, or Dolt process using the worktree.
+2. Run `git worktree list`.
+3. Prove the branch is preserved: `git status --short --branch` and `git log --oneline -1`.
+4. Retry `forge worktree remove <slug>`.
+5. If Git already unregistered the worktree but files remain locked, wait for the process to exit before deleting the leftover directory.
+
+Never delete a worktree before verifying that its branch is pushed or intentionally disposable.
+
+## Branch Protection
+
+Branch protection can reject direct pushes to `master` or `main` with `GH006`. That is expected for code changes.
+
+Beads runtime metadata is not a branch-protection exception. If shared state is required, use the configured sync/server authority or an explicit projection/import path; do not open metadata-only PRs for live `.beads/` files.
+
+Recovery:
+
+```bash
+git status --short --branch
+gh pr checks <pr-number>
+```
+
+```powershell
+git fetch origin $defaultBranch
+```
+
+If shared metadata cannot sync, diagnose the sync/server authority path instead of pushing live `.beads/` state to the protected branch.
+
+## Rollback And Recovery Paths
+
+Choose the rollback path by surface:
+
+- Release documentation confusion: revert the release PR or open a corrective docs PR. Do not publish while README, CHANGELOG, Quickstart, package metadata, and release docs disagree.
+- Setup-generated files: rerun `forge setup --dry-run` first, then rerun setup with the intended `--merge` mode. Preserve existing instruction files before replacing them.
+- Beads metadata: prefer `forge sync`, server authority, or explicit projection/import paths. Avoid direct `.beads` edits unless a documented recovery path requires them.
+- Failed GitHub sync commit: inspect the workflow run, preserve the generated backup or snapshot, then replay through the configured sync workflow or a follow-up branch.
+- Worktree cleanup: prove the branch is pushed or disposable before removal, then remove through `forge worktree remove <slug>` or Git's worktree command if Forge is unavailable.
+
+## Protected State
+
+Protected surfaces include `.beads`, `.forge`, generated agent harness files, workflows, lockfiles, extension manifests, secrets, immutable Git internals, and append-only logs.
+
+If a protected-state check blocks a file:
+
+1. Read the repair hint.
+2. Use the owning command or API surface.
+3. For Forge-owned writes, set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` only for the surfaces that command owns.
+4. For Beads metadata after merge, keep `.beads/` local and diagnose the sync/server authority path when shared state is required.
+
+## Validation Failures
+
+`bun run check` runs:
+
+1. `bun run typecheck`
+2. `bun run lint`
+3. `bun audit`
+4. `node scripts/test.js --validate`
+
+Fix the first failing stage first. Do not hide a validation failure by documenting that it "should pass"; rerun the command and record the fresh result.
+
+## Known Limitations
+
+- Package version remains separate from docs readiness until release/publish occurs.
+- `forge migrate` is dry-run only.
+- Protected-state enforcement depends on hooks/CI wiring.
+- Review adapters currently focus on review adapters and Greptile-shaped scaffolding.
+- DeepWiki can lag after merge until refreshed.
+- Some external services require credentials and branch protection setup outside Forge.

package/docs/guides/WORKFLOW_TEMPLATES.md

@@ -0,0 +1,74 @@
+# Workflow Templates
+
+Forge's workflow is a core product surface, not a side note. The default template gives agents a known path for planning, development, validation, shipping, review, and post-merge verification, with a pre-merge documentation gate that finishes docs and hands off the PR inside the ship and review stages.
+
+## Default Template
+
+The full default template is:
+
+```text
+/plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+Projects can use the full template or smaller profile-specific paths. The important boundary is that these are agent workflow stages, not necessarily standalone `forge <stage>` CLI commands.
+
+## Why It Matters
+
+The template gives AI-assisted work a repeatable operating model:
+
+- `/plan` captures intent, research, branch/worktree setup, and tasks.
+- `/dev` implements through a TDD-oriented loop.
+- `/validate` gathers evidence from project checks.
+- `/ship` prepares a reviewable PR.
+- `/review` handles PR feedback and evaluator findings.
+- `/verify` proves post-merge health when the workflow type requires it.
+
+Before merge, a pre-merge documentation gate finishes documentation and handoff context. It is not a numbered stage or a `/premerge` command; it runs inside the `/ship` and `/review` stages.
+
+The value is not the exact number of stages. The value is recoverable state, known handoff points, validation evidence, and clear ownership while agents work.
+
+## Customization Model
+
+Forge treats the default workflow as a configurable template over runtime building blocks:
+
+- stages can be skipped or shortened by workflow type,
+- project setup can choose different harness targets,
+- `.forge/config.yaml` records adoption profile and harness choices,
+- `forge options lint`, `forge options diff`, and `forge options stages` inspect the resolved config,
+- future work can add or replace stages through skills, adapters, and extension manifests.
+
+Customization should stay explicit. Do not silently remove validation, review, or state handoff steps from high-risk work.
+
+## Workflow Types
+
+Current docs describe these profiles:
+
+| Type | Intended use | Typical path |
+| --- | --- | --- |
+| Critical | Security, auth, payments, migrations, breaking changes | Full template |
+| Standard | Normal features and enhancements | Plan through review |
+| Simple | Small fixes and focused changes | Shorter dev, validate, ship path |
+| Hotfix | Production emergencies | Short path with urgent validation |
+| Docs | Documentation-only changes | Verify and ship |
+| Refactor | Behavior-preserving cleanup | Plan, dev, validate, ship |
+
+Profile docs must be checked against `lib/workflow-profiles.js` and `AGENTS.md` before release because command files, skills, and runtime profiles can drift.
+
+## Skills Direction
+
+Forge is moving toward skills as the portable agent-facing package format. Current v0.0.11 packaging still includes command projections for several agents, and Codex already receives stage workflows as `.codex/skills/<stage>/SKILL.md`.
+
+See [Skills and command projections](../reference/SKILLS.md) for the current source-of-truth boundary.
+
+## Live Feature Rollout
+
+When a planned feature becomes real, update docs in this order:
+
+1. Verify the code, tests, package contents, and CLI output.
+2. Move the feature from roadmap or experimental docs into ready-now docs.
+3. Update README, Quickstart, this guide, and the relevant reference page.
+4. Add migration or support notes if the feature changes setup, state, validation, or workflow behavior.
+5. Refresh DeepWiki after merge and record the generated index date and commit.
+
+Do not document future workflow customization as ready-now until the command, skill, or runtime surface exists and has validation evidence.
+

package/docs/guides/memory-backends.md

@@ -0,0 +1,183 @@
+# Forge Memory
+
+Forge gives agents **durable project memory** through two verbs:
+
+```bash
+forge remember "<note>" [--tag <label>]...   # write a lasting fact
+forge recall  "[query]"  [--limit N]         # read it back
+```
+
+Both route through a small **backend router** (`lib/memory/router.js`). The
+backend is chosen by `memory.backend` in `.forge/config.yaml`:
+
+| Backend | Storage | Needs | When |
+|---|---|---|---|
+| **`local`** (default) | kernel `kernel_memories` table, FTS5-indexed | nothing — offline, instant | always the floor |
+| **`graphiti`** _(experimental)_ | temporal **knowledge graph** over MCP | graph DB + LLM | evolving, relational, temporal recall |
+
+`local` and `graphiti` are the only public `memory.backend` values.
+
+> **The local backend is the default and the guaranteed offline floor.** You do
+> not need to configure anything to use `forge remember` / `forge recall`. The
+> Graphiti backend is strictly **opt-in** and never changes the default path.
+>
+> **`graphiti` is experimental — its runtime emitter is not yet shipped.**
+> Selecting it today still writes the local kernel floor (the graph emit is a
+> best-effort no-op), so `recall` always reads back from the kernel. The config
+> and `forge doctor` reachability checks work; the write-through emit is a
+> fast-follow.
+
+Precedence for selecting the backend:
+`FORGE_MEMORY_BACKEND` env → `memory.backend` in config → `local`.
+
+Check the active backend any time:
+
+```bash
+forge doctor            # reports the memory backend (+ graphiti reachability, non-fatal)
+```
+
+## Local (default) — nothing to set up
+
+Notes persist to the kernel `kernel_memories` table (the per-repo Forge Kernel
+SQLite store under `.git/forge/`), indexed by **FTS5** for token-AND BM25 recall.
+No services, no network, no keys. This is what ships and what most projects
+should use. `recall` with no query returns the newest notes plus a total count;
+a query does full-text BM25 matching (every token must appear, in any order). The
+same kernel table also holds what `forge insights` learns; those records are
+recallable with a query or `--all` (the default no-query listing shows only your
+`remember` notes). (An older flat `.forge/memory/notes.jsonl` is imported once on
+first use, then retired.)
+
+## Opt into Graphiti (knowledge-graph memory)
+
+[Graphiti](https://github.com/getzep/graphiti) (getzep/graphiti) is a Python
+framework that turns notes ("episodes") into a **bi-temporal knowledge graph**:
+an LLM extracts entities and facts, every fact carries two timelines (when it
+was true in the world, and when the system learned it), and superseded facts are
+**invalidated, not deleted** — so you can query "what is true now" or "what was
+true at time T", with a pointer back to the source (provenance). It is served to
+any MCP agent through Graphiti's **MCP server**; Forge only wires it in.
+
+Forge does **not** bundle or reimplement Graphiti. Forge ships the config +
+router seam and documents how to run Graphiti; when `memory.backend` resolves to
+`graphiti` (and the config passes the same validity check `forge doctor` uses),
+**`forge setup` automatically writes the MCP server entry** into `.mcp.json`
+(Claude) and `.cursor/mcp.json` (Cursor) from the descriptor in
+`lib/memory/graphiti-mcp.js`. For other harnesses (e.g. Codex `config.toml`) you
+add the server entry yourself (template below). Design rationale and trade-offs:
+[`docs/work/2026-07-06-graphiti-memory/research.md`](../work/2026-07-06-graphiti-memory/research.md).
+
+### 1. Turn it on (config)
+
+Set the backend in `.forge/config.yaml` — additive and reversible:
+
+```yaml
+memory:
+  backend: graphiti
+  graphiti:
+    # --- active today (validated by the router / forge doctor) ---
+    transport: stdio            # stdio | http
+    mcpServerPath: ./graphiti/mcp_server   # required — path to the Graphiti checkout's mcp_server dir
+    graphDb: falkordb           # falkordb | falkordb-lite | neo4j
+    apiKeyEnv: OPENAI_API_KEY    # referenced by NAME — never store the key here
+    # --- reserved: NO EFFECT yet (the descriptor emits ${VAR} env references, not these values) ---
+    dbUri: redis://localhost:6379
+    llmProvider: openai
+    model: gpt-5.5
+    groupId: <your-project>
+```
+
+Only `mcpServerPath` is required today (it's what `forge doctor` checks and what
+the descriptor threads into the launch args). The keys under "reserved" still
+have no effect — the rendered entry references env vars (`${VAR}`), not these
+literal values — set them now only if you like, they are no-ops until a renderer
+consumes them.
+
+Forge exposes the MCP server as a harness-agnostic **descriptor** (see
+`lib/memory/graphiti-mcp.js`, `buildGraphitiServerDescriptor`) and `forge setup`
+wires it into the right place for Claude (`.mcp.json`) and Cursor
+(`.cursor/mcp.json`), preserving any servers you already have there. Codex
+(`config.toml`) is not auto-wired yet. The descriptor's env values are `${VAR}`
+references only — Forge never writes a secret into any committed config. The
+rendered entry looks like:
+
+```json
+"graphiti-memory": {
+  "transport": "stdio",
+  "command": "uv",
+  "args": ["run","--isolated","--directory","./graphiti/mcp_server",
+           "--project",".","main.py","--transport","stdio"],
+  "env": {
+    "FALKORDB_URI": "${FALKORDB_URI}",
+    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+    "MODEL_NAME": "${MODEL_NAME}",
+    "GROUP_ID": "${GRAPHITI_GROUP_ID}"
+  }
+}
+```
+
+### 2. Run the graph DB + MCP server
+
+Graphiti needs a **graph database** and an **LLM/embedder**. The documented
+default is **FalkorDB** (a light, Redis-based graph DB via Docker) with an
+OpenAI-compatible model. Roughly:
+
+```bash
+# a) graph DB (FalkorDB) — or run the Graphiti combined Docker Compose
+docker run -p 6379:6379 -it --rm falkordb/falkordb:latest
+
+# b) the Graphiti MCP server (from a graphiti checkout)
+git clone https://github.com/getzep/graphiti
+cd graphiti/mcp_server
+export OPENAI_API_KEY=sk-...          # or point at an OpenAI-compatible endpoint
+uv run --isolated --directory . --project . main.py --transport stdio
+```
+
+Set `memory.graphiti.mcpServerPath` in `.forge/config.yaml` to the checkout's
+`mcp_server` directory so `forge doctor` can see it.
+
+**Alternatives** (all documented in the design doc):
+
+- **Graph DB:** FalkorDB (Docker, default) · FalkorDB-lite (embedded, Python
+  3.12+, no server) · Neo4j (production). Set `memory.graphiti.graphDb` +
+  `dbUri` accordingly (Neo4j uses `NEO4J_URI` plus `NEO4J_USER` and
+  `NEO4J_PASSWORD`).
+- **LLM/embedder:** OpenAI (best quality) · any OpenAI-compatible endpoint
+  (OpenRouter, DeepSeek, Together) · **Ollama** for a fully local/offline stack
+  (`ollama pull deepseek-r1:7b` + `ollama pull nomic-embed-text`). Set
+  `memory.graphiti.llmProvider` / `model` / `apiKeyEnv`.
+
+### 3. Use it
+
+Once wired, **agents** call the graph directly over MCP:
+
+- `add_memory` — record a durable fact/decision as an episode (scope with
+  `group_id`). Ingestion is LLM-backed, so treat writes as async.
+- `search_memory_facts` — retrieve facts/edges (with validity windows) before
+  assuming.
+- `search_nodes` — find entities and summaries.
+
+The **`memory` skill** ([`skills/memory/SKILL.md`](../../skills/memory/SKILL.md))
+teaches agents when and how to use these. `forge remember` / `forge recall` keep
+working from the CLI — when the graph backend is selected they still write to the
+local kernel store as a safety floor, so a note is never lost.
+
+## Privacy & cost (read before enabling)
+
+- **Privacy:** with an LLM provider like OpenAI, **every note you add as an
+  episode is sent to that LLM** for entity/fact extraction. For private dev
+  notes this matters — use the Ollama/local path if that is a concern.
+- **Cost + latency:** `add_memory` fires **multiple LLM calls** per episode, so
+  writes are billable and take from sub-second to a couple of seconds. Prefer
+  async ingest; retrieval is cheap.
+- **Ops:** you run and maintain a graph DB + the (experimental) Graphiti MCP
+  server. This is a real jump from "write a note to the local kernel store" —
+  which is exactly why it is opt-in and the local backend stays the default.
+
+## Turning it off
+
+Remove `memory.backend` (and the `memory.graphiti` block) from
+`.forge/config.yaml` — the router falls straight back to `local`. Your local
+kernel notes were never touched. If a `graphiti-memory` entry is in your agent's
+MCP config — whether `forge setup` wrote it when you enabled Graphiti, or you
+added it by hand — delete it too.