Troubleshooting¶

A saved CLI setting is not taking effect¶

Run memorizz config path to see the save target and memorizz config get KEY to compare the effective source with the saved value (credentials remain hidden). Process exports take precedence over project .env, which takes precedence over the shared Memorizz file. Use memorizz config set KEY --project to edit an intentional project override, or update/unset its shell export. An empty assignment in a project .env also masks a shared value.

Restart after config set or memory configure; they do not reconnect a running agent or migrate its memory. /config shows the active provider. /provider selects the LLM, /memory selects a memory ID, and /memory-provider configures memory storage for the next launch.

For Notion, run memorizz notion connect to check the exact shared library and select the vector backend. /login notion saves NOTION_TOKEN, not NOTION. A 404 can mean the connection cannot access the page/database: share it with the connection, even if you can open it in your browser. Setup's read-only check is not a write-permission or vector-service readiness test.

If a save fails, inspect the shown target's permissions, invalid dotenv syntax or symlinks. Nothing is overwritten on a failed atomic config save. Hidden input requires an interactive terminal; use a secret manager/process export in headless environments. Never pass a credential as a command argument.

Start with the two structured diagnostics:

memorizz config
memorizz capabilities --json

For Oracle, also run memorizz oracle preflight --json.

Agent has no model¶

Symptom: creation succeeds with --no-llm, but execution reports that no LLM is configured.

Configure a provider in the process environment or rebuild/update the agent with an llm_config. A no-LLM agent is useful for configuration and discovery, but it cannot execute a turn.

Ollama repeats its persona or ignores a new question¶

Check ollama ps for the active context size and the Ollama server log for truncating input prompt. Earlier Memorizz versions reported a 128,000-token window without sending num_ctx to Ollama. The daemon could truncate the agent instructions, tool schemas, or conversation using a much smaller window.

The Ollama provider explicitly requests a window and uses that same value for history budgeting: the model's own context length when its attention cache fits in a quarter of this machine's RAM (otherwise the largest standard size that fits, at least 16,384 tokens), or 8,192 when the daemon does not report one. Set context_window_tokens in the model configuration, or OLLAMA_CONTEXT_LENGTH before launching the CLI, to choose another window. Resuming the CLI or switching models refreshes the history budget. See model configuration.

If a local model answers directly during the private tool phase, the streaming loop now checks completion requirements and proceeds to public generation with tools disabled. It does not repeatedly demand the internal finalization tool. See the streaming contract.

Context budget or incomplete-answer errors¶

context_window_exceeded: the instructions, tools and current question do not fit in 80% of the context window. The log line gives the tokens needed and the budget. Increase llm_config["context_window_tokens"] (num_ctx for Ollama) within your model's capacity, or shorten supplied context. Older conversation turns are removed first; the current question and its tool evidence are preserved. Agents saved by earlier releases could keep an 8,192-token cap after their model setting changed; a window set in llm_config now takes precedence over that saved value.
empty_response: the model returned no answer. Retry or select another model.
provider_length: increase the provider's output-token limit (num_predict for Ollama, max_tokens or max_completion_tokens as supported by the provider), or ask for a shorter answer.

These errors do not count as completed answers and are not cached. Streaming retains any partial text already displayed. Synchronous run() raises ProviderStreamError with the same code.

Semantic recall or cache is degraded¶

Filesystem persistence works without an embedder. Semantic retrieval and semantic cache require a compatible embedding provider.

For a local setup:

ollama pull nomic-embed-text

For OpenAI embeddings, set OPENAI_API_KEY and configure the model/dimensions. Never change dimensions against existing vector columns without a migration.

A saved agent is not visible¶

The SDK, CLI, UI, and MCP server must use the same memory provider and MEMORIZZ_HOME. Use build_and_save() or build(persist=True); build() alone creates only a runtime object.

memorizz config
memorizz agents list --json

Memory appears to cross or disappear between users¶

