# User Guide ## Coordinator authentication and account-management upgrades An older coordinator can keep serving ordinary device-signed sync while optional auth reports `coordinator_auth_schema_upgrade_required`. The operator must pause auth writers and back up the coordinator database before running `codemem coordinator schema upgrade-auth --db-path coordinator.sqlite --json`. A D1 deployment applies the same cutover as numbered migration `0045`; `codemem coordinator schema upgrade-auth --export-sql` still prints that SQL for review. Never replay historical migrations on a deployment without a migration ledger. **Refresh profile**, **Unlink Google account**, and later same- or different-account linking need account management, which coordinators now install through their normal schema path. A SQLite coordinator installs it at startup when its auth schema is intact V2 or the earlier account extension. A D1 deployment gets it from numbered migrations `0046` and `0047`, after the `0045` authority cutover. Pause auth writers, drain pending attempts, back up the database and obtain separate approval before applying them, as the [deployment guide](cloudflare-coordinator-deployment.md#auth-schema-stages-0045-to-0047) describes. That section also covers a D1 database built from `schema.sql` or an exported install, which needs its migration ledger created and baselined first. The explicit commands remain for local files and exports: ```fish codemem coordinator schema upgrade-account --db-path coordinator.sqlite codemem coordinator schema upgrade-account --export-sql --json ``` Owner-resolution receipt storage is a separate, explicit extension that requires the current account-management schema first. After pausing auth writers, draining pending attempts, making a backup and obtaining separate approval, an operator can install it on an existing regular SQLite file: ```fish codemem coordinator schema upgrade-account --owner-resolution --db-path 'coordinator.sqlite' codemem coordinator schema upgrade-account --owner-resolution --export-sql --json ``` This mode installs empty, immutable receipt storage only: it does not resolve an owner, change access or provide a recovery UI. It rejects partial or unknown receipt schemas instead of repairing them. The command does not pause writers, drain attempts or make a backup; `--export-sql` opens no database and applies nothing, even when `CODEMEM_DB` is set. Export cannot be combined with a database path, and `--owner-resolution` cannot be combined with `--device-unlink`. For local apply, use a trusted maintenance account that owns the regular database file and its containing folder. Group/world-writable files or folders, unsafe parent locations and detected path or identity changes are rejected; inspect the file and parent ownership/permissions before retrying. The command does not change permissions. Keep all writers stopped and protect the database, SQLite companion files and parent paths from changes throughout maintenance. Canonical-path and identity rechecks detect observed replacements but do not prove which file descriptor SQLite opened or prevent a hostile same-account swap-and-restore race, including in WAL mode. ACL and platform limits require separate operator inspection; see the [local maintenance requirements](cloudflare-coordinator-deployment.md#optional-owner-resolution-receipt-storage). ## Explore the viewer The Feed shows captured memories in the same order used when packing context: the full title, narrative, then every fact. Cards open by default; use **Collapse memory** or **Expand memory** to hide or reveal content and supplemental provenance, and use search to narrow the list. The viewer checks status every five seconds while visible and focused. Health's detailed statistics refresh automatically no more than once every 30 seconds; opening Health, returning focus, or requesting a refresh loads them immediately. While the viewer is visible but unfocused, tab data stops polling and lightweight status checks slow to every 30 seconds. Hiding the tab or opening Settings pauses regular polling. Feed showing captured memories Optionally, use **Projects** to review project-level information. This example uses synthetic fixture data: its two Sharing review findings are informational, show no recipients, and do not show a successful sharing or sync flow. Projects view with fixture data All screenshots use invented data. Maintainers can reproduce them with the [screenshot guide](docs-screenshots.md). ## Check for updates Use the read-only release check to compare the running CLI with the latest npm release on its installed channel. Stable versions use `latest`; prereleases use `alpha`, `beta`, or `rc`: ```fish codemem update check codemem update check --refresh codemem update check --json ``` - Results are cached locally for six hours; `--refresh` bypasses a fresh cache. - `--json` prints one channel-aware status object and uses a non-zero exit code when no validated fresh or stale status is available. - Stale validated cache data remains clearly labeled and may provide guidance when the registry is unavailable. - This command never installs or executes an update. Release installation remains outside this read-only check. For a pnpm-global CLI, it reports the exact paired `pnpm add -g codemem@ @codemem/embeddings@` action. Path-based pnpm-global detection recognizes a canonical global virtual-store entry but does not prove mutable ownership. For a mise-managed CLI, it reports the exact global mise action; on Linux that action is `env ONNXRUNTIME_NODE_INSTALL=skip mise use -g npm:codemem@`. - `codemem update install` is the separate, fail-closed installer. Proven npm-global installations retain the 24-hour first-seen delay and install exact matching `codemem` and `@codemem/embeddings` versions from the public npm registry. For pnpm-global installations, it first runs bounded, neutral-directory `pnpm root -g`, `pnpm bin -g`, and `pnpm list -g --depth 0 --json` queries without a shell. It accepts only pnpm 9–11's `/node_modules` root or pnpm 12's `` root. The registered Codemem path and resolved entry must agree before it installs with explicit default and `@codemem` registry pins; it then verifies exact registered package versions and the exact launcher from the reported pnpm bin directory. It never runs a pnpm build-approval command; pnpm 9 still runs install scripts by default, while newer releases apply their configured build-script policy. Before a mise mutation, the installer reads bounded JSON from `mise ls --current` and `mise ls --global`, requires the active source to match a global source under the user's home directory, and requires its canonical install path to own the running CLI entrypoint. System, unresolved, and ambiguous custom sources are refused. It then runs `mise use -g npm:codemem@` with inherited environment, public default and `@codemem` registries, and Linux's CPU-only ONNX setting. Mise writes that exact release into the primary global config, which may move a declaration from a user `conf.d` or recognized user-level `~/.config/mise.toml` source to `config.toml`. Verification re-reads global state and requires `version` or `requested_version` to match the target, then uses `mise exec -- codemem --version` from outside the invoking project, avoiding stale `PATH` entries and project-local overrides. Both paths refresh release status and stay on the installed channel. It refuses npx, Docker, pinned, development, stale, cross-channel, downgrade, unsupported-channel, and unknown installations. Bare `codemem update` remains non-mutating. As with a manual npm install, npm runs the packages' installation scripts for native CPU dependencies. - Mise and pnpm-global installations are never eligible for plugin background auto-install. Changing either global installation requires the direct `codemem update install` command or the reported manual action. ## Start, stop, or restart the local service The local service runs the viewer, sync, raw-event ingestion, and maintenance. - `codemem service start` runs the local service in the background. - `codemem service start -f` or `codemem service start --foreground` keeps it in the foreground. - `codemem service stop` stops the local service, and `codemem service restart` restarts it in the background. - `codemem service status` returns the same local operational report as `codemem status`. - `codemem serve` remains a compatibility entrypoint. Existing `serve` invocations continue to work, and bare `codemem serve` runs the local service in the foreground. ## Viewer trust model - The viewer and its JSON APIs are designed for **localhost-only** use. - codemem relies on listener-based Host validation, loopback-origin checks, and local-process assumptions. It does not provide general-purpose viewer authentication. - Binding the viewer to `0.0.0.0`, putting it behind a reverse proxy, or exposing it through a tunnel can make local APIs reachable in ways the current trust model was not built for. - Treat the viewer as a local tool. If you must expose it beyond loopback, add your own auth and network restrictions first. - This warning applies to the viewer HTTP service, not the separate sync/coordinator listeners documented elsewhere. - Viewer JavaScript and Lucide icons are bundled locally, so loading icons does not contact a CDN. Fonts may still load from Google Fonts. ### Listener and embedding behavior For a loopback listener started by the local service, every viewer request must have a `Host` matching its request URL and the actual listening port, including when `--port 0` chooses an available port. This check runs before preflight and route handlers, including for requests without an `Origin` from CLI or hook callers. Missing, malformed, unexpected, or wrong-port authorities receive `403`. Forwarding headers do not override the listener or request authority. The allowed names follow the configured listener. `127.0.0.1` accepts that address and `localhost`, `::1` accepts `[::1]` and `localhost`, and `localhost` accepts all three. Other addresses in `127.0.0.0/8` and IPv4-mapped loopback IPv6 addresses accept their canonical address and `localhost`. Supported numeric listener shorthand such as `127.1` is canonicalized to `127.0.0.1`. Raw shorthand in a request's `Host` is rejected. Account routes retain their stricter listener, same-origin, and CSRF requirements. The CLI uses the actual bound IP to decide whether the listener is loopback, even when the configured hostname is a custom DNS name. When that name binds to loopback, allowed names include the configured name, the actual IP, and `localhost`. A configured `localhost` keeps its IPv4 and IPv6 aliases. Explicit non-loopback binds, including `0.0.0.0` and `::`, retain their existing behavior and require authentication and network restrictions outside the viewer. The loopback Host check does not make external exposure safe. Embedders calling `createApp` can supply `viewerAuthority.getListenerAddress` with the trusted configured `host`, actual bound `port`, and optional actual bound IP `address`. When supplied, `address` determines loopback classification and must be a valid IP address. Callbacks without it retain classification by configured host. The app otherwise uses `accountLink.getListenerAddress` when present. A configured callback that is unavailable, throws, or returns an invalid listener causes requests to receive `403`. Without either callback, the embedder owns authority validation at its HTTP boundary. ## Check local operational status `codemem status` is the local operational roll-up. It reports database readiness, viewer state, sync, maintenance, semantic indexing, raw-event ingestion, and the observer without changing configuration or stored data. ```fish codemem status codemem status --json codemem status --db-path ./codemem.sqlite --config ./codemem.json ``` - `status` answers whether codemem can do useful local work; `memory stats` reports database inventory and usage. - Collection is offline and local-only. It does not contact peers, coordinators, registries, update services, or non-loopback viewer hosts. - A missing database is reported without creating it. Existing databases are opened read-only. - With no viewer PID record, status probes the configured loopback viewer address; a malformed or non-loopback record reports `unknown` and is not fetched. - Warnings and errors appear in the bounded `attention` list. A collected report exits `0` even when `ok` is false; collection failures exit `1`, and usage errors exit `2`. - With `CODEMEM_EMBEDDING_DISABLED=1`, the semantic index reports `disabled` and adds no attention item: semantic search is off by choice and keyword search still works. - Terminal raw-event and observer failures affect `ok` for 24 hours; use `codemem diagnostics capture check` for the detailed reliability window. - Capture failure messages identify the known processing stage. `no_processable_input` means input preparation stopped before observer inference. Structural repair failures mean incomplete output could not be repaired, while output validation and filtering failures mean returned output produced no storable content. Technical details in Health diagnostics distinguish these stages and empty responses without including captured content. Unknown stages remain unspecified. These descriptions do not change retry or completion rules. - Observer batches in `failed` or `error` with a provider error code updated in the last 24 hours produce `observer.state: degraded` and an `observer_recent_failures` warning. Older rows remain in capture history without adding this warning. This count does not predict whether a batch will retry. - Status no longer labels database failures as observer `backoff`. It only probes viewer health, so it cannot confirm an active retry pause. The viewer's `/api/observer-status` reports the running worker's authentication-backoff timer. An `idle` CLI observer state means there are no recent recorded failures to report. An active runtime pause may still exist. - `codemem service status` replaces `codemem sync status` for operational health. - Use `codemem sync peers` for peer health and per-scope received/pending work, `codemem sync attempts` for recent passes, and `codemem sync doctor` for detailed sync diagnostics. - Use `codemem maintenance status` for background jobs and `codemem diagnostics capture status` for the ingestion backlog. ## Seeing UI changes - The viewer UI is built from `packages/ui/` and served by `packages/viewer-server/`. - Rebuild UI assets after frontend changes: `pnpm --filter @codemem/ui build`. - Restart the viewer after updates: `codemem service restart`. ## Getting started in the viewer - New browser profiles show a non-blocking checklist in Feed until its five jobs are completed or skipped: capture a memory, inspect its details, find it again, choose project scope, and check Settings or Health. - **Search memories** focuses the normal Feed search. **Find it again** completes after a successful search returns a visible result matching the query. - Steps complete from real data and actions rather than manual checkboxes. Completion and dismissal stay in versioned browser-local storage for that viewer profile. - **Skip getting started** hides the checklist without completing pending steps. Reopen it with **Show getting started** in Settings; completed steps remain completed. - Empty Feed messages distinguish no data, queued processing, paused capture, unavailable processing status, search with no matches, and filters with no matches. Use the action in the message to clear the active constraint or open the existing recovery surface. ## Settings modal - Open via the Settings button in the header. - Shows effective values (configured or default) to avoid blank/ambiguous fields. - Persists only changed settings on save (unchanged effective defaults are not rewritten to config). - Each editable field states which stage and scope it affects, when the change takes effect, and whether existing data is reprocessed. Fields show the viewer's current effective values; environment-managed values remain identified as overrides. - Uses task-oriented sections: `Connection`, `Processing`, and `Device Sync`. - Includes a `Show advanced controls` toggle for technical tuning fields (JSON headers, cache/timeout, tier-routing tuning, network overrides, and pack limits). - Connection/auth settings map to `claude_command`, `observer_runtime`, `observer_provider`, `observer_model`, `observer_base_url`, `observer_auth_source`, `observer_auth_file`, `observer_auth_command`, `observer_auth_timeout_ms`, `observer_auth_cache_ttl_s`, and `observer_headers`. - Processing settings include `raw_events_sweeper_interval_s` plus tiered observer routing controls for `observer_tier_routing_enabled`, `observer_simple_model`, `observer_simple_temperature`, `observer_reasoning_effort`, `observer_reasoning_summary`, `observer_rich_model`, `observer_rich_temperature`, `observer_rich_reasoning_effort`, `observer_rich_reasoning_summary`, and `observer_rich_max_output_tokens`. - Settings keeps connection choice and model choice together on the Connection tab. With tiered routing on, Simple and Rich are the main model fields; `observer_model` appears only as an optional advanced or already-configured fallback. With tiered routing off, `observer_model` is the main model field. - When you change the connection, provider, base model, or authentication method, Settings saves the displayed routing switch with the change so your Simple and Rich choices stay in effect. Unrelated saves leave automatic routing unchanged. - Settings outcomes honor `CODEMEM_OBSERVER_SIMPLE_PROVIDER` and `CODEMEM_OBSERVER_RICH_PROVIDER` over saved tier providers. Empty overrides clear the saved tier provider; temperature and base-model outcomes follow the resulting tier-provider fallback. - Observer environment overrides follow the runtime's parsing rules in Settings and save results: empty strings clear string fields, clear authentication commands/headers, set temperatures and output-token limits to zero, and disable boolean options. Empty or invalid integer and output-mode overrides, and empty sidecar-command overrides, retain saved values and do not mark those settings as environment-controlled. - When you have not made an explicit routing choice, codemem may enable tiered routing automatically for capability-safe paths such as OpenAI/Anthropic over `api_http` and Claude subscription usage over `claude_sidecar`. - The base-model outcome describes only requests that actually use that model: omitted routing/provider fields can resolve automatically, even when the form shows an unchecked routing switch. Explicit `false` disables routing; custom API endpoints and Codex sessions do not auto-enable it. Claude tiers use built-in model defaults. Codex tiers preserve explicit tier or base models; without either, they use `gpt-6-luna` for simple batches and `gpt-5.6-terra` for rich batches. - Explicit routing, model, and reasoning settings take precedence over built-in defaults where the selected transport supports them. OpenAI transport behavior has the simple-tier exception described below. - OpenAI tier routing defaults to `gpt-6-luna` for simple batches and `gpt-5.6-terra` for rich batches. - Rich routing defaults to 12,000 output tokens, while an explicit global `observer_max_output_tokens` setting or benchmark `--max-output-tokens` override applies to both tiers; `observer_rich_max_output_tokens` remains the highest-priority rich-only override. - Official OpenAI direct API tiers always use Responses and explicitly send reasoning effort `medium` unless you configure a different effort. OAuth `codex_consumer` requests also remain on Responses. `observer_openai_use_responses: false` is only a custom-gateway compatibility setting: it selects chat completions when `observer_base_url` explicitly points to an OpenAI-compatible gateway, and official OpenAI cannot opt out of Responses. Chat-completions requests do not report reasoning effort or summary because those controls are not transmitted. - When explicit tier routing keeps the same custom provider, both tiers preserve its `observer_openai_use_responses` setting. Set it to `true` for a Responses-only gateway; changing the tier provider does not carry the base provider's protocol choice to a different custom provider. - When tier routing uses a custom provider whose gateway rejects `temperature`, set `observer_temperature`, `observer_simple_temperature`, and `observer_rich_temperature` to JSON `null` in your config file to use model defaults without changing models, authentication, or protocol. Null tier temperatures inherit the global temperature; omitting the global setting still defaults to `0.2`, and numeric temperature environment overrides take precedence. - Observer output defaults to `legacy_xml` during the compatibility rollout. Set `observer_output_mode` or `CODEMEM_OBSERVER_OUTPUT_MODE` to `auto` to use a validated JSON envelope on official OpenAI Responses and direct Anthropic API-key paths while keeping sidecars, OAuth consumers, and unknown gateways on XML; use `json_schema` only when explicitly enabling a compatible custom gateway. - `json_schema` is an operator assertion that a custom OpenAI gateway configured through `observer_base_url`, or an Anthropic gateway configured through `CODEMEM_ANTHROPIC_ENDPOINT`, implements its provider's required JSON Schema contract. Codemem does not probe or infer this support from the gateway name. A refusal, truncation, missing response, invalid JSON, or locally invalid envelope fails closed and leaves existing raw-event retry behavior in control; Codemem does not reinterpret malformed constrained output as XML. - Codemem defines a provider-neutral forced `record_memories` tool using the same envelope and rejects anything other than one valid call. This transport is not enabled for any provider/runtime cell yet; sidecars, OAuth consumers, and other unproven paths stay on XML until executable contract tests exist. - XML will remain available until measured fallback use is negligible over a bounded rollout window and every supported access path has a tested contract. Removing the XML prompt, parser, and repair call requires a later compatibility-breaking release with release notes. - Legacy XML responses larger than 1,048,576 UTF-16 code units fail with `observer_output_too_large` before parsing, including repair responses. Codemem never truncates the output to keep only some memories; existing raw-event retry rules handle the failed call. This ceiling matches the SSE buffer limit and is separate from the observer transcript input budget. - OpenAI Responses requests omit temperature whenever active reasoning is configured because GPT-5.1+ accepts sampling controls only with reasoning effort `none`; replay and benchmark metadata report that temperature as not transmitted. - Configure reasoning shared by both OpenAI Responses tiers with the Processing tab's advanced `Shared reasoning defaults`, the global `observer_reasoning_effort` / `observer_reasoning_summary` file settings, or their `CODEMEM_OBSERVER_REASONING_*` environment variables. The `observer_rich_reasoning_*` settings remain optional rich-specific overrides. - The 2026-08-07 list rates are Luna at $1.00/M input and $6.00/M output versus GPT-5.4-mini at $0.75/M input and $4.50/M output; Terra and GPT-5.4 are both $2.50/M input and $15.00/M output. Measured extraction cost can rise by more than the list-rate difference when a model produces more output tokens. - If a selected tier path cannot honor the requested settings, codemem records the requested versus actual provider/model/runtime details and surfaces a visible fallback reason. - Sync settings can also be updated here (`sync_enabled`, `sync_host`, `sync_port`, `sync_interval_s`, `sync_mdns`). - Environment variables still override file values. - Connection mode and its outcome labels use the backend's resolved observer runtime, including automatic Claude/Codex session detection and normalized environment values. An explicit mode edit previews the saved choice unless an environment override controls it; reading Settings does not start a model request or authenticate a client. - Connection mode appears before Model provider in Settings. Local Claude and Codex sessions choose their own provider, so Settings hides the provider picker in those modes; the saved provider choice remains available when switching back to automatic mode. - The provider picker includes OpenAI, Anthropic, OpenCode, and configured custom providers. The running connection status hides the separate API-key and saved-sign-in inventory for local CLI sessions and OpenCode accounts; that inventory does not describe those connections. - Explicit choices are **OpenCode account**, **API key**, **Local Claude session**, and **Local Codex session**. API-key mode never uses a cached subscription sign-in or falls back to OpenCode. OpenCode-account mode uses only the running OpenCode service, regardless of which client captured the activity. Existing automatic connections keep their current rules until changed. An unavailable selected connection produces an observer error, not a switch to another account. - Blank model fields show backend defaults as placeholder text, including the selected connection's Simple and Rich models. Placeholders are not saved as explicit overrides. Settings highlights **Restart required** before saving only when edits affect settings the server cannot apply live; reverting those edits removes the warning. Observer changes apply live when supported, and save results remain authoritative if applying fails. - With automatic Connection mode, changing Authentication source previews the mode that will apply after saving, including switching from Codex to API for command/file authentication and back when restored. The config API returns `observer_runtime_by_auth_source` alongside `resolved_observer_runtime`; these safe previews use the same resolver and server-side dependencies as runtime selection. Unrelated edits preserve an omitted runtime setting rather than saving the displayed automatic mode. - Saving observer settings pauses new extraction, waits for already-dispatched work, and applies the new runtime and tier models without restarting the viewer when live apply is available. The save result reports whether changes are applying or a restart is required instead of showing restart guesses under each observer field. Settings shows the running observer separately from saved values while the change applies. If it cannot apply, captured events stay queued; reopen Settings and choose **Retry applying observer settings**. A listed model is not proof that the active provider account can use it; check observer diagnostics after a request. The connection choice is still global to this viewer database, not per Project. - Config resolution supports JSON and JSONC with this precedence: 1. explicit `CODEMEM_CONFIG` 2. workspace-scoped config derived from `CODEMEM_RUNTIME_ROOT` or `CODEMEM_WORKSPACE_ID` 3. legacy global config (`~/.config/codemem/config.json` or `~/.config/codemem/config.jsonc`) ## Extraction replay and benchmarks Proven delegated brief-only batches produce a context-only outcome instead of an observer evaluation. `diagnostics extraction replay --json` returns `status: "context_only"`, `code: "delegated_brief_context_only"`, `evaluated: false`, the batch/scenario IDs and an explanatory message, with exit status zero. `diagnostics extraction benchmark` continues past context-only batches and records each skipped iteration in `summary.contextOnlySkips`. `summary.contextOnlySkipped` counts those skips, while `summary.scheduledTotal` counts every scheduled batch/iteration. `summary.total`, `runs`, failure counts and quality, stability, output, cost and latency metrics cover actual observer attempts only; an all-context-only benchmark has no evaluated runs and null rates, rather than a quality pass. ## Observer auth configuration - Explicit runtime choices are `api_key`, `opencode_v2` (OpenCode account), `claude_sidecar`, and `codex_sidecar`. `api_http` remains supported for existing automatic setups. - Pi observer auto-derivation is API-key-only. `codemem setup` can derive unset `observer_provider` / `observer_model` from pi API-key providers (cheap-model-first) without copying secrets. `unconfigured (oauth-only)` is an auto-derivation status, not the state of every observer connection. Configure observer credentials or the connection separately, with provider or model overrides as needed. - `claude_sidecar` runs observer calls through the local Claude runtime (subscription/session auth) and does not require `ANTHROPIC_API_KEY`. - `claude_command` controls how `claude_sidecar` invokes Claude CLI (default `["claude"]`). - Wrapper example: `"claude_command": ["wrapper", "claude", "--"]` - `codex_sidecar` runs observer calls through the local Codex CLI login and does not require `OPENAI_API_KEY`. - OpenCode keeps refreshed provider credentials in its service database, not the legacy `auth.json` file. Select **OpenCode account** (`opencode_v2`) to use that connection, **API key** (`api_key`) for a separate API credential, or `codex_sidecar` for a local Codex CLI login. Codemem does not copy credentials out of OpenCode's database. - When observer authentication is missing or rejected, new raw-event batches stay visibly failed and retryable without spending flush attempts or advancing their stream cursor. The sweeper backs off until credentials become available. - An exhausted batch containing only trivial acknowledgement prompts can complete as a no-op even when it has more than two events. This requires the pipeline to have diagnosed no processable input, with no observer error. Finalization makes no model call, retains the raw events, and creates no memories. Larger ranges containing tools, assistant messages, substantive prompts, or unknown event shapes still require review. - Observer usage records include parsed observation counts, summary presence, counts after validation and capture routing, and the reason a summary was removed. These fields are retained when output disposition fails and on successful or skipped calls. They contain only counts, flags, and fixed reason codes. Older failures retain their original metadata. - Once authentication works again, the viewer automatically reviews retained raw events from older auth-missing failures whose cursors already advanced. It reconciles overlapping failed ranges, excludes completed ranges, and limits non-no-op recovery attempts to four per hour. Windows containing only assistant usage records complete without an observer call, a budget charge, or a new memory; the raw records remain intact. Recovered observations keep their original event time, remain private on this device, and do not replace later session summaries. Missing or invalid raw events stay failed for review instead of receiving invented facts. Set `CODEMEM_RAW_EVENTS_RECOVERY_ENABLED=0` on the viewer process to disable automatic historical recovery. - `codex_command` controls how `codex_sidecar` invokes Codex CLI (default `["codex"]`). - Default model selection: - `api_http`: `gpt-6-luna` for OpenAI unless `observer_model` is set. - `claude_sidecar`: `claude-4.5-haiku` unless `observer_model` is set. - `codex_sidecar`: `gpt-6-luna` unless `observer_model` is set; with tier routing enabled, the rich default is `gpt-5.6-terra` unless an explicit base or rich model is set. - Tier routing may pick different simple/rich models automatically when the current runtime/provider path is marked capability-safe. - Anthropic direct API calls use Anthropic's direct model IDs. codemem translates the common shorthand `claude-4.5-haiku` to `claude-haiku-4-5`; if you want a fixed snapshot, set a versioned model like `claude-haiku-4-5-20251001` directly. - If a configured `observer_model` is unsupported by a sidecar CLI, codemem retries once with that CLI's default model. - Supported auth sources: `auto`, `env`, `file`, `command`, `none`. - Endpoint and credential always come from the same source: vendor-scoped env/OAuth credentials (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENCODE_API_KEY`, `CODEX_API_KEY`, Anthropic OAuth) are only sent to the official provider endpoint. A custom `observer_base_url` or pi-derived gateway authenticates via `CODEMEM_OBSERVER_API_KEY`, `observer_api_key`, an OpenCode provider block's own key, or the endpoint-matched pi credential — never a vendor key. - `observer_auth_command` is argv and must be a JSON string array, not a space-separated string. - Config file form: `"observer_auth_command": ["iap-auth", "--audience", "example"]` - Env var form (`CODEMEM_OBSERVER_AUTH_COMMAND`): `'["iap-auth","--audience","example"]'` - Header templates can use `${auth.token}`, `${auth.type}`, and `${auth.source}`. - Settings are grouped into `Connection`, `Processing`, and `Device Sync` sections with shell-agnostic labels. - Queue settings include `raw_events_sweeper_interval_s` (seconds), which controls background pending-event drain cadence. - Tiered routing and simple/rich model choices live in the Connection tab. Processing retains background cadence and advanced request tuning; the optional base fallback is shown only when already configured or when advanced controls are visible. - Rich-tier OpenAI transport tuning remains visible in Processing. Official OpenAI tiers and OAuth `codex_consumer` always use Responses with reasoning effort `medium` by default. An explicit custom `observer_base_url` may use `observer_openai_use_responses: false` for chat-completions compatibility. Example command-token gateway config: ```json { "observer_provider": "your-gateway-provider", "observer_base_url": "https://gateway.example/v1", "observer_runtime": "api_http", "observer_auth_source": "command", "observer_auth_command": ["iap-auth", "--audience", "example"], "observer_auth_timeout_ms": 1500, "observer_auth_cache_ttl_s": 300, "observer_headers": { "Authorization": "Bearer ${auth.token}", "X-Auth-Source": "${auth.source}" } } ``` Header template variables: - `${auth.token}` - `${auth.type}` - `${auth.source}` Command/file token caching notes: - Successful `file`/`command` token resolutions are cached for `observer_auth_cache_ttl_s`. - Failed `file`/`command` resolutions are not cached (codemem clears stale cache and retries on the next call). ## Memory persistence - A session is created per ingest payload. - Observations and summaries persist when the observer emits meaningful content. - Low-signal observations are filtered before writing. ## Retrieve context for a task Use `memory context` when you want prompt-ready memory text for a task: ```fish codemem memory context 'Investigate the retry regression' codemem memory context 'Investigate the retry regression' --compact codemem memory context 'Investigate the retry regression' --json ``` The default output is plain text for a prompt. `--json` returns the structured pack response, including selection and size metrics. The command supports the full pack flag set, including project scope, working-set hints, limits, token budget, `--compact`, and `--compression-mode off|compact|ids`. Use `ids` only when the caller can retrieve the referenced observations. To inspect selection, run: ```fish codemem memory context trace 'Investigate the retry regression' codemem memory context trace 'Investigate the retry regression' --json ``` The trace uses the existing human and JSON trace output contracts. `memory pack` and root `pack` remain hidden compatibility commands for installed integrations and Pi callers. Report-style terminal output and the existing JSON response schema remain available there. ## Maintain project labels Project rename and normalization commands preview their changes by default. Add `--apply` only after reviewing the preview: ```fish codemem maintenance project rename 'old-project' 'new-project' codemem maintenance project rename 'old-project' 'new-project' --apply codemem maintenance project normalize codemem maintenance project normalize --apply ``` ## Automatic context injection - The OpenCode 1 plugin injects a memory pack next to the latest user message by default, keeping older prompt prefixes stable for provider prompt caches. - The OpenCode 2 entrypoint (beta integration, validated on the exact stable OpenCode 2.0.24 release) captures activity, manages lifecycle cleanup, and exposes manual `mem-status`, `mem-recent`, and `mem-stats` tools through `tool.transform` with `codemode: false`. On OpenCode 2.0.24, automatic recall runs through `session.context` when the latest user message has a non-empty ID. Each identified turn performs one fresh retrieval, while retries and tool continuations replay retained context; missing or blank identity skips safely. Auxiliary hooks remain isolated; see the [pinned contract](opencode-v2-contract.md). To stop the OpenCode 2 path or return to OpenCode 1.18.29+, follow [troubleshooting and rollback](plugin-reference.md#opencode-host-support-troubleshooting-and-rollback); no database migration is needed. - OpenCode 1 controls: - `CODEMEM_INJECT_CONTEXT=0` disables injection. - `CODEMEM_INJECT_SURFACE=system` uses the legacy OpenCode system-prompt injection surface. - `CODEMEM_INJECT_LIMIT` caps memory items (default 8). - `CODEMEM_INJECT_TOKEN_BUDGET` sets a positive approximate cap for OpenCode's complete wrapped injection (default 800). Unset, zero, negative, and invalid values use the default. OpenCode reserves its context prefix before requesting the pack; an override too small to leave a positive pack budget injects nothing because `0` means unlimited to generic pack calls. Accounting uses `ceil(characters / 4)`, not the provider tokenizer. - Scope revocation affects newly built packs immediately, but already-injected context in the current OpenCode session is not retroactively scrubbed; start a new session after revoking access if you need a clean prompt history. - Automatic message recall has an optional retained ceiling (`CODEMEM_INJECT_RETAINED_TOKEN_BUDGET`), off by default; set a positive integer such as `8000` to opt in. The per-pack default remains 800. Existing blocks are never truncated or rewritten, even after restart or when the ceiling is lowered. Actual removal from ordinary transform history releases allowance; compaction notification alone does not. The system surface remains per-pack only. See [lifecycle details](opencode-retained-recall.md). - Expand **Automatic recall (advanced)** in Health for local duplicate hit rates, estimated injection tokens avoided, and metadata gaps. The panel covers at most the newest 1,000 eligible retrieval attempts in the last 30 days across all projects, with current memory visibility enforced. Older clients or failed capture leave savings unknown, not zero; the estimates are not provider costs. - Retrieval, skipped injection after attempt creation, current-request cache reuse, and handoff status are recorded in the local evidence ledger. A positive token budget too small for the context prefix is rejected before an evidence-ledger attempt is recorded and reported once through the plugin's warning logs. Records contain bounded memory identity, diagnostic codes, and safe repository-relative working-set paths, never prompt text, pack text, memory content, or absolute paths. Reattaching historical cached context does not create attempts, and ledger failures do not block injection. If post-restart identity repair fails, usable fallback context is still injected without assigning its delivery to a stale or failed ledger attempt. - Reuse savings estimate discovery work versus pack read size. - Automatic message recall deduplicates unchanged retained item fingerprints. Narrow continuation prompts skip injection only after retrieval confirms no changed facts and file/tool context is unchanged. When local plugin logging is enabled, `inject.recall` JSON separates new and retained estimated tokens, duplicate counts, and bounded reasons without content or identifiers. See [lifecycle and evaluation details](opencode-retained-recall.md); these estimates do not measure answer usefulness or provider token usage. ### Pi Pi captures session, message, and tool activity through `@codemem/pi-extension`. Automatic recall appends a block to the latest user message of the request copy. Older messages replay that process's in-memory decision only; `session_start` and a restart clear it, and the next turn fetches again. The system prompt and saved transcript are not changed. A successful built-in `read` can also attach file context to that tool result. - Pi 1.1.0 or newer, below 2.0, is required; upgrade an older host with `pi update`. - `CODEMEM_PI_INJECT_PROMPTS=0` disables prompt recall. If that variable is unset, `CODEMEM_INJECT_CONTEXT=0` does the same for Pi prompts. - `CODEMEM_PI_FILE_CONTEXT=0` disables read-file context. It is independent of prompt recall. - `pi.tools_mode` / `CODEMEM_PI_TOOLS_MODE`: `native` (default) registers 15 native tools; `mcp-adapter` skips native registration so an independently configured MCP surface can supply them; the codemem MCP server's 15 tools include `memory_session_search`, so that surface keeps Pi session search. Use one surface. - Pre-install history is not imported automatically. Run `codemem session import` to backfill it. `--extract` also runs the observer over pending Pi sessions, so model cost scales with the backlog; without it, this command does not run extraction. Import `--json` also reports whether extraction was requested, flushed-event and failed/pending-session counts, and the first extraction error. Incomplete extraction exits with code 1 while keeping imported events. - Search stored user/assistant text with `codemem session search `. `--json` returns the shared core response, including `query_truncated` when matching uses a bounded prefix of the query. Human output warns about partial matching even with zero results; shorten the query and retry. See [session search and history import](plugin-reference.md#session-search-and-history-import) for flags and import safety limits. Settings: [Pi extension](plugin-reference.md#pi-extension) and the [package configuration table](../packages/pi-extension/README.md#configuration). ### Usage metric semantics `codemem memory stats --json` and the viewer usage API identify token units and provenance. Pack rows are estimates of tokens injected into context. Observer rows use provider-reported input tokens (`tokens_read`) and output tokens (`tokens_written`) across every attempted observer call; transports without usage telemetry record those values as unavailable instead of estimating them. Observer rows written before this provenance marker used UTF-16 text lengths, not tokens. Codemem keeps those rows for audit but excludes their values from token aggregates and reports them through `legacy_text_length_count`; the original token counts cannot be recovered. Health’s Injected, Savings, and Reduction cards use pack estimates only, so observer model usage is not mixed into pack-size metrics. The viewer may cache global usage totals, but it checks recent memory packs against current permissions on every request. If a pack references hidden, missing, deleted, or invalid memories, it keeps permitted memory IDs and omits other metadata, including summaries and snippets. Fully visible packs retain their metadata. ## Retrieval attribution diagnostics Use `codemem memory stats --attribution` to inspect local, bounded, observational retrieval diagnostics: ```fish codemem memory stats --attribution codemem memory stats --attribution --json ``` - The report covers the 50 most recent retrieval attempts and at most 100 linked assessments; counts are a recent bounded window, not lifetime totals. - It includes lifecycle completeness: requested, selected, and handed-off attempts and exposures. - Evidence completeness distinguishes validated assessed attempts with known or unknown results (insufficient evidence) from unassessed attempts (no valid assessment row was inspected). - Invalid rows failed current fail-closed validation. Omitted-by-limit rows exceeded the assessment cap; affected attempts are reported with indeterminate status or incomplete assessment details instead of inferred from unvalidated raw rows. - Findings include counts of stale and harmful assessments. - It contains no raw transcript, per-memory ROI, or composite productivity score. It makes no causal claim absent a preregistered randomized contrast. ## Semantic recall Codemem combines FTS5 keyword retrieval with sqlite-vec semantic retrieval. Embeddings are written for new memories, and semantic ranking for a file-backed database runs in one local worker. `memory_search` and `memory_pack` keep their existing result formats; packs can combine keyword and semantic evidence. ### Upgrade an existing database The first opening of an existing file-backed database with embeddings enabled upgrades the vector layout automatically, before it serves requests. The upgrade copies vectors in one transaction and preserves existing memories and vector identities. It may take time and requires temporary disk space roughly comparable to the vector tables. 1. Stop or close every other Codemem writer using that database. 2. Start the updated Codemem runtime and open the database normally. 3. Wait for the initial open to finish before sending requests. If the database is busy, Codemem fails without changing the older layout. Close the other writers and reopen it. A failed upgrade rolls back, so the legacy layout remains usable. Do not remove vector tables or try to downgrade the database manually. After the upgrade, update every process that writes the database before using semantic retrieval. Older runtimes can still use keyword access only when embeddings are disabled; they cannot use semantic features with the upgraded layout. There is no automatic downgrade. ### Use keyword-only retrieval Set `CODEMEM_EMBEDDING_DISABLED=1` before starting Codemem to skip the upgrade and semantic retrieval. Keyword search continues to work. This is useful when you need to keep an older runtime on the database temporarily. Semantic results use only validated vectors. A model change or rebuild can temporarily return keyword-only results while Codemem finishes validation. After that audit, valid rows remain searchable even when other stored vectors need repair. Cleanup removes vectors with invalid numeric values or unusable metadata, without changing source memories. Rows from undeclared models remain available for a later model transition. Use `codemem maintenance embeddings --dry-run`, then `codemem maintenance embeddings`, to backfill missing vectors. For applications that create a `MemoryStore`, close an asynchronous semantic store before closing its database: ```ts const store = new MemoryStore("./codemem.sqlite"); try { // Use the store. } finally { await store.closeAsync(); } ``` `closeAsync()` waits for queued semantic work and background vector work before SQLite closes. `close()` remains synchronous when no semantic or audit work needs draining; it cancels unfinished best-effort vector writes. Use `closeAsync()` to flush those writes. A store that owns a semantic worker requires `closeAsync()`. ## Distill recurring lessons Use `codemem memory distill` to find lessons that keep showing up in memory history. ```fish codemem memory distill --explain codemem memory distill --all-projects --json codemem memory distill --no-judge # skip the observer-model worthiness judgment codemem memory distill --draft # draft an AGENTS.md rule for the top candidate + diff codemem memory distill --draft --apply # write it after confirmation ``` Candidate mining is deterministic and review-first: - `project` candidates target that repo's `AGENTS.md`; `user` candidates target global/user context. - Without `--draft`, the command only emits ranked candidates and evidence (`draft_text` is null). - Candidates are judged by default: one short observer-model call per candidate drops clusters that are recurring *activity* (release/CI status, review passes with no findings, context lookups) rather than recurring *lessons* — recurrence alone cannot tell these apart. Unjudgeable candidates are kept and marked `unjudged`. When no observer model is configured, the command falls back to unjudged output with a warning; `--no-judge` skips the judgment (and its model calls) entirely. - `--draft` uses your configured observer model to write one concise rule for the top candidate and prints a unified diff; it does not write anything. - `--apply` (implies `--draft`) writes the rule into a codemem-managed `## Distilled lessons` block, delimited by `` markers so every distilled edit stays in one place. It prompts before writing (except with `--json`, which is non-interactive — there `--apply` itself is the explicit consent and the write happens immediately) and appends only (never deletes your existing notes). ## Projects, Sharing, Devices, and Health For the short Project-first walkthrough, see [Share Projects and add devices](sharing-guide.md). ### Link a Google account The **My Account** card at the top of **Sharing** is separate from sharing controls. When the coordinator confirms that the Google account is linked to the current Codemem Identity, the verified Google name and email identify that same Identity in **Sharing → Identities** and in Team member lists. The local Identity ID remains under **Technical details**. This changes only how the Identity is presented; it does not rename or replace the stored Identity or change its devices, Teams, or Project access. Identity, device, and coordinator information is collapsed under **Technical details**; **Link Google account** is hidden when the coordinator reports a linked account, while **Check status** remains available. This card is available from the current source checkout or a release that includes My Account. It is not available in every installed version. Account status is per coordinator. If more than one coordinator group is configured, the Viewer checks status with the first group whose enrollment the coordinator accepts. To use a specific group instead, choose it under **Technical details**. The card does not accept an arbitrary profile, URL, or identifier. To link an account: 1. Open the Viewer on the device whose existing Identity you want to link, then choose **Link Google account**. 2. Complete Google sign-in in the browser window that opens. If the browser blocks the window, choose **Open Google sign-in** to open it on the same computer. 3. Return to the Viewer. Status updates automatically while linking; after the attempt finishes, **Check status** is available to verify the result. The coordinator's signed account status is the completion record. The card starts Google sign-in only when you choose **Link Google account**. Do not paste a private sign-in link into another browser or computer. The Viewer and browser must run on the same computer. Account linking requires the Viewer to bind to `localhost`, `127.0.0.1`, or `::1`; wildcard bindings do not expose the account API. An SSH tunnel can show Viewer status on another computer, but its loopback callback reaches that other computer, so Viewer linking does not work there. Do not copy private sign-in links. To link a device that has no browser, such as a server reached over SSH or a NAS container, use [headless linking](#link-a-device-without-a-browser) instead. The coordinator must support the signed account-status endpoint and have Google browser authentication enabled. A self-hosted operator performs any required coordinator upgrade and deployment separately; this client flow does not change coordinator schema. An older coordinator that returns unsupported is not asking for Google; the card cannot start linking against it. An unavailable or unknown status does not mean the Identity is unlinked—check status again. For an active enrolled device with a current Identity that matches coordinator eligibility, choose **Link Google account**, complete Google sign-in, and return to the Viewer. This normal flow needs no administrator credential, review command, enrollment, claim checkbox, or new Identity. Linking applies only to the current Identity. It does not change device keys, enrollment, grants, or history, and it cannot authorize another device. If the coordinator cannot link the eligible context, ask its operator; do not reset a profile, create an Identity, or use an administrator credential in the Viewer. Account linking is optional. It does not grant Team or Project access, move an Identity, merge accounts, reassign devices, transfer history, or change existing device keys or enrollments. At one coordinator, one Google account links to one existing Identity, and each Identity links to one account. Choose an account that follows your work policy. When the coordinator advertises account-management capability, a linked account can show **Refresh profile** and **Unlink Google account**. **Check status** only reads the signed coordinator result; it does not refresh a profile. Refresh requires fresh Google proof and has no extra confirmation. Unlink asks once in the Viewer and uses this device’s existing authorization; it does not open Google sign-in or another tab. Cancel leaves the account unchanged. Confirming ends the current link, its browser sessions and display profile, while preserving your Identity, device keys, history, memberships and access grants. To link again—whether to the same or another Google account—choose **Link Google account** (or **Sign in with Google**) and complete Google verification. Unlinking never switches this device to another Identity. If this device runs as a different Identity than the account owner the coordinator confirmed, the card names both and does not show the owner's Google profile. Refresh and Unlink work only on a device that runs as the account owner; **Sign in with Google** can switch this device to the owner (see below). Google account details (name, email, and picture) appear only on a device that holds its own proof for the Identity: the device that linked the account, one with its own controller attestation, or one that signed in with Google. Another device of the same Identity shows **Linked on another device** without those details, and offers **Sign in with Google** so it can refresh or unlink the account too. If these controls are absent, management is not currently available for this device and coordinator. Check status before retrying; do not use an external Google workaround or an operator credential. If the coordinator reports an Identity mismatch, conflict, revoked link, or required review, ask the coordinator operator to resolve it; the card does not merge or repair identities. Use **Cancel linking** to ask to stop an in-progress request. Status updates continue if the cancellation request fails. An unknown outcome can still finish later; use **Check status** when it becomes available. If the Viewer configuration changes during an attempt, **Cancel previous link** requests cancellation for the original Identity; it does not attach that attempt to the newly displayed Identity. Transient status failures retry until the attempt's deadline without reopening sign-in. After that deadline, use the available cancellation and status controls to check the outcome. Returning to the tab or refreshing resumes an in-progress operation. Restarting the Viewer loses its in-memory operation, but **Check status** still reads the signed coordinator result. The linking request has a ten-minute deadline. Local capture, reading, and direct sync continue without Google, and this optional link does not add a required-auth policy. ### Link a device without a browser A device with no browser, such as a NAS, a Docker container, or a server you reach over SSH, can link its existing Identity with a short code that you enter on any other computer. The coordinator must have migration 0043 applied; otherwise the command reports that the coordinator does not support headless linking and that its operator needs to apply migration 0043 and deploy. Run the command in an interactive terminal on that device. In a container, use `docker exec -it` so the command can prompt you: ```fish docker exec -it codemem coordinator account link --headless ``` On a host you reach over SSH, run `codemem coordinator account link --headless` in the SSH session. The command refuses to run without a terminal on both stdin and stderr, and it does not support `--json`. `--headless` cannot be combined with `--loopback-host`, and the command never switches to headless mode by itself. The terminal shows: ```text On any computer, open https://coordinator.example.com/auth/link/device and enter code: BCDF-GHJK This device: · key SHA256:1a2b3c4d...5e6f7a8b The code expires at 3:42 PM PST. ``` In the browser, enter the code and sign in with Google. The browser then shows the Google account, the Identity and group the link applies to, and the device key fingerprint. Continue only if you started the command yourself within the last ten minutes and the fingerprint matches the terminal. The browser gets no Codemem session from this flow. It tells you to return to the terminal. Back on the device, the terminal names the account that approved the link, for example `Approved in the browser by ada@example.com (verified by Google)`, and asks `Link Identity to this Google account? (y/N)`. If Google shared no email, the terminal shows the account's display name, or "an account with no email", and you must type `link` to continue. Any other answer, Ctrl-C, or reaching the code's expiry cancels the request. The command prints `Linked.` when the coordinator confirms the link. While it waits, the command polls the coordinator no more often than the coordinator asks, slows down when the coordinator rate-limits it, and backs off when the network fails. The same Identity checks as the desktop command apply: an Identity that is already linked is left alone, and conflicts, revoked links, and required reviews stop the command with the usual messages. A Google account linked this way cannot be used to move another device into its Identity with **Sign in with Google**, or to enroll a new device as its owner. The browser says "Link this account from a browser first." This limits the damage if someone tricks a person into approving their device's code. If you linked your own device this way and later want to move or enroll devices into that Identity, link the account once from a browser. On a device that already runs as that Identity and has a browser, disconnect the account (**Unlink Google account** in the Viewer), then choose **Link Google account** on that same desktop. Refreshing the profile keeps the headless link and does not clear the block. If you approved a code that you did not start yourself, your Google account is now linked to someone else's Identity. Do not use that account to sign in or move devices, and contact your coordinator operator. You cannot unlink it yourself, because only a device in that other Identity can disconnect it, and the coordinator does not let the same Google account link to a different Identity later. Moving the account to another Identity has no self-service path. ### Sign in with Google on a device Starting in 0.47.0, a Viewer whose coordinator supports it shows **Sign in with Google** instead of **Link Google account**. Signing in sets this device's Identity from your Google account: - **The account is linked to another Identity.** The browser shows both Identities and the Teams this device would stop syncing with, and asks you to confirm. This device then switches to your account's Identity. It gets only the Teams and Projects that Identity already has; memberships and Project grants never move, and memories keep their original author. - **The account is linked to this device's Identity on another device.** Confirming gives this device its own proof, so it can refresh or unlink the account too. Its Identity stays the same. - **The account isn't linked yet.** Choose **Link this account** to link it to this device's current Identity, as in [Link a Google account](#link-a-google-account). Each device can switch or bind this way only once. If the result is unclear, for example after a network failure, restart the Viewer and check status before trying again; the Viewer resolves an unfinished switch by reading coordinator status. Devices that hand out Project access learn about the switch from the coordinator once they run 0.47.0, and keep sharing whatever the new Identity is allowed to see. ### Repair a reviewed account owner This recovery workflow first shipped in **0.47.0-beta.4**. It works only against a coordinator that its operator has upgraded for owner resolution, and that coordinator upgrade and live rollout are separate operator steps. When available, **Review account ownership** appears in **My Account** only for a review-required, conflicting, or mismatched account state. It does not use the computer username or create a new Identity. This state often follows an upgrade from the older model, where each install created its own Identity. Each machine then claimed your other devices under its own ID, so different Teams can record different owners for the same device. With operator access, the owner list suggests every Identity that a Team records for this device and names the groups that record it. Pick the Identity that is linked to your Google account. If no owner is recorded, the dialog opens **Advanced: enter an existing owner ID** so you can enter that Identity ID directly. 1. Choose **Review account ownership**, select the already-linked existing owner and each group to review, then choose **Preview account ownership**. 2. Inspect every retained assignment and each group result. The preview keeps the full retained history. Reviewed weak labels, including Project actor labels, are display-only account-owner evidence, not device assignments or sharing access. 3. An operator-configured Viewer shows an unchecked acknowledgement by default. Check it only after reviewing the current preview, then choose **Confirm account ownership**. While any selected group is blocked, the acknowledgement stays disabled and the dialog names the blocked groups. Clear those groups or fix them, then preview again. The coordinator requires a fresh scoped review and confirmation; an ordinary controller-only approval is not enough. 4. Read each group result separately. **Check review status** is read-only and never applies a review again. For a missing, unknown, stale, wrong-profile, wrong-group, or wrong-target result, request a fresh preview and acknowledgement instead of retrying an old confirmation. A new preview replaces the previous results. A preview expires after 5 minutes, and the Viewer runs one ownership request at a time, so another tab waits while one confirms. When **Confirm account ownership** is disabled, the dialog says why below the button. Owner reviews wait at least 10 seconds for the coordinator, or longer when `sync_coordinator_timeout_s` is higher. Confirming saves the owner under `~/.codemem/account-owner-associations`. Codemem refuses to save it while `~/.codemem` is writable by your group or other users, and the dialog shows the command that fixes it, usually `chmod go-w ~/.codemem`. Some managed workspaces create that folder group-writable. The confirmed account owner is displayed separately from the unchanged Memory author and sharing Identity. The workflow retains old records, memories, keys, configuration, services, sharing grants, and their full history. It is not an actor merge, reset, Google-account move, new Identity, Team/Project permission change, or future-policy setup. Existing Team and Project delivery or reconciliation warnings still need their own sharing review. When the recovered owner differs from the current Identity, **My Account** says which Identity this device runs as and who owns the account. It does not show the owner's Google name, email, or picture, because this device never signed in as the owner. The owner projection does not enable linking, profile refresh, unlink, disconnect, or permission changes. If the recovered owner has a Google link, choose **Sign in with Google** to run this device as that Identity. This starts a separate sign-in, not another owner review. The coordinator checks the device, and Google sign-in and your confirmation are still required before the device switches. Existing memories keep their original author. When the recovered owner is already the current Identity, **My Account** uses the device's normal signed account status. If the coordinator offers **Connect this device**, complete Google sign-in and browser confirmation to attach the existing device key to that same Identity. This keeps the current Identity and sharing permissions. The saved owner review alone does not enable account management. Without an operator-configured Viewer, use the dialog's **Copy support request** and send the noncredential request only to a trusted coordinator operator, never a public issue. It includes private coordinator, device, and group identifiers but no admin secret or private key. Paste only that operator's noncredential JSON reply and choose **Verify operator reply**. The local backend checks fresh device-signed receipt and owner proof before retaining an association; a verified import can restore that local association while immutable history remains unchanged. Use the local Viewer with your browser for the supported requester flow; do not bypass its loopback, Host/Origin, or CSRF protections with ad hoc console or SSH instructions. ### Choose a sharing flow The normal flow is **Projects → Sharing → Devices → Health**, not manual pairing. Inside **Sharing**, open **Teams** when you want to manage ongoing Team membership and inherited Project access: - **Team onboarding** — create or join a Team when people will collaborate over time. - Accepting the Team invitation links the recipient's Identity and device and inherits every current and future Project assigned to that Team. - The invitation does not create Project-to-Team assignments. Manage those separately, and review the Team's Projects before sending or accepting the invitation. - Team invitation previews group matching Project display names into one row, combine their memory counts, and show how many distinct Project identities the row covers. This summary does not merge Project identities or change access; matching names alone do not prove that repositories are the same. - **Direct Project sharing** — once Team sharing is configured, use **Share exact Projects** to invite one Identity to exact Projects without adding the recipient to the Team. - **Add device** — invite another device for an existing Identity and review the Projects it will inherit from that Identity's direct and Team access. Team membership organizes people and devices, but it is not permission to every Project—only Projects explicitly assigned to that Team. Project access remains explicit and uses canonical Project identity. When **Projects** shows **Sharing review**, local Identity suggestions are optional: no action is needed to preserve your current setup. **Review this suggestion** shows the recorded evidence. **Apply** records the selected review decision only; it does not grant or revoke access, assign an Identity, or change project mappings. Recording a local preference does not remove existing recipients. Use **Update sharing** in the project list to change recipients explicitly, or **Devices** for Identity and device setup; these actions are not review responses. If the suggested action requires input elsewhere, choose a review response before applying anything. Use the review checkboxes and **Apply selected** for a subset, or **Apply all** to record every ready choice. For an unfamiliar Project, open **Details** to check its **Project match source**, recorded workspace path, session and active-memory counts, and latest recorded session. Project match source describes how Codemem matches the Project (for example, by remote or workspace path), not a person's Identity or ownership. A Project can appear from sessions or a saved mapping even with no active memories. Its name alone does not explain who created it or why; missing activity is shown as unknown. **Advanced → Coordinator Administration** keeps the last successfully loaded coordinator groups, Spaces, join requests, devices, and status visible if a refresh fails. A bounded notice names stale or unavailable sections and provides **Retry**. Mutations that require current coordinator state remain disabled until refresh succeeds; retained rows and counts do not imply deletion, and a section that has never loaded is shown as unavailable rather than empty. While you edit an enrolled device's display name, background polling leaves the rename form alone. It resumes after you leave the form; saving a rename and choosing **Retry** still request current coordinator data. An outage continues to disable changes until the data loads again. To rename an active Team, open **Sharing → Teams**, choose **Team settings**, and save a human-readable Team name. For Teams completed through legacy setup and still linked to the configured coordinator group, this one action updates both names; local Teams update only their policy metadata. If that exact Team and coordinator group has repeated completed setup records, all of those historical summaries receive the new name while remaining completed. Renaming never changes Team membership, device decisions, or Project access. If the connected service cannot be updated, the local name remains unchanged; retry the same name after the connection recovers. ### Set up an existing Team If a Team needs device setup, **Sharing** shows a notice and **Continue setup**. The Teams list shows **Needs setup**, **In progress**, or **Ready**. 1. In **Review devices**, confirm a suggested person or choose an existing person. To add a missing person, open **Advanced → Manual device and identity controls**, choose **Create person**, then return to setup. Each confirmed assignment saves immediately and resumes if you leave or reload the page. A suggestion is never selected for you. Only this device's own assignment is suggested. For other devices, setup shows how this computer lists them, and you choose the person. The coordinator treats that choice as a label, so it does not count as proof that the person owns the device. Finishing setup needs a coordinator that understands these labels. If setup says the coordinator needs an update, ask the person who runs it to update it, then retry. No changes are applied until then. 2. Still in **Review devices**, include each device with its confirmed person, choose **Exclude**, or clear an earlier choice to review it again. An exclusion applies only to this Team; a confirmed person assignment can be reused by another Team. 3. In **Review Projects**, check every Project. Codemem can recognize some Projects automatically; choose an explicit Project mapping for any it cannot. Unresolved Projects prevent finishing. 4. In the final review, check the server-provided list of people, included and excluded devices, Project mappings, and every access change. Nothing changes while you are reviewing or saving choices. 5. Choose **Finish Team setup** only when the review is correct. The first valid finish becomes the shared result for that Team. Codemem applies the confirmed Team, device decisions, Project mappings, and access changes together. If it cannot complete every change, it applies none. Setup can become stale when devices, Project mappings, or access change while you are reviewing. Refresh the Team, review the updates, and finish again; new or changed devices need a fresh decision. Your unchanged saved choices remain available for review. When you first open a saved stale review, Codemem revalidates it once so you can continue without an initial Retry click. If revalidation fails, the dialog shows the error and keeps Retry available. Reads used only to check a completed setup do not refresh the review automatically. When another upgraded device opens **Sharing**, it automatically applies a completed Team's reviewed policy locally before removing the setup task. The Team then appears normally under **Sharing → Teams**, so you do not need to repeat setup on each device. A new device can recover a Team even if it has not seen the other people before. It restores missing person records under their saved Identity IDs with the display name **Team member**, because the completed setup does not include person names. Existing names and identities are not merged or changed. Restoring a person record does not verify account or device ownership. If the page closes or the finish response is lost, refresh **Sharing** and open the Team again. Retrying the same finish safely returns the completed result instead of applying access changes again. If setup cannot reach the shared completion service or cannot apply the completed result locally, the task stays visible and offers retry; it never hides an incomplete setup. When a Team's completed setup cannot be recovered, **Sharing** shows **Needs recovery** with the reason and **View recovery details**, rather than asking you to migrate it again. Other Teams can still be reviewed. If this device verifies that its existing policy matches the coordinator's and only a local Project scan limit prevents recovery, its existing sharing stays active. Conflicting or unverifiable policy still requires containment before recovery can continue. Every device that finishes or recovers setup must use a coordinator that supports cross-device Team completion. The device must also list the Team's coordinator group in `sync_coordinator_groups`; scope-backed discovery can show a Team for review but cannot complete its setup. With an older coordinator, Codemem keeps the setup unfinished rather than creating a local-only result; update the coordinator, then retry. A device upgraded after a prior local completion makes that result available when it reconnects, after which other upgraded devices recover it automatically. A device that is not a member of every Space in a completed Team still applies the setup. It shares only the Projects in Spaces it belongs to, and adds the others if it later joins those Spaces. Leaving one of the Team's Spaces later does not reopen setup on that device. If a completed Team keeps asking for setup or the setup dialog will not load, run a dry run on the affected device. It needs the coordinator admin settings saved in your configuration: ```bash codemem coordinator schema diagnose-team codemem coordinator schema diagnose-team '' --json ``` For each configured group, the report shows whether the coordinator has a completed setup, which mapped Spaces are not active on this device, and what applying the completion would do. You can run it before opening **Sharing**. It creates any missing review draft inside the temporary copy, following the viewer's recovery sequence. When the apply fails, the report names the failing check. The command opens the existing database read-only and diagnoses a private temporary SQLite backup, including committed changes from a running viewer. It needs temporary disk space for a full database copy and removes the copy afterward. Database initialization and compatibility upgrades run only on the copy. The viewer logs the original failing check as a `[team-setup]` warning when a setup request fails. ### Share exact Projects For direct sharing, including after Team onboarding: 1. Choose **Create an invitation → Share exact Projects**. 2. Choose an existing **Identity** or enter the teammate's Identity display name. 3. Select the exact projects and review their existing-memory counts. 4. Confirm that the invite shares those existing memories and future activity, then send the one expiring invite. 5. The recipient reviews the invitation, accepts once, and confirms their Identity and device display names. Codemem links the Identity and device, establishes trust and Project access, and starts initial sync. ```text Brian will receive: • 436 existing memories and future activity from codemem No other projects will be shared. ``` Project access uses canonical project identity, not a display name. Selecting `codemem` does not share a similarly named or sibling project in the same Space. **Only me** keeps a memory local, even when its project is shared. The invite is single-use, expires, and is limited to the reviewed Projects. It names one Identity, not a Team, and the recipient cannot add Projects during acceptance. Existing and future selected-Project memories arrive after setup; unrelated Projects remain absent. ### Add a device for an existing Identity Create an **Add device** invitation from the existing Identity. Before sending it, review the exact Projects the new device will receive: - Direct Projects come from access granted to that Identity. - Team Projects come from the Identity's Team membership. - Existing Project exclusions remain excluded. - The invitation cannot silently add unrelated Projects during acceptance. The recipient accepts on the new device. Codemem links it to the same Identity, establishes the required trust, and starts initial sync for the reviewed Projects. ### Devices, status, and recovery **Devices** shows every known device and whether its Identity ownership is configured. It does not infer ownership from pairing, coordinator membership, device names, or historical associations. It also does not infer per-device Team access from Identity membership; use Team policy administration when you need to review authoritative device decisions. Both direct and Team access remain limited to exact canonical Projects selected in Sharing. These screenshots use fictional devices. **Laptop** is the local device. **Studio** has recent exchanges in both directions, **Workshop** has received operations but has no observed send, and **Notebook** has a failed send. Devices with an overall sync summary and separate sending and receiving activity Use **Rename device** on a configured row in **Devices** to change its friendly name. A coordinator-enrolled device is renamed in every configured group where it is enrolled; if one group fails, retry the same name after the coordinator recovers. A device without coordinator enrollment gets a name local to this installation. **Change Identity** is a separate, reviewed ownership reassignment; the target picker lists only other active Identities. It cannot rename a device. Each device name carries its overall sync state. The **Sync** column shows **Sent** and **Received** activity for the **Last 24h**, with relative freshness. Sent counts **acknowledged operations**, and Received counts **applied operations**, starting when this installation began recording activity. Retried operations count once. An acknowledgment means the remote endpoint accepted the batch without reporting apply errors. It can include operations the peer already had or intentionally skipped. Open **Sync details** for exact timestamps, count definitions, snapshot counts, tracking coverage, queued work, and recovery guidance. Failures remain visible when details are closed. An unknown activity count appears as **—** rather than zero. See the [expanded example](images/docs-devices-sync-details-dark.png). An idle check can succeed with zero operations. Codemem retains operation and snapshot revision IDs beyond the display window to avoid counting retries again. This tracking uses additional database space as activity accumulates. **Sync: OK** means both directions have recent successful checks. It does not prove that every page of eligible data has transferred. In **Sync details**, **Queued for sync: Unknown** means Codemem has not measured the remaining work. It does not mean zero pending operations. A receive error for one Space stays visible until a later sync pass checks every Space shared with that peer. A pass that stops early, such as after a failed send or a sync reset, does not clear it. A relay pass checks one Space at a time, so it clears connection errors but leaves apply and scope errors until a direct sync completes. A peer that you only reach through relay therefore keeps showing an apply or scope error even after relay retries that Space successfully. Failed connection probes do not replace the last completed result while sync tries other addresses or relay. If those attempts also fail, the completed pass reports the failure in **Advanced → Sync**. Connection failures before a valid peer status response do not create send or receive errors or add the peer to the needs-attention count. Previously successful checks age into **Stale**, and directions without a successful check stay **Not verified**. Trust, scope, and version negotiation problems still need attention, as do failures after an exchange starts. **Sync now** uses the Viewer's existing relay connection when one is available, just like background sync. An upgrade does not clear stored receive errors from earlier connection failures. An affected device keeps showing **Receive failed** until a successful receive clears the error under the existing rules. A sleeping or powered-off device is **Offline**. Its old sync timestamps and failed connection probes do not lower overall Health or trigger repair advice, even when other devices are online. Health shows **Waiting for devices** when offline devices account for stale sync checks. Sync resumes when they become reachable. Recorded transfer errors, trust or sharing problems, and errors in the local sync service still need attention. Trust, scope, and version negotiation warnings persist across unreachable retries until a successful exchange resolves them. Sync starts as **Not verified** after an upgrade until Codemem observes the direction. Older history can also be unknown, so Devices leaves its time and counters unavailable instead of treating them as zero. A successful exchange with one peer does not hide another peer that is unknown, stale, or needs attention. An unpaired device does not show zeroes as though it had synced. If the status refresh fails, Devices hides stale counts and disables manual sync until a successful refresh. Choose **Sync this device** from the paired device's action menu to run one pass for that device only; it does not sync every peer. The result reports partial or failed delivery, and **Advanced → Sync** still has detailed peer diagnostics. | Sync check | Meaning | What to do | | --- | --- | --- | | OK | Codemem observed successful send and receive checks for the peer. | Open **Sync details** to review exact timestamps and queued work. | | Not verified | Codemem has not observed that direction yet. | Wait for the next sync or run **Sync this device**. | | Stale | The last observed check is older than the current freshness window. | Check that the device can connect, then retry sync. | | Needs attention | A send or receive check reported a problem. | Open **Advanced → Sync** for the reason and retry after resolving it. | | Identity setup state | Meaning | What to do | | --- | --- | --- | | Configured | One active Identity binding is authoritative. | Nothing, unless you deliberately need to change the Identity. | | Setup required | The local or paired device has no authoritative Identity. | Choose an existing active Identity, explicitly confirm the device, and review the change. | | Pairing required | The device is visible through the coordinator but is not paired locally. | Pair it first, then return to Devices. Pairing does not choose an Identity. | | Review required | Device or ownership evidence conflicts. | Use the Advanced review path; normal setup cannot resolve conflicts. | For several setup-ready devices, select each device, choose an Identity for each one, and confirm each choice. Codemem never bulk-assigns an Identity from a suggestion. The review step lists every device and target Identity before the atomic commit. A prefilled local or suggested Identity is still unconfirmed until you select the confirmation checkbox. Changing a configured device's Identity is a separate rebind flow. It shows both the previous and target Identities and requires another reviewed confirmation. If device evidence changes after preview, refresh Devices and review the current information before retrying. The **Sharing** tab shows an attention notice while device setup, pairing, repair, or coordinator enrollment reconciliation remains. **Review Devices** focuses the authoritative ownership workflow. Devices and Sharing show only a safe affected-enrollment count. Identity setup records ownership only: it does not grant Projects, add Team membership, change recipient policy, or enable sync access. When no policy Teams exist, Sharing opens the Identities view rather than implying that coordinator groups are Teams. Devices shows **Complete coordinator setup** when coordinator settings are incomplete. Configure the coordinator URL, administrator secret, and at least one group in the Viewer’s local config, then refresh Devices; Identity setup stays disabled until coordinator evidence is available. Migrating legacy coordinator groups from Sharing also needs coordinator admin access; without it, Sharing won't discover new groups, but saved unfinished migrations remain visible. Current Teams and memberships remain available and unchanged. An actual coordinator outage in Devices shows **Coordinator unreachable** with **Retry**. Already-paired devices that still need approval on this device remain visible when coordinator presence is stale. Wait for a fresh presence update before reviewing approval; stale rows do not offer an approval action. **Availability** tells you whether the device can currently receive work. It does not change ownership or Project access: | Status | Meaning | What to do | | --- | --- | --- | | Waiting for acceptance | The invite has not been accepted. | Copy the invite or cancel it. | | Setting up project access / Starting first sync | Codemem is establishing trust, access, and initial replication. | Wait. | | Waiting for device | The recipient device is offline. | Wait; sync continues when it reconnects. | | Up to date | The selected projects are syncing. | Nothing. | | Needs attention | A setup step reached a terminal failure. | Use **Retry setup**. | An offline device is a passive waiting state, not a failure or revocation. It keeps its current access and catches up after reconnecting. Retry only when codemem shows **Needs attention**; retry preserves completed setup work and resumes from the failed step. Disabling a device enrollment for one coordinator group revokes future delivery only for Projects in that group. The global identity device remains active, stays in **Devices**, and can retain access granted through other groups. Use **Advanced → Coordinator Administration** only to review or re-enable that technical group enrollment. Re-enabling clears the disabled state; the next owner reconciliation pass then restores only the Projects currently authorized through the Identity's direct shares and Team policies for that group. Delivery resumes without a broader re-invite, and unrelated Projects remain absent. A separate global identity-device revocation removes the device from the active list; it is not restored through the group enrollment action. Neither revocation nor disabling can delete memories already copied to a recipient device. Configured coordinator runtimes can expose operator-only global device revocation through a JSON HTTP preview and digest-confirmed commit. This blocks the device ID with any key and its canonical signing key with any device ID across the selected database; it does not rewrite account links, browser sessions, grants, or stored data. Peers that refresh from the coordinator then remove their pairings with the revoked device, as described below. The coordinator-wide admin secret and a trusted configured coordinator/database pair are required, not a browser owner or Team role. Default `coordinator serve` does not activate this capability. The maintained [`coordinator device revoke` CLI](#operator-device-revocation) uses saved operator configuration to preview and explicitly confirm revocation. See the [activation contract](contracts/coordinator-device-revocations.md#optional-configured-operator-http-routes) for runtime composition and request limits. ### What stops syncing when you remove a device Each removal action reaches a different set of devices. Coordinator changes reach other devices when they next refresh coordinator permissions. A direct pairing exists on each device that made it, and only that device can remove it. | Action | Where it applies | What stops | What keeps syncing | | --- | --- | --- | --- | | Remove a Team member or exclude a device from a Team | Every device that refreshes that Team's permissions | That Team's Projects, for the removed Identity or device | Access granted directly or through another Team | | Disable or remove a coordinator group enrollment | The coordinator and every peer that refreshes that group | Projects shared through that group. Peers discovered only through the coordinator also drop the device after the refresh. | Other groups' Projects. Direct pairings on any device keep syncing unscoped memories. | | Revoke a device globally (operator) | The whole coordinator database and every peer that refreshes from it | Coordinator discovery, enrollment, Project delivery, and every pairing with that device ID or key, including direct ones | Peers that don't use this coordinator, or haven't refreshed yet | | Unpair from this device | Only the device you use | Every exchange between this device and that peer | Other devices' pairings with that peer. If both devices still share a coordinator-managed Project, the next refresh pairs them again. | Your own devices and devices that joined through an invitation are paired directly, so removing their coordinator enrollment does not stop their direct sync. Global revocation does: each peer that uses the coordinator asks it which of its paired devices are revoked during its next coordinator refresh, then deletes those pairings and their sync progress. If the coordinator can't answer, for example during an outage or before it's upgraded, peers keep their pairings and check again on the next refresh. To retire a device from Devices, open its menu and choose **Retire device…**. Codemem previews the revocation, asks you to confirm, revokes the device's ID and key across the coordinator, and unpairs it from the device you're using. This needs the coordinator admin secret in this viewer's coordinator settings, and a coordinator whose operator has turned on device revocation. Devices counts a globally revoked device among its revoked devices instead of listing it or offering setup for it. A device ID and key that are revoked globally can't enroll again, so a retired machine needs a fresh device identity to rejoin. No action deletes memories already copied to the retired device. ## Advanced operator and compatibility guidance **Sharing is the primary supported Team experience.** Use **Sharing → Teams** for Team membership, Team names, Identity relationships, and inherited Project access. Use **Projects** to choose exact Project recipients. **Advanced** is technical administration for compatibility, recovery, diagnostics, and self-hosted coordination. Its coordinator groups and Spaces are discovery and transport boundaries, not policy Teams. Creating, renaming, archiving, or restoring a coordinator group does not safely create, rename, archive, or change access for a Team in Sharing. Archiving a coordinator group stops its coordinator presence, peer discovery, Space grants, legacy invites, and joins, and removes that group from this device's local coordinator configuration. Restoring the remote group does not re-add that local configuration; configure this device separately before expecting presence or discovery here. Policy Team membership and Project access in Sharing remain separate and unchanged. Use this section for same-person devices, existing integrations, diagnostics, or self-hosted coordination. These controls preserve internal compatibility and recovery capability; they are not required for the normal Projects → Sharing → Devices → Health workflow. Legacy `#sync` and `#sync/diagnostics` viewer links remain valid Advanced routes. Saved Sync views and coordinator administration remain available through **Advanced**. ### Operator device revocation Use `codemem coordinator device revoke ` only as a coordinator-wide operator. Group/Team authority, an actor hint, or a planted enrollment is not permission to revoke globally. The group selects current enrollment evidence, including disabled enrollment; it does not limit the effect to that group. Save `sync_coordinator_url` and `sync_coordinator_admin_secret` in your private operator configuration and select it with `--config`. This command reads saved values only, not environment credential overrides, and accepts no credential argument. Use an HTTPS origin without credentials, path, query or fragment; HTTP is allowed only for literal `127.0.0.1` or `[::1]` origins. ```fish codemem coordinator device revoke '' '' --config '' --json codemem coordinator device revoke '' '' --config '' ``` The first call sends a read-only network preview and prints validated public references. Noninteractive calls also preview only. A terminal call displays the coordinator ID, evidence group, global device ID and canonical key ID, then asks for confirmation with **No** selected. There is no `--yes`. Confirmation rereads operator configuration and sends the exact preview digest once; changed, missing or malformed configuration prevents the commit request. Requests never redirect or retry automatically. Confirmation revokes the device ID with **any key**, and the canonical key under **any device ID**, throughout the selected coordinator database and all groups. Another device continues only when **both** its device ID and canonical key differ. Confirmed success writes one JSON line to stdout containing the validated committed result: state, version, coordinator, scope, group/device/key IDs, and both retained subject references (`subject_kind`, `subject_value`, `revocation_id`, `created_at`). Prompts, warnings and progress remain on stderr. Retained text uses terminal-safe JSON escapes; parsing restores the original values without timestamp normalization. Overlapping revocations can retain different IDs and dates. Cancellation, rejection and unknown outcomes emit no committed receipt. This does not promise immediate offline enforcement, revoke independent manual or direct-peer trust, erase remote copies, or rewrite account links, sessions, grants, memberships or stored memories. Managed peers learn omissions after a successful current authorization refresh. Configured operator-context runtimes mount these endpoints with a server-trusted coordinator ID and configured coordinator-wide admin credential. Legacy/unconfigured Workers and default `coordinator serve` leave them unavailable; running this CLI does not activate server routes. A stale/unavailable-target HTTP 409 rejects the request and requires a new preview. After dispatch, malformed responses, missing receipts, transport failures and unexpected statuses mean **outcome unknown**: the write may have committed. Ask the operator to inspect both retained subjects; do not assume rollback or retry automatically. ### Sync runtime - `codemem sync enable` generates keys and writes config. - `codemem service start|stop|restart` manages the local service runtime. - `codemem service status` and `codemem status` show the same local operational report. - `codemem sync peers` shows peer health, including per-scope received and pending work. ### Manual pairing Use manual pairing for same-person devices, existing integrations, or compatibility—not normal teammate sharing. 1. In **Devices**, choose **Pair a device** and copy the displayed `codemem sync pair --payload-only` command. 2. On the device you want to connect, run `codemem sync enable` and `codemem service restart` before running the copied command. Both devices need sync enabled to exchange memories. 3. Copy the generated payload and paste it under **Accept a pairing payload** in **Devices**. Choose **Review invite** to check the device ID, fingerprint, and addresses against the other device, then choose **Accept invite**. Accept only a payload from a device you trust; acceptance trusts that device. 4. Repeat in the other direction: enable sync and restart this device, generate its payload, then accept that payload on the other device. Each device must accept the other's payload; one-way acceptance does not complete pairing. For a CLI-only compatibility flow, generate a payload with `codemem sync pair` on one device and accept it with `codemem sync pair --accept ''` on the other. Repeat with the devices reversed. Optional legacy filters can narrow an already-authorized peer's data; they cannot grant project access: - `codemem sync pair --accept '' --include shared-repo-1,shared-repo-2` - `codemem sync pair --accept '' --exclude private-repo` ### Product terms and internal access boundaries Normal sharing uses product terms: - A **Team** organizes collaborating people and their devices. Team membership can supply inherited access only to Projects explicitly shared with that Team. - A **Project** is the canonical repository selected for sharing. Linked worktrees are member paths of that Project, while unrelated repositories with similar names remain separate. - A **Space** is the underlying access boundary that groups related Projects. Normal Project sharing does not require choosing one. Advanced screens and diagnostics may call a Space a **Sharing domain**, a coordinator group an administrative container, and the stored boundary a `scope_id`. Those internal terms explain enforcement; users do not need them to share a Project or add a device. Coordinator-group membership alone never grants Project access. Project filters narrow an already-authorized peer; they never grant Project access. Use separate Sharing domains for personal, work, client, and OSS data on the same machine: | Example project | Recommended Sharing domain | Why | |---|---|---| | `personal/finance` | Personal | Private or same-person data should only sync to your own devices. | | `work/acme-api` | Acme Work | Employer or team data should only sync to devices granted to that domain. | | `oss/codemem` | OSS codemem | Public/open-source work can be shared with OSS peers without widening work access. | Safe defaults: - Unknown projects default to local-only until you map them. - `Only me` keeps a memory local even if the project normally shares. - Private same-person sync uses a personal Sharing domain, not a broad work or coordinator group grant. - A peer's project include/exclude list can remove memories from sync, but it cannot add memories from a Sharing domain the peer is not authorized for. - Broad mappings or basename collisions should be reviewed before you rely on them. If `codemem` exists under both work and personal paths, map the canonical workspace path/remote instead of trusting the basename. - Removing a Local-only project mapping can expose existing memories through a fallback Sharing domain. Review the access warning and select Remove again to confirm; if mappings change in between, review the new warning first. - Assigning a shared mapping to a Project with existing Local memories also requires reviewing and confirming the access change before those memories move. - Sharing a Project stops before granting access if its repository is already assigned to a different Space; resolve that mapping conflict first. For a mixed personal/work laptop using advanced manual mappings, start conservatively: 1. Create or select one personal Sharing domain and one work/team Sharing domain in the Sync settings UI. 2. Map each known project to the smallest correct Sharing domain. 3. Leave unknown projects local-only until reviewed. 4. Pair peers normally, then confirm each peer card shows the expected authorized Sharing domains. 5. Use project include/exclude filters only to narrow what an already-authorized peer receives. Do not treat coordinator-group membership as data access. A coordinator group can help discover and administer devices, but a device still needs Project access through a direct recipient or Team policy before it can receive those memories. ### Upgrade maintenance / Sharing-domain backfill Schema version 21 adds a recipient-policy wake counter on startup. Policy edits made while reconciliation is running remain due for a follow-up pass; existing databases gain the column automatically. When upgrading an existing database to 0.30, codemem may run a one-time Sharing-domain backfill. This stamps historical memories and sync bookkeeping rows with `scope_id` so future sync and retrieval can enforce the new hard boundary. The progress total can be larger than the visible memory count because it includes both `memory_items` and historical `replication_ops`. Large databases can be CPU-bound while this runs. That is expected upgrade work; successful completion should make later startups quieter. Inspect current and completed maintenance jobs with: ```fish codemem maintenance status ``` ### Same-person device recovery - In **Advanced → Sync**, ownership summaries come from active `identity_devices` bindings. Use the device card's **Set up Identity in Devices** or **Review or rebind in Devices** action to confirm or change ownership. - A legacy `sync_peers.actor_id` value may appear as a suggested Identity, but it is only a hint. It does not become ownership until you explicitly review and confirm the binding in Devices. - Identity setup preserves the distinction between ownership, provenance, pairing, and access. Private sync still requires membership in a personal Sharing domain; an Identity binding is not an access grant. - If a machine is replaced or re-paired, use `Claim old device as mine` to reconnect older synced history to your local actor. ### Advanced actor management - The Sync panel now has an `Actors` section for creating and renaming non-local actors. - The same section can merge a duplicate actor into another actor. This immediately moves assigned peers, device bindings, Team memberships, and direct or received Project access to the target Identity, while already-stamped historical memories keep their current provenance until a later follow-on flow changes them. - Historical actor records and `sync_peers.actor_id` remain available to explain provenance and supply setup suggestions. They do not establish device ownership. - Create or rename an actor label here when maintaining legacy provenance, then complete any device ownership choice in Devices. - Non-local peers receive memories only after Sharing-domain authorization succeeds. Their include/exclude filters can narrow that set, but cannot grant access. - Use `Only me` on a memory when it should stay local and not sync to non-local actors. - The Sync panel also shows a teammate review card with per-peer counts for memories that will share by default versus memories marked `Only me`, plus a one-click jump into `My memories` in the Feed for review. ### Compatibility, Spaces, grants, and reassignment Legacy pairing and coordinator invitations remain supported, but do not grant selected-project access by themselves. Manual Space grants and project mappings are Advanced administration. When selected history may already have replicated, all participating owner devices must support `reassign_scope` before codemem moves it into a project-specific boundary. If any required device lacks support, setup fails closed before partial migration; update that device, then use **Retry setup**. Technical capability details and IDs are available only in diagnostics. ### One-off sync - `codemem sync once` syncs all peers once. - `codemem sync once --peer ` syncs one peer. ### Autostart - codemem does not ship a `sync install` helper in the TS CLI. - Use an OS service manager to run `codemem service start --foreground` at login/boot. - Follow the [autostart template guide](autostart/README.md) to customize executable paths, runtime environment, and logs before installing an OS service. ### Diagnostics - `codemem sync peers` shows peer health, including per-scope received and pending work. - `codemem sync attempts` shows recent sync attempt history per peer. - `codemem sync doctor` shows detailed sync configuration and reachability diagnostics. - `codemem sync bootstrap ` bootstraps sync state from a peer's snapshot. - `codemem sync relay-keys` lists the relay service key pinned for each coordinator group. When a coordinator advertises a different key, relay pauses for that group and sync stays direct until you check the new key with the coordinator operator and run `codemem sync approve-relay-key --key `. Set `sync_relay_enabled` to `false` to turn relay off on a device, then run `codemem service restart`. The service reads the setting only at startup. [Relay](relay.md) explains relay status lines and failure codes. - A restored peer requires its SQLite database and original signing key together. If no matching key exists in `device.key` or the configured platform keychain, sync fails closed with a `device_identity_*` diagnostic instead of silently replacing the enrolled key. - The daemon records an `identity_error` state and retries without blocking local memory capture. Restore the original key, then restart the service if mDNS advertisement also needs to be re-established. - See [Anchor-peer deployment](anchor-peer-deployment.md#storage-and-backups) for the complete backup and restore contract. ### Service commands - `codemem service start|stop|restart` manages the local service runtime. - `codemem service status` returns the same local operational report as `codemem status`. - Existing `codemem serve` invocations remain supported for compatibility. Bare `codemem serve` runs the local service in the foreground. ### Coordinator-backed discovery - Use coordinator-backed discovery when peers are reachable but their addresses change frequently or mDNS does not work across network boundaries such as VPNs. - Set `sync_coordinator_url` and `sync_coordinator_group` to enable it. - The Settings UI exposes coordinator URL, group, timeout, and presence TTL fields under Device Sync. - Use **Share** in Projects for normal teammate sharing. Manual project-to-Space assignment, grants, addresses, fingerprints, filters, epochs, and cursors are operator/compatibility details; Device Sync is for runtime configuration. - The coordinator is self-hosted/operator-run and only helps peers discover fresh addresses; direct peer-to-peer sync remains the data path. - See [docs/coordinator-discovery.md](coordinator-discovery.md) for setup, config, and current limitations. - See [docs/anchor-peer-deployment.md](anchor-peer-deployment.md) if you want an always-on peer as a sync backstop for personal or team Sharing domains. - Do **not** expose the viewer itself just because the coordinator or sync protocol needs cross-network reachability; those are separate surfaces. ### First-owner bootstrap before Teams Link an existing device's account, then enroll a second device with its own key under the same Identity. This operator-assisted bootstrap works before any Team exists. It creates no Team or Project access and does not change memory sharing. Choose the coordinator deployment before starting: - `group-create` and `enroll-device` write only the built-in coordinator's **local SQLite** database selected by `--db-path`. They do not create groups or devices in a remote Worker. - A Cloudflare Worker needs its first group and enrolled device created in its D1 database by its operator. Follow the [Worker first-device prerequisite](cloudflare-coordinator-deployment.md#7-enroll-the-first-device); there is no maintained remote CLI command or zero-seed Worker flow. Part A reviews and links the already-enrolled profile. Part B enrolls a separate profile with a fresh key. Ordinary `device_claim` supports Google account linking for an active eligible device, but that link cannot enroll another profile until a reviewed authority upgrade is available. #### Optional coordinator account linking ##### Reviewed account qualification `codemem coordinator owner qualify ` previews a separate permission: “Allow this linked account to enroll new devices under this Identity.” Its server API is mounted only on the configured Worker with browser authentication and owner enrollment enabled, the selected D1 binding, and complete current schemas (including explicit migrations 0035 and 0036). Default/unconfigured Workers and local coordinator serving cannot issue qualifications. The command never installs schemas, configures Google, or deploys the Worker. The command uses the saved coordinator URL and existing private admin credential (`--config` can select the saved configuration). It accepts only the exact `controller-v1:` reference from a real operator device-owner review, not an Identity, email, link or key nomination. Independently verify that review. The command first requests a network preview. `--json` and noninteractive runs stop after this read-only preview; interactive confirmation defaults to **No** and submits the exact server digest. Changed or revoked evidence denies confirmation without automatic retry; an unknown write outcome does not mean rollback. A transport-group grant remains a separate operator decision. Qualification does not create a Team, change Project access, or rewrite the original device claim. Bare, unqualified device claims remain denied for account-mode device enrollment. The owner consumer accepts issued, nonrevoked qualified links with complete schemas and an independently eligible transport-group grant. Bare claims remain denied, and other privileged consumers do not gain this exception. This source stack does not configure or deploy a live service or verify the live two-device journey. ##### A. Review, grant, and link the existing enrolled profile Run these commands on the existing device. The review reads its actual current Identity and device binding; it has no Identity argument and cannot nominate another user. It does not adopt old keys or create a new Identity. For a separate operator review, preview the existing device owner. The group name is the coordinator administrative group, not a Team permission or an access grant: ```fish codemem coordinator owner review team-alpha --coordinator "https://coord.example.com" --config '' --db-path '' --json ``` The preview reads the existing local device database and current Identity, then asks the coordinator to preview the review. It does not run database maintenance, change configuration or credentials, rotate keys, adopt an Identity, move memories, or change ownership or grants. It uses the configured coordinator-admin credential; do not put that credential in the command or output. Without `--json`, the interactive prompt defaults to **No**. Only an operator confirmation writes a coordinator controller review; it does not write an actor, grant, or Identity/device ownership record. Noninteractive and JSON calls remain preview-only. Before confirmation, the command displays the relevant retained Team history, including historical Identity assignments. JSON previews preserve that history in `legacy_history`. These records are evidence to inspect, not permission to change Team or Project access; confirmation does not rewrite them. If the coordinator omits history or returns invalid history, update it before reviewing. If the terminal output cannot show all history, the command refuses confirmation; use `--json` to inspect the complete preview. Changed evidence requires a fresh review and explicit confirmation, never an automatic retry. To confirm the review, run the same command in a terminal without `--json`: ```fish codemem coordinator owner review team-alpha --coordinator "https://coord.example.com" --config '' --db-path '' ``` After confirmation, the command displays the coordinator's stored **Controller attestation reference** (`controller-v1:` followed by 64 lowercase hexadecimal characters). Keep that noncredential reference with the reviewed coordinator and group for a separate, explicit operator-issued transport group grant. It is not an admin credential, invitation, review receipt ID, or proof of Team/Project access. A successful retry returns the same stored reference; previews do not return one. The review command does not issue a transport group grant. To preview that separate operator action, use the stored reference with the maintained command (replace the example reference with the one returned by your review): ```fish codemem coordinator group grant-identity 'controller-v1:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' --config '' --json ``` Run the same command in a terminal without `--json` to confirm; the prompt defaults to **No**. JSON and noninteractive invocations only show a local request preview, make no network request, and do not check server eligibility. There is no `--yes` shortcut. Cancellation sends no request. The command reads the existing coordinator URL and admin credential from the selected configuration and shared runtime overrides. Use `--config` to select the existing operator configuration; there is no URL, credential, Identity, or group argument. The URL must be an HTTPS origin without embedded credentials, path, query, or fragment (literal loopback HTTP is allowed for local testing). Only the validated origin is displayed, never the admin credential. `--db-path` and its legacy `--db` alias are accepted for consistency but do not open a database. After confirmation, the command sends exactly `{ "attestation_id": "..." }` to `POST /v1/admin/identity-group-grants`, using the existing admin header and refusing redirects. The coordinator derives the Identity and transport group from the actual stored review and rechecks current authority. Success requires a validated active controller-attestation grant with a coordinator ID, Identity ID, group ID, receipt reference, revision, and timestamp. Both newly created and already-existing grants are reported. This is an explicit **transport enrollment grant**, not Team/Project access. It does not run Google sign-in, alter the local profile, move memories, enroll a device, or complete first-owner bootstrap by itself. Do not put credentials in commands, edit the database, or derive a reference yourself to bypass missing operator setup. If current review authority is unavailable, ask the operator to check enrollment, revocation, and group status. Network or invalid-response failures may leave the outcome unknown; check coordinator state before retrying. Ambiguous ownership stops the review. If ownership records disappear or change during the prompt, the command stops and requires a fresh preview; it never migrates legacy records automatically. After the grant succeeds, use the maintained link command on that same device. It resolves the current configuration or environment Identity and readiness automatically; it does not accept an Identity to nominate. Choose the intended Google account in its browser: ```fish codemem coordinator account link team-alpha --coordinator "https://coord.example.com" --config '' --db-path '' ``` Add `--config` or `--db-path` only to select the intended existing configuration or database. Keep `CODEMEM_KEYS_DIR` unchanged when selecting existing device keys. The command also honors `CODEMEM_SYNC_COORDINATOR_URL`. If linking returns `auth_link_review_required`, check the current Identity and coordinator status again. If it still cannot link, ask the coordinator operator; do not run an administrator command or use administrator credentials as a client workaround. If review conflicts, is revoked, or stops, contact the coordinator operator. A rejected link does not replace an existing link; do not create another Identity, key, or credential to work around it. An account-link conflict can involve either the Google account or the coordinator Identity, including a revoked binding. If this account already belongs to the intended Identity, sign in at the configured coordinator's `/auth/sign-in`; otherwise ask the operator. These commands cannot replace or remove account links. See [Coordinator-backed discovery](coordinator-discovery.md#optional-account-linking) for the link-session limits and privacy rules. #### Optional coordinator owner enrollment ##### B. Enroll a separate fresh-key profile Part B is not the Part A profile: do not run `owner enroll` against Part A's already-enrolled key, and do not copy that key. Prepare a separate profile with its own new key, configuration, database, and state directory. Use the same Google account linked in Part A. `codemem coordinator owner enroll` does not manually adopt an Identity or an old key, create Team or Project grants, merge Identities, populate existing Identity devices or access authorities, or transfer legacy ownership. It does not configure Google or deploy a coordinator; follow [Cloudflare coordinator deployment](cloudflare-coordinator-deployment.md) for operator setup. This enrollment flow currently requires POSIX private-file checks. Windows enrollment stops before changing the profile because Windows ACL verification is not implemented; do not copy signing keys to work around this limitation. Before preparing, stop this profile's capture plugin, viewer, and sync daemon. Keep them stopped until the command reports `Verified coordinator Identity`: ```fish codemem coordinator owner enroll team-alpha --prepare --coordinator "https://coord.example.com" --config '' --db-path '' --keys-dir '' --state-dir '' ``` The review reports the current Identity, device, key, and memory-author counts. Existing keys, history, and authorship remain unchanged. It does not create Team or Project grants, merge Identities, populate existing Identity devices or access authorities, or transfer legacy ownership. Bootstrap state is populated only after immutable creation proof. Conflicts, legacy enrollment, and already-enrolled keys stop the review; ask the coordinator operator to resolve them. Preparation writes a private `capability-request.json`. Reuse the same coordinator, configuration, database, key, and state-directory selections on resume. If multiple databases share a directory, give each profile a distinct `--state-dir`; the default state directory is shared by colocated databases. Operator admission submits that unchanged file through the operator's private process. Never paste the file contents or a capability into chat or a URL. All resume operations require an interactive terminal, including retained-final and config-only retries; `--json` is supported for preparation, not resume. ```fish codemem coordinator owner enroll team-alpha --resume --review-digest '' --capability '' --coordinator "https://coord.example.com" --config '' --db-path '' --keys-dir '' --state-dir '' ``` If an ambiguous failure occurs after a final request is retained, retry that exact request unchanged. If a start succeeded but no final request was saved, keep the old state and prepare a new attempt in a new `--state-dir`; do not delete or replace the prior state. #### Explicit account admission Operator admission remains the default. Account admission requires a Worker that serves authenticated `/auth/owner/admit`, an active review-backed account link, an eligible existing Identity group grant, and a verified management session from `/auth/sign-in`. Resume the same prepared review with account admission instead: ```fish codemem coordinator owner enroll team-alpha --resume --account-admission --review-digest '' --coordinator "https://coord.example.com" --config '' --db-path '' --keys-dir '' --state-dir '' ``` `--account-admission` is resume-only and cannot be combined with `--capability`. It skips the initial operator start request. The client first binds its retained literal-loopback receiver and saves the start marker, then displays a fixed HTTPS link with no private handoff or secrets in its query. Open the link while signed in to the management account, upload the unchanged private `capability-request.json` from the displayed path, and compare its device and fingerprint with the local output. The fixed admission URL does not carry private handoff material; the OIDC callback follows its configured protocol. Keep the command running and capture stopped until `Verified coordinator Identity` appears; browser confirmation alone is incomplete. If the management account is unknown, denied, expired, or no longer linked, stop. Do not substitute another account, create an Identity, change keys, or try to turn an ordinary `device_claim` into authority. This mode creates neither grants nor device-claim authority, and the flag does not deploy or enable the server page. Preparation and `--json` behavior are unchanged; all resume operations remain interactive. Retained-final retries reuse the exact signed request without a current capability or browser. A retained receipt can reopen for configuration adoption while offline; retain its files unchanged. Local review, capture pauses, cancellation, private-file checks, and refusal of conflicting keys or locks still apply. If the browser was opened but no final request was retained, keep the old state unchanged and prepare a new attempt in a new state directory only after conflicts are reviewed. This source workflow has not yet been validated end-to-end against a live coordinator. It makes no claim about a 24-hour admission or session policy. ### Keychain (optional) - `CODEMEM_SYNC_KEY_STORE=keychain` stores the private key in Secret Service (Linux) or Keychain (macOS). - Falls back to file-based storage if the platform tooling is unavailable. - On macOS, the Keychain storage uses the `security` CLI and may expose the key in process arguments; use `CODEMEM_SYNC_KEY_STORE=file` if that is a concern. - Keep the protected `device.key` file as the portable restore artifact even in keychain mode; codemem can repopulate the keychain from a matching restored file. A matching private key that remains in the platform keychain can also authenticate a local installation if `device.key` is missing, corrupt, or belongs to another identity. That is not a portable migration: moving a keychain-only credential requires platform-supported secure tooling. The database and public-key file alone cannot authenticate the original identity. ## Troubleshooting - If sessions are missing, confirm the viewer and plugin share the same DB path. - Check `~/.codemem/plugin.log` for plugin errors. - Sync errors: `codemem sync peers` shows the last error per peer. ### Inspect retained rejected events Use `codemem diagnostics capture list-rejected --json` to list retained OpenCode rejection metadata without reading private event text. Copy a receipt into `codemem diagnostics capture show-rejected '' --json` to validate that file and inspect its metadata. The commands work without a running Viewer or database connection and do not modify retained files. Without `--json`, inspection prints a short metadata summary. Add `--raw` only when you intend to reveal private event text. That option always returns JSON with the original serialized text as an escaped string. Entries larger than 16 MiB remain listed but report `read_limit_exceeded` when inspected. Malformed entries report `invalid`. If a file changes during inspection, the result is `changed_during_read`. Rerun the command for a stable snapshot. Inspection never removes the file. After inspecting a valid entry, retry that selected receipt only when you intend to deliver it to the current database and runtime identity: ```fish codemem diagnostics capture recover-rejected '' --db-path '~/.codemem/mem.sqlite' -y ``` The original delivery target is unknown. `--db-path` selects the current database, and `-y` confirms that choice. Before sending, the command verifies the loopback Viewer's protocol, database, runtime identity, and advertised ingest size. It sends the exact retained event bytes in one wrapped HTTP request, rejects redirects, and does not use a SQLite fallback. Add `--json` for machine-readable output. The receipt is removed only after the Viewer returns a recognized queued or ingested acknowledgement and the retained file is unchanged. Timeouts, unrecognized responses, and ambiguous outcomes leave it retained because the Viewer may already have accepted the event. If the command reports that delivery was acknowledged but cleanup needs inspection, inspect the receipt and recovery status. Do not retry blindly. OpenCode creates retained receipts automatically only for known payload-validation rejections and verified oversized requests. Those entries leave active retry selection, allowing later healthy events to proceed within the existing 20-entry drain limit. A healthy event behind 20 rejected entries waits for the next drain. Timeouts, throttling, server failures, authentication and target errors, and unknown responses keep their existing retry behavior. Retention does not free spool capacity or retry the rejected event automatically. If retention fails, inspect saved events before attempting recovery. The Viewer treats an existing event ID as a duplicate without comparing content. If you suspect that different content reused an ID, add `--keep-receipt` to retain the original file after acknowledged delivery. The command reports success and `cleanup: "kept"` rather than removing the receipt. This option still requires `--db-path` and `-y`, and kept receipts count toward the spool capacity limit. Without it, a duplicate acknowledgement can remove the retained receipt even when its content differs from the stored event. Native Claude, Codex, and Pi hook receipts have their own format. Select it and the provider explicitly: ```fish codemem diagnostics capture list-rejected --format native-hook-v1 --provider claude --json codemem diagnostics capture show-rejected '' --format native-hook-v1 --provider claude --raw ``` Replace `claude` with `codex` or `pi` as needed. Listing reads metadata only. Showing a receipt validates its saved JSON within the 16 MiB inspection limit, and only `--raw` includes the saved text as an escaped JSON string. Inspection uses the provider's existing spool directory and overrides, makes no HTTP or SQLite calls, and refuses unsafe or symlinked paths without changing permissions. Native retained files end in `.retained`, so older CLIs do not replay them as active `.json` entries. To recover a supported native receipt, select its format and provider and confirm the current database: ```fish codemem diagnostics capture recover-rejected '' --format native-hook-v1 --provider claude --db-path '~/.codemem/mem.sqlite' -y ``` Recovery uses the provider's HTTP route after checking the Viewer profile, current database, runtime identity, and complete request size. It rejects redirects and has no SQLite fallback. Add `--keep-receipt` to preserve the file after a recognized acknowledgement. Duplicate or no-op skip responses leave the receipt intact because they do not confirm native capture. Pi receipts with a saved extraction cutoff cannot be recovered through the current HTTP API. Recovery reports `pi_boundary_snapshot_unsupported`, sends no POST, and leaves the file untouched. Other Pi boundary receipts require a durable queued acknowledgement. A synchronous response cannot confirm completion of that boundary work. Existing native boundary retries are unchanged. Native hook delivery automatically retains receipts after the exact HTTP 400 `invalid session id` response, or HTTP 413 `payload too large` with a positive safe-integer `max_bytes` smaller than the complete outgoing UTF-8 body. Unknown responses, redirects, authentication and target errors, throttling, and transport or server failures remain retryable. Confirmed retention preserves the original bytes and allows later healthy queue entries to proceed. Retained entries do not count as accepted ingestion and require explicit recovery. A changed target or increased body limit may make an oversized receipt recoverable. Claude preserves the local fallback for the boundary event being ingested now. Older queued Claude boundaries can be retained after a terminal rejection. Explicit recovery sends their boundary-flush header, so recover these receipts to resume that work. Pi keeps receipts with any saved extraction cutoff or pending boundary work in the active retry queue. A native skip response does not authorize cleanup. Inspection shows retained receipts, not the active native hook backlog. Native hook storage has no entry limit equivalent to OpenCode's spool limit. Native inspection refuses group- or other-writable spool directories and files. Spools created with umask `002` may therefore require a permission review before inspection works. Review ownership and remove group or other write access where appropriate before retrying. The commands never change permissions. Symlinks in the spool directory or its immediate parent are also refused, so use a physical directory path. Native retention and recovery have not been validated on Windows. Filesystems that cannot synchronize directories cause these operations to fail rather than use a copy-or-delete fallback. Automatic retention preserves ordinary retry behavior and reports a warning when directory permissions or filesystem support prevent safe retention. A failure after publishing a retained copy can leave saved bytes outside active selection. Inspect the retained receipts before attempting recovery, especially when a warning reports uncertain lock release. ### Semantic runtime unavailable Codemem installs its matching optional embedding runtime by default and falls back to FTS5 keyword retrieval when that runtime is absent. On Linux, set the CPU-only policy so the installer skips the unused GPU provider: ```fish env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem ``` On Apple silicon macOS and Windows, install normally (no environment variable, which `env`/`cmd.exe`/PowerShell do not share): ```text npm install -g codemem ``` For an existing setup-managed installation, upgrade `codemem` with the package manager that originally installed it, then rerun its setup command. The scoped `--opencode-only` and `--codex-only` forms work too. Setup replaces the old managed `npx -y codemem mcp` launcher and codemem MCP entries detected as UV/UVX-based so both packages resolve in one runtime. Other custom MCP commands remain unchanged. Claude marketplace installs bundle MCP configuration and need no separate setup command. `codemem setup --opencode-only` writes an MCP entry that starts one `codemem mcp` process per project directory (`--opencode-mcp stdio`, the default). On OpenCode 2.2.6 and later, `--opencode-mcp pooled` writes one shared entry instead, so every project uses the same process. It replaces an entry setup wrote earlier and leaves a customized one alone unless you pass `--force`. Every project must load the codemem plugin. Rerun setup with `--opencode-mcp stdio` to go back. See [Shared MCP server](plugin-reference.md#shared-mcp-server-on-opencode-2-opt-in). For a smaller keyword-only install, use `npm install -g codemem --omit=optional` and set `CODEMEM_EMBEDDING_DISABLED=1` in every Codemem process. The flag is required because npm also omits sqlite-vec's optional platform package. Generated MCP configurations use the durable global `codemem` binary when it is available, allowing it to resolve the globally installed sibling package. Setup-managed `npx` launchers instead request `codemem` and `@codemem/embeddings` together in one temporary environment. After installation, restart the host you configured — OpenCode, Claude Code, Codex, or Pi — plus any running local service. Each MCP process checks runtime availability once per lifetime, so a running Claude or Codex MCP host stays lexical-only until it restarts; restarting the local service alone does not restart that MCP child. Codemem runs semantic inference on the CPU. `ONNXRUNTIME_NODE_INSTALL=skip` prevents ONNX Runtime's Linux installer from downloading unused GPU provider libraries; the CPU binaries remain available. Apple silicon macOS and Windows users can omit the environment variable. Intel (x64) Macs have no ONNX Runtime 1.24.3 artifact, so Codemem reports the unavailable semantic runtime and stays on FTS5 keyword retrieval; installing the runtime there does not enable semantic search. The default `Xenova/bge-small-en-v1.5` model is pinned to a tested revision. If you set `CODEMEM_EMBEDDING_MODEL` to another repository, it must be a feature-extraction model that emits 384-dimensional embeddings — the `memory_vectors` table is a fixed `float[384]` column, and the runtime rejects a client whose dimensions differ. Also set `CODEMEM_EMBEDDING_REVISION` to a branch, tag, or full 40-character commit SHA. The runtime resolves mutable refs to their canonical Hugging Face commit before labeling vectors, preventing old and new embedding spaces from sharing an identity. A custom model without a revision is rejected; offline or local-model use requires the full commit-style identity because Codemem cannot resolve a mutable ref without the Hub. Set `CODEMEM_EMBEDDING_OFFLINE=1` to disable remote model requests and load that commit only from the Transformers.js cache. Clear the variable before using a mutable branch or tag so Codemem can resolve it to a canonical commit. Viewer and OpenCode profile checks include this setting, so clients do not send prompt content to an already-running viewer configured for online model access. `CODEMEM_EMBEDDING_REVISION` can also override the default model revision when an intentional rebuild is required. Downloaded model files are stored in `~/.codemem/models`, about 130 MB for the default model. Set `CODEMEM_EMBEDDING_CACHE_DIR` to use another directory. The directory must be writable by the user that runs Codemem. In a container, mount it as a volume so a rebuilt image does not download the model again. Earlier releases stored models inside the installed `@huggingface/transformers` package, so the first start after upgrading downloads the model once more. With `CODEMEM_EMBEDDING_OFFLINE=1` that download cannot happen. Before upgrading, copy the contents of the package's `.cache` directory into `~/.codemem/models`; both locations use the same file layout. The first v4 start rebuilds legacy default-model vectors once in the background. Measured-compatible legacy vectors continue serving semantic search until the new corpus is complete; other model or revision changes use FTS5 during the rebuild. Cutover and stale-vector cleanup happen only after full coverage. A CPU-only migration of 31,779 memories on an Apple M4 Max took about 30 minutes and peaked at 3.24 GiB RSS. Runtime varies with text length, corpus size, and hardware; the rebuild runs outside the viewer process in bounded batches. ONNX Runtime 1.24.3 has no macOS x64 artifact, so Intel Macs continue using FTS5 keyword retrieval instead of semantic inference. ### Required SQLite native binding `better-sqlite3` is required for every codemem storage mode. Viewer startup now checks its native binding before preparing a database or detaching a background process; restart checks before stopping a healthy viewer. If the check fails, copy the exact-version `npm install -g codemem@` repair command from the diagnostic. Use Node 24.15+ on a supported 64-bit target listed in the [native install matrix](plans/2026-03-15-install-matrix.md). `better-sqlite3` 13.0.3 bundles its N-API prebuilds and has no package install script, so a failed binding check does not by itself mean npm blocked lifecycle scripts. Semantic installs still carry upstream runtime requirements including Sharp, ONNX Runtime, protobufjs, and global-agent; ONNX Runtime's postinstall and roughly 220 MB unpacked weight remain upstream requirements. `sqlite-vec` stays optional: viewer startup catches its load failure, disables semantic search, and preserves FTS5 lexical search. Other commands require `CODEMEM_EMBEDDING_DISABLED=1` when sqlite-vec is unavailable. ### sqlite-vec / `no such module: vec0` **Symptom:** API errors with `SqliteError: no such module: vec0`, or the viewer logs `sqlite-vec failed to load; retrying viewer startup with embeddings disabled` at startup. `memory_vectors` is a sqlite-vec virtual table backed by the `vec0` extension module. The module is shipped as a per-platform npm sub-package (`sqlite-vec-darwin-arm64`, `sqlite-vec-linux-arm64`, `sqlite-vec-linux-x64`, `sqlite-vec-windows-x64`, `sqlite-vec-darwin-x64`) and selected automatically by npm's `optionalDependencies` resolution. It usually just works, but a few install layouts can leave the right binary missing. Diagnose first: ```fish # Confirm the architecture and the codemem install path uname -m which codemem ls (npm root -g)/codemem/node_modules/ | grep -i sqlite-vec ``` You should see both `sqlite-vec/` (the wrapper) and `sqlite-vec-/` (the prebuilt binary). If the platform-specific package is missing, that's the bug. Fixes, in order of preference: 1. **Reinstall codemem with optional deps explicitly included.** npm sometimes drops `optionalDependencies` for global installs: ```fish npm install -g --include=optional codemem@latest ``` 2. **Force-install the platform package alongside.** If reinstalling didn't help (sometimes happens with global installs across major Node upgrades), install the matching platform sub-package separately and link it into codemem's tree: ```fish # 64-bit Pi OS / generic Linux ARM64 npm install -g sqlite-vec-linux-arm64 ln -sfn (npm root -g)/sqlite-vec-linux-arm64 \ (npm root -g)/codemem/node_modules/sqlite-vec-linux-arm64 # then restart the viewer ``` Substitute `sqlite-vec-linux-x64` for x86_64 Linux. A 32-bit Pi OS installation (`uname -m` reports `armv7l`) is not supported because better-sqlite3 13 does not ship a Linux armv7 binary; use a 64-bit OS on arm64 hardware instead. 3. **Run with embeddings disabled.** Codemem degrades gracefully: keyword search via FTS5 keeps working, the viewer keeps loading, and the only feature you lose is semantic recall via vector similarity: ```fish set -Ux CODEMEM_EMBEDDING_DISABLED 1 # then restart the viewer ``` Reverse with `set -e CODEMEM_EMBEDDING_DISABLED`. The viewer's startup retries automatically with embeddings disabled if the initial load fails (`sqlite-vec failed to load; retrying viewer startup with embeddings disabled` in the banner). If you see API errors with `no such module: vec0` AFTER that retry message, please file an issue — `getSemanticIndexDiagnostics` and other vec-touching code paths should be self-healing on a connection without `vec0`. ### Bootstrap grant failures **Symptom:** worker bootstrap fails with HTTP 401 / `bootstrap_grant_invalid`. The wire error is intentionally generic. Check the peer serving the bootstrap snapshot for the specific reason, then work through these: 1. **Is the coordinator reachable from the peer serving bootstrap?** That peer, not the worker, calls the coordinator's admin API to verify the grant. If the coordinator is down or unreachable from that peer, the grant cannot be verified and bootstrap will fail. Check network connectivity and `sync_coordinator_url` config on the serving peer. 2. **Is the grant expired or revoked?** List active grants with `codemem coordinator grant list ` and confirm the grant is still valid. 3. **Does the grant's worker device match the bootstrapping device?** The `worker_device_id` on the grant must match the device ID of the worker attempting bootstrap. A mismatch (e.g., using a grant issued for a different worker) will be rejected. ## Retrieval scope - New memories are stamped with the Sharing domain resolved from their project mapping; unmapped projects stay local-only. - Owned feed items expose a visibility control so you can explicitly switch a memory between `Only me` and `Share with peers`. - Choosing `Only me` keeps the memory local; choosing `Share with peers` keeps it eligible only for peers authorized for the memory's Sharing domain. - The feed supports `All`, `Mine`, and `Theirs` scopes without splitting memories into separate databases. - For non-local peers, Sharing-domain membership is the access boundary. Project and per-peer sync filters narrow the eligible set, and `Only me` acts as a per-memory override. ## Advanced Sync panel - The `Actors` section keeps legacy provenance-label creation and rename controls in one place. - Peer cards show authoritative Identity ownership from Devices. Legacy actor values remain suggestions or provenance and cannot be saved as ownership from Advanced. - Feed cards you own include a visibility control so shared/private intent can be changed without editing raw metadata. - `Redact sensitive details` lives above Recent sync attempts so it is easier to find before you inspect peer addresses and attempt history. - Recent sync attempts intentionally show only the latest few rows in the viewer; use CLI diagnostics for deeper history if needed. ## Review and accept recipient invitations For Team/add-device invitations, review the access details before accepting. Use an existing initialized device profile with its matching keys; review never creates or repairs a database or keys, changes config, or consumes the invitation. For a new profile without signing keys, first run `codemem sync pair --payload-only` with the intended `--db-path`, `--config`, and `CODEMEM_KEYS_DIR`. This initializes the local device and prints its public pairing metadata; it does not accept a peer or start sync. Do not accept or send that pairing payload for this invitation flow. ```fish codemem coordinator invitation accept '' --review --json ``` The review shows the coordinator, group, invitation kind, target Identity, device ID and key fingerprint, Team membership, included/excluded Projects, and whether future memories or Team Projects are shared. It returns `reviewed_onboarding_digest` without the invitation token or signing key. After checking those details, accept explicitly: ```fish codemem coordinator invitation accept '' --reviewed-onboarding-digest '' --json ``` Pass the same `--db-path`, `--config`, `--keys-dir`, and `--device-name` overrides to both commands when using a separate profile. Acceptance checks that the reviewed profile and keys still exist before the import can initialize anything. The existing digest binds the reviewed access to the target Identity, invitation, device ID, key fingerprint, and device name. A Team recipient display name is cosmetic and may be changed with `--recipient-name` before acceptance; it is not part of this digest and does not change the assigned Identity or access. Changed access or device bindings require a fresh review and explicit acceptance. There is no automatic acceptance or `--yes` bypass; omitting the digest on a recipient import changes nothing. Do not combine `--review` and `--reviewed-onboarding-digest`. The Viewer remains another way to review and accept. Legacy coordinator invitations still use `import-invite` without a review digest. Invitation inspection and joining reject HTTP redirects: use the original coordinator endpoint instead of forwarding an invitation token to another endpoint. Treat the invitation itself as a secret; CLI arguments may remain in shell history.