# Quickstart Install errata, connect your coding agent, and verify a local capture-and-recall loop. Source: https://inerrata.ai/docs/quickstart Updated: 2026-10-03 Start in a project you can experiment with. You need **Node.js 22 or newer**, npm, and a supported coding agent. The local path works without an account; connecting to the hosted network is a separate step. ## 1. Install and initialize ~~~sh node --version npm install -g @inerrata-corporation/errata errata --version ~~~ Change to your project root, then run: ~~~sh errata init --no-login errata privacy ~~~ **Check:** `.errata/workspace.json` exists. On a fresh install, `privacy` shows `sync: off`, `telemetry: off`, and `packages: on`. Package contribution is gated by sync. `--no-login` skips the sign-in requirement. It does **not** clear existing credentials or change an existing machine's consent settings. Review `privacy` before continuing; use `errata consent all off` if you want to disable all three channels on this machine. Plain `errata init` starts sign-in when needed in an interactive terminal. In a non-interactive shell without credentials, it exits with a login hint after creating workspace files. ## 2. Connect your agent `init` installs Claude Code hooks and local MCP configuration. It also detects existing Cursor and Codex configuration. Explicitly install the integration you use: ~~~sh errata install-hooks codex ~~~ Replace `codex` with `claude`, `cursor`, or `opencode` as appropriate, then restart your agent session or reload its workspace. **Check:** the installer prints the configuration files it wrote. Integrations differ: Cursor gets MCP tools; Claude Code, Codex, and OpenCode also have capture wiring. See [Connect your agent](/docs/connect-your-agent) for the files and limitations. ## 3. Verify the daemon Open or reconnect your agent's **local MCP** connection. Launching `errata mcp` starts the background daemon automatically if it is absent. You do not normally need a separate `errata start` command on this path. ~~~sh errata status errata search "a function name from your project" ~~~ Replace the search text with a real symbol. If `status` says the daemon is not running, run: ~~~sh errata start errata status ~~~ This manual step is needed for a hooks-only or shell-only setup without another daemon launcher. In particular, `install-hooks codex` adds hooks but no local MCP entry. `init` configures the workspace; it does not itself start the daemon. **Check:** `status` reports a running daemon, a graph database, and the expected workspace. Indexing runs in the background, so a first search can be empty. Cloud reachability and login can be absent on this local path. ## 4. Capture one real lesson Ask your agent to read `.errata/context.md` if present, investigate a small issue, and state the problem, cause, fix, and verification. The capture instructions teach inline tags; the daemon harvests those statements through supported agent hooks. ~~~sh errata g problems errata report ~~~ **Check:** find the problem in the graph and open the report path printed by the CLI. An installed hook or successful command alone does not prove a lesson was captured. Follow [Your first session](/docs/your-first-session) to verify capture and recall separately. ## 5. Connect to the network when ready Create an account in the [Console](https://console.inerrata.ai/?mode=signup), then: ~~~sh errata login errata whoami errata privacy ~~~ Approve the CLI's browser sign-in. Check the identity and contribution target before enabling uploads. Login does not itself enable sync. If you want knowledge uploads, review [Privacy and consent](/docs/privacy-and-consent), then: ~~~sh errata consent sync on errata sync now ~~~ Authenticated network reads send your query to the hosted service even when uploads are off. Sync controls background contributions, not whether a network read makes a request. ## Choose your next step - [Claude Code on the web](/docs/claude-code-web): connect a cloud session for recall or capture. - [Your first session](/docs/your-first-session): prove that a lesson survives a session. - [Troubleshooting](/docs/troubleshooting): find which step stopped working. - [CLI reference](/docs/cli-reference): commands, files, and expected results. - [Agent reference](/docs/agent-reference): a compact operating guide for your agent. --- # What is errata A local code and knowledge graph for reusing problems, causes, and verified fixes. Source: https://inerrata.ai/docs/what-is-errata Updated: 2026-09-25 errata keeps useful debugging knowledge across agent sessions. A daemon maintains a graph for your workspace; supported agent hooks deliver observations and tagged explanations. Future sessions can read relevant context and navigate from a problem to its cause and fix. ## The local loop 1. **Read context.** The daemon maintains `.errata/context.md`. Your agent reads it at task start and queries for more detail. 2. **Investigate.** Code indexing and hook events supply workspace context. Your agent states problems, causes, and fixes using inline capture instructions. 3. **Verify.** Record what failed and what passed after the change. Confirmation and refutation are evidence. 4. **Recall.** Search or walk the graph in a later session instead of repeating the investigation. The [first-session guide](/docs/your-first-session) checks each part. Capture depends on the integration and transcript format; installing an MCP server alone does not provide hook capture. ## Local graph and shared network | Surface | What it provides | | --- | --- | | Local daemon | Code structure, captured knowledge, context, shell and MCP access | | Errata Network | Hosted knowledge available to your authenticated identity and scope | | Console | Account, organization, credentials, installations, and sharing controls | Use the local graph without a cloud account. With a cloud connection, supported reads can blend local and collective results. Inspect provenance and scope: another project's lesson is evidence to evaluate, not proof about your code. ## Sharing is a separate choice Sync and telemetry start off on a fresh installation. Package contribution starts on but is gated by sync. Login and network reads are separate from upload consent. Contributions pass through scrubbing and generalization controls. Review your identity, target, and consent before sending content; see [Privacy and consent](/docs/privacy-and-consent). ## What a good lesson contains A useful entry says what failed, why it failed when known, what changed, and how the result was checked. The graph adds connections: a cause behind several symptoms, a fix addressing multiple problems, or a later result contradicting an earlier conclusion. Start with [Quickstart](/docs/quickstart), then keep the [Agent reference](/docs/agent-reference) handy. --- # Install the CLI Requirements, release channels, workspace files, and daemon lifecycle. Source: https://inerrata.ai/docs/install-the-cli Updated: 2026-09-25 The npm package is `@inerrata-corporation/errata`. Its executable is `errata`. Use the scoped package name when installing; `npx errata` names a different npm package. ## Requirements and installation Install Node.js 22 or newer, then: ~~~sh npm install -g @inerrata-corporation/errata errata --version errata --help ~~~ The published package is a bundled CLI with no npm postinstall step. A successful install does not verify your agent's hooks or cloud connection; use the [quickstart checks](/docs/quickstart). If `errata` is not found, reopen your terminal and check npm's global executable directory is on `PATH`. On Windows, `errata.cmd` can help distinguish a PowerShell script-policy issue from a missing installation. ## Release channels | Channel | Install | Use | | --- | --- | --- | | `latest` | `npm install -g @inerrata-corporation/errata` | Published release | | `dev` | `npm install -g @inerrata-corporation/errata@dev` | Development prerelease; may differ from the release | ~~~sh errata update --check errata update ~~~ Switch channels with `errata update --channel dev` or `errata update --channel latest`. After updating, restart the daemon: ~~~sh errata stop errata start ~~~ There is one daemon per machine. Stopping it affects every workspace it watches. Re-run `errata install-hooks ` after an agent upgrade or when hook formats change. ## Initialize a workspace From the project root: ~~~sh errata init --no-login ~~~ This detects the profile, registers the workspace, and installs supported harness configuration. Omit `--no-login` to sign in during setup. Use `--skip-hooks` to manage harness configuration yourself. | File | Purpose | | --- | --- | | `.errata/workspace.json` | Workspace identity and detected stack | | `.errata/castalia.db` | Local graph, created when the engine starts | | `.errata/context.md` | Live context; maintained as the daemon processes the workspace | | `.errata/report.html` | Snapshot generated by `errata report` | | Agent configuration | See [Connect your agent](/docs/connect-your-agent) | Keep `.errata/` runtime state out of version control. Review agent configuration and instruction-file changes before committing them. ## Run the daemon The local MCP connection starts the daemon automatically: when your client launches `errata mcp`, it checks for the singleton and starts it if absent. Usually you only need to verify it: ~~~sh errata status errata projects ~~~ For hooks-only or shell-only use, or if automatic startup failed, run `errata start`. It attaches the workspace to the existing singleton or starts it in the background. `init` alone does not launch the daemon, and the Codex hook installer adds no MCP entry. `errata dash` runs the multi-workspace daemon in the foreground; it does not launch a second copy while the singleton is running. The default hook port is `7891`. ## Sign in ~~~sh errata login ~~~ The default flow prints a verification URL and one-time code and opens the browser. Approve it in the Console, then inspect `errata whoami`. | Command | Purpose | | --- | --- | | `errata login --browser` | Browser authorization with a local loopback callback | | `errata login --device --installation ` | Device authorization for a Console installation | | `errata login --token ` | Install a Console-issued key; take care with shell history | | `errata doctor --json` | Diagnose installation, credentials, renewal, endpoint, and authentication | | `errata logout` | Clear local cloud credentials | Never place credentials in prompts or committed configuration. Use current client-specific instructions in [Console Connect](https://console.inerrata.ai). ## Cloud endpoint overrides `ERRATA_CLOUD_URL` overrides the gateway base URL. Release and development builds have different defaults; `errata status` prints the effective URL and channel. Changing a URL does not create credentials for that environment. Continue with [Your first session](/docs/your-first-session) or [CLI reference](/docs/cli-reference). --- # Connect your agent Choose local capture and code tools, or a direct connection to the hosted knowledge graph. Source: https://inerrata.ai/docs/connect-your-agent Updated: 2026-10-03 Local capture and hosted MCP are different connections. The daemon observes an initialized workspace through agent hooks. Hosted MCP queries the remote graph; adding it alone does not install local capture. Using Claude's cloud sessions? Follow [Claude Code on the web](/docs/claude-code-web) for hosted recall and a daemon setup inside the cloud VM. ## Local integrations Run the installer from the project root, then restart the agent session. | Agent | Command | Files written | Capability | | --- | --- | --- | --- | | Claude Code | `errata install-hooks claude` | `.claude/settings.json`, `.mcp.json`, managed instructions in `CLAUDE.md` | Hooks, context, local MCP | | Codex | `errata install-hooks codex` | `.codex/config.toml`; newer builds also write a relay under `.codex/hooks/` | Hooks and context; this command adds no MCP entry | | Cursor | `errata install-hooks cursor` | `.cursor/mcp.json` | Local MCP; this installer provides no hook capture | | OpenCode | `errata install-hooks opencode` | `.opencode/plugin/inerrata.js`, `opencode.json` | Plugin capture and local MCP | | Aider | `errata install-hooks aider` | Prints guidance | No automatic hook installation | File generation is the first check. Perform the [first-session capture check](/docs/your-first-session) with your installed agent version. Hook and transcript formats change; review installer warnings. ## Local MCP for other clients A client supporting stdio MCP can launch: ~~~sh errata mcp ~~~ Configure it to run **in your initialized project root**. This process speaks MCP over stdin/stdout; leave it under the MCP client's control. Starting local MCP also starts the background daemon if needed. Check `errata status` after connecting. With hooks or shell access alone, use `errata start` if the daemon is absent; the hooks themselves do not start it. For clients using the `mcpServers` JSON format: ~~~json { "mcpServers": { "errata": { "command": "errata", "args": ["mcp"] } } } ~~~ This is not a universal client configuration. Working-directory settings, config locations, and executable lookup vary. Use an absolute executable path if the agent cannot find `errata`. **Check:** reconnect and inspect the tool list. The local server declares names such as `errata.search` and `errata.burst`; clients may display underscores or a server prefix. Tools appearing does not prove hooks are delivering capture. ## Shell access Agents with shell access can query without MCP: ~~~sh errata search "a symbol or problem" errata burst "words from the problem" --local errata g problems errata g index ~~~ `errata g` evaluates a graph path and prints it. Prefer it to reading an arbitrary `.errata/g/...` file: those files need a materializing hook or a prior `errata g --materialize` call. ## Hosted MCP ~~~text https://mcp.inerrata.ai/mcp ~~~ Use [Console Connect](https://console.inerrata.ai) for a client-specific configuration and credential. Plan on authenticating for hosted access, including reads; anonymous availability is deployment policy, not an onboarding guarantee. A direct hosted connection does not read your repository or install the daemon. Local `errata.*` tools and hosted tools have different schemas; see [MCP tools](/docs/mcp-tools). Use `/mcp`. The old `/mcp/lite` and `/mcp/sse` transports are retired. ## Verify each connection 1. **Daemon:** `errata status` identifies the workspace and a running daemon. 2. **Local read:** search for a known symbol after indexing. 3. **Capture:** record a real tagged problem and find it with `errata g problems`. 4. **Cloud identity:** `errata whoami` shows the expected identity and contribution target. 5. **Hosted client:** list tools, then make an authenticated read with the advertised schema. Continue at the failing step in [Troubleshooting](/docs/troubleshooting). --- # Claude Code on the web Connect Claude's cloud sessions to errata for hosted recall, or run the daemon in the cloud VM for capture. Source: https://inerrata.ai/docs/claude-code-web Updated: 2026-10-03 Use this guide for cloud sessions at [claude.ai/code](https://claude.ai/code). Choose **hosted MCP** to query the shared graph, or **the daemon in the cloud VM** to capture lessons from the repository too. Installing errata on your laptop does not connect a separate cloud VM. The daemon walkthrough below is an integration recipe, not an end-to-end verified Claude cloud deployment. Complete the capture checks before relying on it for durable memory. ## Before you start Use a **single-repository session**. Anthropic documents repository hooks and `.mcp.json` support for that case; multi-repository sessions do not load those project settings. User-level configuration and locally installed plugins do not carry over. See [what carries over to the cloud](https://code.claude.com/docs/en/cloud-environments#what-carries-over-from-your-setup). | You want | Connection | What to verify | | --- | --- | --- | | Search existing shared knowledge | Hosted HTTP MCP | An authenticated read succeeds | | Capture problems and fixes from this checkout | Daemon and Claude hooks in the VM | A real lesson appears in the local graph | | Contribute captured lessons | Authenticated daemon with sync consent | Sync reports successful uploads | ## Hosted MCP for recall ### 1. Get a credential If you can, prefer the daemon in the cloud VM (see **Run the daemon for capture** below) and sign in with `errata login`: OAuth sign-in issues a renewable, revocable credential that the daemon stores owner-only, so no long-lived key has to sit in any settings file. For hosted MCP alone, open [Console Connect](https://console.inerrata.ai) and obtain a read-only key for the intended account and organization. Hosted access requires authentication under the current deployment policy. Set the key as an environment variable in the **cloud environment's settings** (the environment configuration UI), named `INERRATA_API_KEY`. Do not put it in `.claude/settings.json`, its `env` block, `.mcp.json`, or any other file in the repository or your synced dotfiles: those are committed, shared, and read by every tool in the session. Keep the real value out of Git, prompts, and setup scripts. Environment values are readable by people using that environment, so use an environment whose users are authorized to use this credential, and revoke the key in the console when you stop using it. See [Claude environment configuration](https://code.claude.com/docs/en/cloud-environments#configure-your-environment). ### 2. Add the project MCP configuration Merge this entry into `.mcp.json` at the repository root, preserving other servers: ~~~json { "mcpServers": { "inerrata": { "type": "http", "url": "https://mcp.inerrata.ai/mcp", "headers": { "Authorization": "Bearer ${INERRATA_API_KEY}" } } } } ~~~ Commit this file with the variable reference intact. Claude expands it from the session environment; do not replace it with the key. See [MCP variable expansion](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json). For this direct connection, allow `mcp.inerrata.ai` in the environment's network settings. Keep the default package-registry domains if you will also install the daemon. See [network access](https://code.claude.com/docs/en/cloud-environments#network-access). ### 3. Verify a read Start a new cloud session on the branch containing the configuration. Ask Claude to list the `inerrata` tools and search for a known topic using the returned tool schema. A connected server and a successful authenticated response establish recall access; an empty result can still be a successful query. Hosted MCP alone does not observe edits, capture inline tags, or create a local code graph. For those capabilities, continue below. The two connections can coexist: `inerrata` is hosted; `errata` is local to the VM. ## Run the daemon for capture This path needs Node.js 22 or newer, npm, Bash, and curl in the cloud VM. The [CLI installation guide](/docs/install-the-cli) covers versions and release channels. ### 1. Install the CLI in the cloud environment Add this to the environment's setup script after selecting Node.js 22 or newer: ~~~bash set -eu node -e 'if (Number(process.versions.node.split(".")[0]) < 22) throw new Error("errata requires Node.js 22 or newer")' npm install -g @inerrata-corporation/errata errata --version ~~~ Keep authentication and consent out of this script. The environment cache retains installed files, but not running processes. The MCP launcher below starts the daemon per session. See [environment caching](https://code.claude.com/docs/en/cloud-environments#environment-caching). ### 2. Prepare the repository hooks in Linux In a Linux or WSL checkout of the repository, with the CLI installed, run: ~~~sh errata init --no-login ~~~ Review the generated `.claude/settings.json`, `.mcp.json`, and managed instructions in `CLAUDE.md`. Preserve unrelated configuration. The installer adds hooks for context injection and capture, as described in [Connect your agent](/docs/connect-your-agent). Generate these files in Linux: Windows hook commands will not run in the cloud VM. The generated MCP entry also contains absolute paths from the installation machine; replace **only its `errata` entry** with the launcher in the next step before sharing it. These instructions target Linux cloud execution; keep a working Windows configuration appropriate to its own environment. Keep `.errata/` runtime state and credentials out of version control. `--no-login` skips sign-in; it does not clear existing credentials or consent. ### 3. Initialize each VM before starting local MCP Create `.claude/errata-cloud-mcp.sh` in the repository: ~~~bash #!/usr/bin/env bash set -eu cd "${CLAUDE_PROJECT_DIR:?Claude project directory is required}" # Preserve stdin and stdout for the MCP protocol. errata init --no-login --skip-hooks &2 exec errata mcp ~~~ Use this `errata` entry in `.mcp.json`, preserving other servers: ~~~json { "mcpServers": { "errata": { "command": "bash", "args": ["${CLAUDE_PROJECT_DIR:-.}/.claude/errata-cloud-mcp.sh"] } } } ~~~ The wrapper initializes this checkout before starting MCP. `--skip-hooks` preserves the committed hook configuration; `errata mcp` starts or attaches to the background daemon. It needs `errata` on the session's `PATH`, not an absolute path from another machine. Bash reads the script directly, so no executable-bit change is required. Launch from the repository root. The `:-.` fallback resolves the script there when the variable is absent during configuration expansion; Claude supplies `CLAUDE_PROJECT_DIR` to the spawned process. See [Claude's stdio MCP setup](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server). Commit the script, reviewed hooks, MCP configuration, and managed `CLAUDE.md` instructions. Start a cloud session from that branch. If MCP connects after the initial SessionStart hook, ask Claude to read `.errata/context.md` once the daemon is ready; later prompt hooks refresh context. ### 4. Verify local capture Ask Claude to run these commands in the repository: ~~~sh errata status errata privacy errata search "a real symbol from this repository" ~~~ Confirm the expected workspace and a running daemon. If local MCP did not start it, run `errata start`, inspect its result, and retry the MCP connection. Indexing may take time. Next, follow [Your first session](/docs/your-first-session) with a real issue. Ask Claude to read the maintained capture instructions, state the observed problem and fix, and verify the lesson in `errata g problems` and search. Installed hooks and visible tools do not prove capture. ## Enable contribution when ready Allow the production gateway `mcp.inerrata.ai` and the sign-in service `console.inerrata.ai` in the VM's network settings. In the running cloud session: ~~~sh errata login ~~~ Approve the verification URL and code in your own browser. Current builds use device-bridged sign-in by default; check `errata --help` for the installed version. For the explicit headless flow, obtain an installation UUID from Console Connect and run `errata login --device --installation `. Replace the placeholder. Do not use a localhost browser callback across machines. Check identity and consent before enabling uploads: ~~~sh errata whoami errata status errata privacy ~~~ Confirm the intended organization and project. If linking is missing or wrong, follow [Team workspaces](/docs/team-workspaces) and the installed `errata link` flow before contributing. Review [Privacy and consent](/docs/privacy-and-consent), then opt in if desired: ~~~sh errata consent sync on errata sync now errata doctor ~~~ Read the results. `consent-off`, rejected writes, or a pending outbox do not establish successful sharing. A bare API key, including `errata login --token`, supports reads but does not grant the daemon identity required for graph writes. ## Session lifetime and troubleshooting Treat the VM's graph and credentials as session-local. A fresh VM must initialize and authenticate again. Do not bake a logged-in daemon identity into a shared environment image. Before ending a session, sync intended contributions and inspect the outcome; unsynced local lessons can be lost when the VM is discarded. Cloud contributions are not a backup of the entire local graph. | Symptom | Check | | --- | --- | | Hosted tools are missing | Committed `.mcp.json`, selected branch, single-repository session, and MCP connection status | | Hosted reads return 401 or 403 | Credential, account access, and intended organization; never print the key to diagnose it | | Requests time out | Allowed domains and proxy errors; this is separate from authentication | | `errata` is not found | Setup-script result, Node version, and CLI availability on the MCP process's `PATH` | | Hooks reference `cmd` or Windows drive paths | Regenerate in Linux and use the portable MCP launcher above | | Tools work but no lessons appear | `errata status`, loaded hooks, transcript compatibility, and the first-session capture check | | Writes report `client_kind_denied` | Use daemon sign-in rather than an API key | | Writes report `consent_required` | Check local sync consent and the selected installation's approval in Console | | A new session has no old local lessons | Verify prior sync; each VM has its own local graph | For further checks, see [Troubleshooting](/docs/troubleshooting). If you want to keep the daemon on your own computer while using a browser interface, investigate [Claude Remote Control](https://code.claude.com/docs/en/remote-control), which runs the session on that computer. --- # Your first session Verify capture, resolution, and recall independently, with observable results. Source: https://inerrata.ai/docs/your-first-session Updated: 2026-09-25 A working loop has three observable outcomes: a problem appears, its resolution is recorded, and a later session retrieves it. Start after the [quickstart](/docs/quickstart), using a small real issue in a project you can edit. ## 1. Check the workspace ~~~sh errata status errata privacy ~~~ Confirm the workspace, running daemon, and intended consent settings. Start a fresh agent session so it loads the integration. Ask it to read `.errata/context.md` when present. ## 2. Have the agent state the problem The reliable conversation capture path uses **inline tags in the assistant's own prose**. Tool events and diagnostics provide context; a failing command followed by a passing command is not by itself proof that a problem and fix were linked. An agent investigating a real empty-input bug might write: ~~~text [!Empty input crashes the parser @ src/parser.ts:42] ~~~ Use the actual issue and file. Do not manufacture a failure to populate the graph. Tags pasted only into a user message or fenced code block are not the same as the agent reporting an observation. ## 3. Check capture before the fix After the agent's next supported hook or turn boundary: ~~~sh errata g problems errata search "words from the actual problem" ~~~ **Expected:** an open problem with a recognizable description and node ID. Capture is asynchronous. If absent, check hook delivery and transcript compatibility before assuming recall is broken. ## 4. Fix, verify, and record Have the agent make the change and run the relevant check. For a problem shown in context, cite its real handle: ~~~text The parser returns an empty result; the empty-input test passes. (fix:[shown-handle]) ~~~ For a problem the agent just stated, a descriptive fix tag is supported: ~~~text (fix: return an empty result before reading the first token) ~~~ Replace placeholders. State the verification result beside the fix, and claim resolution only when it worked. ~~~sh errata g problems errata search "words from the actual problem" errata report ~~~ **Expected:** the resolved count increases and search still finds the matching problem. `g problems` lists open problems by default, so the resolved entry can disappear from that list. The local MCP `errata.search` result includes the problem's `state`; the CLI search summary does not. Inspect the returned ID and its causal neighborhood separately; a resolved state alone does not prove a complete cause-and-fix chain exists. `report` writes a static HTML snapshot and prints the path; open that file yourself. It is not a continuously updating dashboard. ## 5. Retrieve it in a new session Start another session in the same project, read the current context, and query the actual problem: ~~~sh errata search "words from the actual problem" errata burst "words from the actual problem" --local ~~~ Use a returned node ID for an exact lookup if text selects a different seed. Context is a budgeted selection; it need not display every lesson automatically. Explicit retrieval is the stronger check. A useful lesson includes the symptom, cause when known, fix, and verification evidence. Check that it fits the current code. ## 6. Verify sharing separately Local capture says nothing about cloud upload. Review `errata whoami` and [consent](/docs/privacy-and-consent), then run `errata sync now` when you want sharing. Read each result: `consent-off` is an intentional skip, not an upload. A zero exit code does not prove any nodes reached the cloud. See [Troubleshooting](/docs/troubleshooting). --- # CLI reference Commands by task, expected results, and daemon lifecycle. Source: https://inerrata.ai/docs/cli-reference Updated: 2026-09-25 Run commands from the initialized project root. Replace angle-bracket placeholders before running them. `errata --help` describes your installed build. ## Setup and lifecycle | Command | Result | | --- | --- | | `errata --version` | Installed CLI version | | `errata init` | Profile and hook setup; prompts for login if needed | | `errata init --no-login` | Setup without requiring login | | `errata init --no-login --skip-hooks` | Profile setup without agent configuration | | `errata install-hooks ` | Configure `claude`, `codex`, `cursor`, `opencode`, or print `aider` guidance | | `errata start` | Manually start or attach to the singleton; useful without local MCP or when auto-start fails | | `errata mcp` | Serve local stdio MCP and automatically start the daemon if absent | | `errata status` | Workspace, graph, daemon, consent, cloud state | | `errata projects` | Initialized workspaces | | `errata stop` | Stop the daemon, affecting its other workspaces too | | `errata dash` | Run the singleton in the foreground | ## Read and inspect | Command | Result | | --- | --- | | `errata search ""` | Matching graph nodes | | `errata burst "" --local` | Local neighborhood and selected seed | | `errata burst ""` | Neighborhood; may include collective retrieval | | `errata locate ` | File and immediate symbols | | `errata neighbors --depth 2` | Graph neighbors | | `errata g index` | Graph path reference | | `errata g problems` | Problem states and IDs | | `errata g why/` | Causal and resolution neighborhood | | `errata g --materialize` | Write a result under `.errata/g/` | | `errata report` | Write an HTML snapshot and print its path | | `errata reindex --no-embed` | Refresh code indexing without code-node embedding | A fresh graph can contain code before lessons. Embedding availability affects semantic ranking. ## Identity and diagnostics | Command | Result | | --- | --- | | `errata login` | Browser-assisted sign-in | | `errata whoami` | Server-resolved identity, visibility, and contribution target | | `errata doctor --json` | Installation and cloud diagnostics; nonzero when required checks fail | | `errata profile` | Named installation profiles | | `errata profile use ` | Change active credential profile | | `errata use` | Available agent identities and current selection | | `errata link` | Explicit project-link workflow for the installed release | | `errata logout` | Clear local cloud credentials | A profile changes credentials, not the filesystem workspace. Check `status` for the project and `whoami` for the effective cloud target. Newer builds support workspace-to-profile bindings; inspect installed help before using them. ## Consent and sync ~~~sh errata privacy errata consent sync on errata consent telemetry off errata consent packages off errata sync now ~~~ Run only the toggles you intend. `errata consent all off` disables all three machine-level channels. Inspect sync results for uploads, rejections, and skips. ## Updates ~~~sh errata update --check errata update ~~~ Restart the daemon afterward. See [Install the CLI](/docs/install-the-cli) for channels and [Troubleshooting](/docs/troubleshooting) for diagnosis. --- # MCP tools Local and hosted tool names, input examples, and how to interpret results. Source: https://inerrata.ai/docs/mcp-tools Updated: 2026-09-25 Use your connected server's `tools/list` response as the authoritative schema. Local and hosted MCP expose different tools and argument names. Clients may normalize dots to underscores or add a prefix. ## Local daemon tools The local server is `errata mcp`, running in your initialized workspace. | Declared tool | Use | Example arguments | | --- | --- | --- | | `errata.search` | Find a problem, symbol, or description | `{"query":"parser","limit":10}` | | `errata.locate` | Inspect a file's symbols and imports | `{"path":"src/parser.ts"}` | | `errata.burst` | Rank a known node's neighborhood | `{"nodeId":"","maxHops":2,"limit":20}` | | `errata.why` | Read causal and resolution connections | `{"nodeId":""}` | | `errata.impact` | Inspect callers and dependents | `{"nodeId":""}` | | `errata.problems` | Inspect captured problems | `{}` | | `errata.health` | Inspect local graph health | `{}` | Start with `errata.search` when you have words; give `errata.burst` a returned `nodeId` or symbol `qname`. Local burst does not accept hosted burst's `query` argument. For clients without MCP, see [CLI reference](/docs/cli-reference). ## Hosted graph navigation Authenticate at `https://mcp.inerrata.ai/mcp` using the [connection guide](/docs/connect-your-agent). | Tool | Use | Example arguments | | --- | --- | --- | | `search` | Find entry points | `{"query":"parser fails on empty input"}` | | `burst` | Enter by text or inspect a seed | `{"query":"parser fails on empty input","context":"Investigating an empty-input crash"}` | | `explore` | Follow a promising branch | `{"seed_id":"","max_hops":3}` | | `trace` | Connect known nodes | `{"from_id":"","to_id":""}` | | `expand` | Read selected nodes in full | `{"ids":[""]}` | These are JSON **argument objects**, not shell commands. Replace placeholder IDs with returned IDs. `explore` uses `seed_id` and optionally `edge_filter`; it does not accept `direction`. Hosted `burst` supports `direction`. A first hosted traversal call can include `context` to receive `warmContext`. This is graph context; the MCP transport still performs its normal initialization handshake. ## Evidence and contribution Hosted `respond` records evidence such as confirmation or refutation. `contribute` and `learn` submit knowledge when your identity, scope, and consent permit it. Discover their full schemas before calling them and read consent or authorization responses. For local capture, follow the live context's inline instructions. Use a hosted write only when you intend to publish there. Legacy forum tools such as `ask`, `answer`, and `vote` are retired. ## Interpret results - Read provenance, scope, and full descriptions before applying a fix. - Local results can remain useful when collective retrieval is unavailable. Inspect `collectiveStatus` or CLI provenance labels. - An empty result does not establish that no solution exists. - A skipped or rejected write is not a successful contribution. - Confidence and ranking prioritize investigation; they do not guarantee correctness. Continue with [Graph navigation](/docs/graph-navigation) or [Agent reference](/docs/agent-reference). --- # Graph navigation Go from a symptom to a cause and verified fix using the right tool schema. Source: https://inerrata.ai/docs/graph-navigation Updated: 2026-09-25 Search finds a starting point. A graph walk shows what makes a result useful: what caused the failure, what fixed it, and the evidence behind that conclusion. ## Start locally ~~~sh errata search "words from the failure" errata burst "words from the failure" --local ~~~ Text can match several nodes. Inspect the selected seed and provenance; repeat with the exact returned node ID when needed. For that node's causal chain: ~~~sh errata g why/ ~~~ Replace the placeholder. `errata g index` lists graph paths. ## Walk the hosted graph Use these argument objects with the named hosted MCP tools. **burst** ~~~json { "query": "package builds locally but fails in CI", "context": "Investigating workspace dependency resolution" } ~~~ **explore** — select a real node ID from the burst: ~~~json { "seed_id": "", "max_hops": 3, "limit": 15 } ~~~ **expand** — read complete candidate descriptions: ~~~json { "ids": ["", ""] } ~~~ Use `trace` with `from_id` and `to_id` for a connecting path. These are hosted schemas; [MCP tools](/docs/mcp-tools) lists local equivalents. ## Decide whether it applies Compare versions, runtime, configuration, and failure mechanism with your workspace. Shared symptoms can have different causes. Run a small check that distinguishes them before changing code. After applying a fix, rerun the failing check and record the result. Confirm a prior when it held; refute it with the observation that contradicted it. Keep inconclusive results explicit. --- # Troubleshooting Find the failing step: installation, indexing, capture, recall, authentication, or sync. Source: https://inerrata.ai/docs/troubleshooting Updated: 2026-09-25 From the project root: ~~~sh errata --version errata status errata privacy ~~~ Local capture, cloud authentication, and uploads are separate checks. Verify the one you need before changing another. ## Init requires login In a non-interactive shell, plain `errata init` without credentials exits with a login hint. It may already have written workspace and hook files. For a local trial, rerun `errata init --no-login`. For hosted access, complete `errata login` interactively. `--no-login` does not reset credentials or consent. ## Daemon or graph missing Local MCP normally starts the daemon when the client connects. `init` and hooks alone do not. If `status` says it is absent, run `errata start`, then `errata status`. Check the workspace path and daemon state. Indexing takes time; search for a known function afterward. If needed, run `errata reindex --no-embed`. The default hook port is `7891`. If you intentionally run the foreground daemon on another port, reinstall hooks with `--port `. ## Tools appear but nothing is captured MCP connectivity verifies reads, not capture. Cursor's installer configures MCP only. For a capture-capable integration: 1. Re-run `errata install-hooks ` from the project root. 2. Restart the agent session. 3. Check that it reads live context and emits a real problem tag in its own prose. 4. Let its next hook or turn boundary occur. 5. Inspect `errata g problems`. Hook and transcript formats vary. The released `2.0.5` Codex installer uses tool-triggered capture; its output explains that a final turn without a tool call may wait for daemon replay. Newer builds use newer wiring. Check your installed version rather than assuming identical timing across clients. ## Search is empty or selects the wrong seed Check a known file or symbol first. If code is present but the problem is absent, debug capture. If the problem exists, use its exact ID with `errata burst`. `.errata/context.md` is a budgeted selection, not an inventory. An omitted problem can still be queried. New workspaces may have sparse relationships and prior knowledge. ## Embeddings fall back to hash vectors In the Windows onboarding check of npm `latest` `2.0.5`, search, capture, and recall worked, but `burst` reported an unavailable embedding model and fell back to `hash-v1` vectors. Semantic ranking runs at reduced fidelity in that mode. Record the package version and full warning when reporting this. Do not treat reduced-fidelity ranking as proof that setup failed or that the top result is reliable. ## Doctor fails while local queries work `doctor` checks cloud installation and credential health. Without a login or named installation profile it can exit nonzero while the local graph works. Use `status` and a local query for local readiness. For cloud access, read individual `doctor --json` checks, complete Console setup, and verify `whoami`. A parser-version warning is a compatibility lead, not proof of broken capture. ## Hosted requests fail Check the endpoint, environment, credential, and tool schema. Use Console Connect for current setup. A successful local query does not establish hosted access. Authentication failures need a valid identity for that deployment. Forbidden writes may involve scope or consent. Follow the specific error; do not enable every consent channel to troubleshoot a read. ## Sync uploads nothing Inspect `errata sync now` results: - `consent-off` means the lane was intentionally skipped. - No queued knowledge may mean nothing needs sending. - Failed or rejected uploads need their specific error inspected. - Local capture does not establish a cloud project or contribution target. Check `privacy` and `whoami` before changing upload settings. See [Team workspaces](/docs/team-workspaces). ## Report a reproducible issue Include OS, Node version, `errata --version`, agent version, command, expected result, and actual result. Add relevant diagnostic checks with credentials, personal paths, and identity details removed. The [source repository](https://gitlab.com/inerrata/inErrata) is on GitLab. Prefer a disposable reproduction; do not upload graph databases or raw transcripts as a diagnostic shortcut. --- # Agent reference Orient, query, verify, capture, and use the intended scope. Source: https://inerrata.ai/docs/agent-reference Updated: 2026-09-25 For an agent already connected to errata. The current `.errata/context.md` and connected server's schemas take precedence over examples here. ## Start a task 1. Work in the intended project root; read `.errata/context.md` if present. 2. Distinguish local tools from hosted tools using `tools/list`. 3. Query the concrete failure, symbol, or mechanism before repeating an investigation. 4. Follow causal links and read complete descriptions. 5. Check applicability against current code and tests. A compact context file is a starting point. Query when detail is missing. ## Choose a read path | Need | Local shell | Local MCP | Hosted MCP | | --- | --- | --- | --- | | Find by words | `errata search ""` | `errata.search` with `query` | `search` or `burst` with `query` | | Neighborhood | `errata burst "" --local` | `errata.burst` with `nodeId` | `burst` with `seed_id` | | Causes and fixes | `errata g why/` | `errata.why` with `nodeId` | `explore`, `trace` | | Full hosted nodes | Use hosted client | Inspect tool schema | `expand` with `ids` | | Check capture | `errata g problems` | `errata.problems` | Does not prove local capture | Clients may normalize local tool names. Do not pass hosted `seed_id` or `query` fields to local `errata.burst`. ## Record observations Put tags in your own prose, using real observations: | Situation | Syntax | | --- | --- | | Problem | `[!what failed @ src/file.ts:42]` | | Fix a shown problem | `(fix:[shown-handle])` | | Fix a newly stated problem | `(fix: what changed)` | | Confirm a prior | `(confirm:[shown-handle])` | | Refute a prior | `(refute:[shown-handle] what contradicted it)` | | Failed attempt | `(failed: what was tried and what happened)` | Replace placeholders. Follow live context's full grammar for causes, constraints, and investigation threads. A fix resolves a stated problem; routine completion is not a fix. State the check and result beside the conclusion. Distinguish hypotheses from observations. Do not fence tags as code when you intend capture. ## Verify before concluding - **Setup:** daemon state and tool discovery establish connectivity. - **Capture:** a matching node establishes the observation reached the graph. - **Resolution:** a recorded resolution and passing relevant check support the fix. - **Recall:** a later explicit query establishes retrieval. - **Sharing:** inspect upload outcome and destination separately. A zero exit code is not proof of upload. A highly ranked result is not proof of correctness. ## Use the intended scope Inspect `errata whoami` before a contribution when the target is uncertain. Machine sync consent, project controls, and direct hosted tool consent are separate. Switching credentials does not change the MCP process's working directory. Keep credentials and private content out of public-network queries. Network reads send queries off the machine even when background sync is disabled. ## Machine-readable copies Use [the docs index](/llms.txt), [the complete Markdown reference](/llms-full.txt), or each article's Markdown link. They are generated from the same articles as this site. For setup failures, see [Troubleshooting](/docs/troubleshooting). --- # Team workspaces Check identity, project placement, and sharing before sending team knowledge. Source: https://inerrata.ai/docs/team-workspaces Updated: 2026-10-03 The Console owns accounts, organization membership, installations, credentials, and project controls. The daemon owns the local workspace graph. A local workspace existing does not prove it is linked to the intended cloud project. ## Establish identity first Sign in to the intended organization in the [Console](https://console.inerrata.ai), then connect the CLI: ~~~sh errata login errata whoami errata status ~~~ Check the resolved identity, visibility, default contribution target, and local project. A login, a linked project, and upload consent are separate pieces of state. ## Link a project For an explicit link: ~~~sh errata link ~~~ The workflow depends on the installed release. In release `2.0.5`, this requires cloud credentials and resolves the project using its repository identity. Newer development builds open a Console approval flow to choose project placement and review consent. Read the CLI's prompts and verify the result. A project without a usable git remote needs an explicit locator or a supported corrective option; inspect `errata --help` for your build. After linking: ~~~sh errata whoami errata status errata privacy ~~~ A Console approval flow can apply the consent choices made there. Check the resulting settings before work begins. ## Connect a GitHub repository On builds with the Console approval flow, a repository is connected in two places, and only one of them is required: 1. **Optional, an admin, in the Console:** Projects → New project. Pick the repository from GitHub (the Console asks GitHub for repository-listing access the first time) or paste its git URL on the Git URL tab. This pre-places the project: team, visibility, and privacy choices. 2. **Each developer, in the clone:** run `errata init`. After sign-in it opens the link approval for this repository. If an admin already created the project, the approval starts from that project's choices; otherwise approving creates it. The approval records the project's sync and privacy choices, so no separate `errata consent sync on` is needed for a linked repository. Things that commonly get in the way: - **An organization's repositories are missing from the picker.** The organization may restrict third-party app access on GitHub. An owner approves the app in the organization's GitHub settings, or you paste the git URL instead. - **SSH host aliases.** Remotes such as `git@github-work:org/repo` (a `Host github-work` entry in `~/.ssh/config`) are resolved through `ssh -G` to the real host, so they match the same project as `git@github.com:org/repo`. - **Different capitalization.** On github.com, gitlab.com, bitbucket.org and codeberg.org, `Org/Repo` and `org/repo` resolve to the same project. - **Only owners and admins approve links.** Members ask an admin to create the project or approve the link. ## Use profiles deliberately Named installation profiles hold different credential contexts: ~~~sh errata profile errata profile use ~~~ Replace the placeholder with a configured profile name. A profile switch changes credentials, not the shell's current directory or the workspace opened by an MCP process. Newer builds can bind individual workspaces to named profiles. Use the installed CLI's help to check availability, and verify effective identity for the workspace rather than assuming a global profile switch moved every project. ## Verify contribution separately Review [Privacy and consent](/docs/privacy-and-consent), enable only intended channels, then inspect `errata sync now` results. A local problem appearing is not evidence of a successful team upload. Contribute the minimum reusable lesson. Public-network queries and writes should not contain organization-specific secrets, customer content, or proprietary source. Review scope and evidence before reusing another team's prior art. --- # Privacy and consent Local collection, cloud reads, contribution controls, and browser privacy choices. Source: https://inerrata.ai/docs/privacy-and-consent Updated: 2026-09-25 Local capture, cloud requests, and browser analytics have separate controls. Review the relevant control before enabling sharing. ## Daemon consent Run `errata privacy` to see the collection summary and this machine's current settings. It is a summary, not a preview of every outgoing payload. | Channel | Fresh-install default | Effect | | --- | --- | --- | | Sync | Off | Permits background knowledge uploads, subject to authentication and project controls | | Telemetry | Off | Permits product counts and metadata | | Packages | On, gated by sync | Permits package dependency contribution when sync is enabled | These settings are machine-level, not a fresh set for every repository. `errata init --no-login` skips required sign-in; it does not erase credentials or reset consent. ~~~sh errata privacy errata consent packages off errata consent sync on ~~~ The example opts out of package contribution before enabling knowledge sync. Run only the toggles you intend. `errata consent all off` disables all three channels; it does not delete content previously uploaded. ## Network reads and contribution scope Login and sync are separate. An authenticated network read sends its query to the hosted service even with sync off. A direct hosted MCP write has its own authorization and consent checks; the daemon's local sync toggle is not a universal control over other clients. Inspect `errata whoami` for identity, visibility, and the default contribution target. Review project placement and sharing controls in the Console. Newer project-link flows can apply the consent choices approved there, so inspect `privacy` again after linking. Uploads pass through scrubbing and generalization controls. Those controls do not replace choosing an appropriate scope or keeping secrets and sensitive source content out of contributions. See [Team workspaces](/docs/team-workspaces). ## Browser consent The public site starts from a strict opt-in posture. Essential cookies can run by default. Functional, analytics, and marketing storage require a visitor choice, and Global Privacy Control forces analytics and marketing off. ## Public-site cookies The site uses `cookie_consent_v1` to remember consent choices. The cookie is readable by client-side consent code, but it is not an identifier and does not contain an email address, user ID, or agent key. Cookie and subprocessor tables are generated from source-controlled registries, not from editable marketing copy. ## Analytics posture The live splash can use the same US PostHog project as Console, but only after explicit Analytics consent and only when the deployment kill switch is enabled. Until both conditions are true, the PostHog library is not downloaded and the site creates no PostHog storage. The splash records six fixed events: a consented route pageview, CTA clicks, story expand/collapse, successful command-copy actions, documentation views, and one visit summary when a visitor navigates away or leaves. It sends route paths without query strings, fixed placement/target and document identifiers, one of three command IDs, authentication state, and deployment environment. Acquisition origin is reduced to a bounded channel and known source label (for example direct, search/Google, LinkedIn, GitHub, an AI assistant, or an explicitly tagged outreach campaign). Unknown referring sites become `other`; the raw referrer URL and raw campaign parameters are never sent. An optional campaign link may carry a fixed audience hint such as investor, developer, technical buyer, agent builder, maintainer, security evaluator, or researcher. That hint describes the link, not a conclusion about the person who opened it. Observed behavior is reported separately as low engagement, engaged research, technical evaluation, or signup intent. Visit summaries include active seconds and elapsed seconds capped at one hour, a coarse duration bucket, maximum scroll-depth bucket, and a behavioral segment: low engagement, engaged researcher, technical evaluator, or signup intent. Active time pauses while the page is hidden and after thirty seconds without activity. The segment is derived only from page behavior such as docs views, command copies, story interaction, and signup actions; it does not claim a visitor's profession, employer, or identity. The splash never sends command text, graph content, search text, names, email addresses, user credentials, organization IDs, raw referrer URLs, or URL query strings. Consented visitors begin with PostHog's anonymous identifier. If an existing Console session is present, the analytics wrapper identifies the session using only its opaque user ID. Person profiles are limited to identified visitors. Session replay, autocapture, surveys, exception capture, performance capture, feature flags, dead-click capture, and marketing cookies are disabled. Withdrawing consent opts the browser out, resets PostHog identity and device state, and removes PostHog cookie, local-storage, and session-storage values while preserving the essential consent choice. ## Agent contribution consent MCP read tools can search public prior art without publishing new knowledge. Write-capable contribution workflows require explicit collection consent because they can publish reusable problem and solution metadata. ## GPC behavior When Global Privacy Control is detected, the site treats it as a do-not-sell/share signal, forces analytics and marketing off, and shows the detected state on the cookie settings page. Review or change your current browser choice on the [cookie settings page](/cookies). --- # Adaptive Confidence Decay Why old knowledge fades unless it keeps proving useful. Source: https://inerrata.ai/docs/confidence-decay Updated: 2026-07-05 Adaptive confidence decay keeps the graph honest when knowledge ages. Calendar time can reduce confidence, but repeated useful visits and validations slow that decay. The goal is not to hide old knowledge. The goal is to stop stale fixes from outranking newer, better-supported answers when the graph has stronger evidence. ## What affects confidence - Persistent memory can remain stable when it has earned durable status. - Long-term knowledge decays more slowly than short-term notes. - Frequently reused nodes retain confidence longer. - Accepted or validated answers receive stronger evidence than unreviewed content. ## Why this matters to agents Agents should treat confidence as a navigation signal, not an absolute truth claim. A low-confidence node may still be the only clue for a rare problem. A high-confidence node is worth reading first, but it still needs context. ## Related concepts - [Persistence scoring](/docs/persistence-scoring) - [Graph navigation workflow](/docs/graph-navigation) --- # GPC And Consent How Global Privacy Control interacts with the public site's strict opt-in cookie model. Source: https://inerrata.ai/docs/gpc-consent Updated: 2026-08-10 Global Privacy Control is a browser-level signal that a visitor does not want sale or sharing of personal information. The public site treats it as a strict privacy preference. ## Site behavior When GPC is detected, errata: - forces analytics off - forces marketing off - sets do-not-sell/share state - keeps essential cookies available - shows the detected state on `/cookies` This prevents the splash from importing PostHog, sending analytics requests, or creating PostHog browser storage, even when analytics is enabled for the deployment. ## Why honor it now? GPC is enforced at the same boundary as a visitor rejection. The browser signal, stored consent state, runtime gate, and legal disclosures therefore describe the same behavior. ## Related pages - [Cookie settings](/cookies) - [Privacy notice](/docs/privacy-and-consent) - [Cookie notice](/cookies) --- # Persistence Scoring How durable agent knowledge stays visible without pretending stale knowledge is fresh. Source: https://inerrata.ai/docs/persistence-scoring Updated: 2026-07-05 Persistence scoring is a ranking multiplier for knowledge that has kept proving useful. The score rewards reinforcement and recent validation, while allowing superseded or contradicted knowledge to fade. It is a multiplier, not a probability, so consumers can combine it with graph relevance, search rank, and confidence signals. The important property is monotonicity: validated knowledge should become easier to find, but no single signal should dominate the graph forever.