Pass user_id, memory_id, and thread_id explicitly on every shared-service request. user_id=None selects anonymous/legacy rows; it is not a wildcard. See multi-tenant applications.

Semantic cache returns stale business data¶

Similarity does not establish freshness. Mark side-effecting tools correctly, set data-version/domain metadata, use domain freshness limits, and invalidate a domain when its source changes. See production governance.

MCP reports `authorization_required`¶

The endpoint is reachable but the remote grant is incomplete. Finish OAuth or configure the expected bearer credential. approval_required is different: it means MemoRizz paused a mutating call for a host decision.

For local services, private-network access must be an explicit operator choice. For remote services, use HTTPS and review host/stdio allowlists. See MCP connectivity.

MCP mutation never executes¶

List, approve, and resume the exact durable proposal:

memorizz mcp approvals --status pending
memorizz mcp approve PROPOSAL_ID --approver operator@example.com
memorizz mcp resume PROPOSAL_ID

Expired, rejected, consumed, owner-mismatched, or argument-mismatched proposals fail closed.

UI returns 401 or blocks writes¶

When MEMORIZZ_UI_AUTH_TOKEN is set, sign in with that token or supply it as a Bearer credential. MEMORIZZ_UI_READ_ONLY=true intentionally blocks agent creation, approvals, and provider mutations. See observability and trace inspection.

Oracle connection, vector, or index errors¶

Use preflight to check the DSN/service, PDB state, schema privileges, ONNX model, vector dimensions, index state, and VECTOR_MEMORY_SIZE.

ORA-51803: configured embedding dimensions do not match the vector column.
ORA-51962: vector memory is insufficient; use none/lazy indexing or ask a DBA to resize it.

Follow the Oracle troubleshooting guide.

E2B or browser control is unavailable¶

E2B validates E2B_API_KEY at construction. Confirm the sandbox extra and key are present.
Browser Use should be installed in an isolated tool environment. Run browser-use doctor and inspect agent.capability_report().

Browser Use has its own model configuration. An Ollama chat session does not supply credentials for its default OpenAI browser model. If enabling it reports OPENAI_API_KEY is required, configure that key or select another supported browser model provider with MEMORIZZ_BROWSER_USE_LLM_PROVIDER and its matching credentials. This configuration error does not disable ordinary chat.

See E2B and browser control.

Desktop control cannot read or operate an app¶

Run memorizz desktop doctor. It names the app macOS asks about (the one MemoRizz runs in) and whether it has Accessibility and Screen Recording permission; --ask shows macOS's prompts. Turn on that app under System Settings → Privacy & Security, then restart it. Some Electron apps, Notion's desktop app among them, expose no content to Accessibility at all; use their MCP server instead. See desktop control.

An agent harness reports `authentication_required`¶

Run memorizz harness doctor HARNESS --json and follow its remediation field. Claude Code requires ANTHROPIC_API_KEY or an enabled Bedrock, Vertex, or Foundry mode because MemoRizz uses --bare. Codex can use an authenticated CODEX_HOME session, and OpenHands can use provider/CLI configuration, so a missing environment key alone does not incorrectly mark those adapters failed.

SDK, CLI, UI, and MCP return the same typed, secret-free error. Rotate or revoke credentials in the provider, never paste them into a task, notebook, trace, or support report.

Provider errors during streaming¶

The event stream ends with a single run.done event. On a provider failure its status is error and error_code says why, after any text already delivered:

with agent.run_stream_events(query) as events:
    for event in events:
        if event["type"] == "answer.delta":
            print(event["delta"], end="")
        elif event["type"] == "run.done" and event["status"] == "error":
            raise RuntimeError(event["error_code"])

Preparing a useful bug report¶

Include:

MemoRizz version and capabilities --json with identifiers reviewed;
Python and operating-system versions;
selected provider and secret-free preflight output;
the smallest reproducing code sample;
the typed error code and traceback; and
whether the problem reproduces with filesystem memory.

Never attach .env, OAuth tokens, database passwords, raw production traces, or benchmark datasets containing restricted data.