Local UI Guide

Streaming is now the default delivery path. See the streaming contract, defaults and compatibility modes for the SDK event iterator, CLI opt-out, UI lifecycle and opt-in MCP answer events. Full-answer completion validators still buffer until acceptance; Python run() retains its complete-string return contract.

The Memorizz local UI gives you a browser-based workflow for connecting to your memory provider, creating/editing agents, running conversations, and inspecting memory state without writing extra code.

What You Can Do

• Connect to Oracle, MongoDB, or filesystem providers.
• Create, edit, favorite, and delete agents.
• Run agents in Playground with streaming responses.
• Launch and govern Codex, Claude Code, OpenHands, and native MemAgent tasks through the Agent Harnesses operator console.
• Configure Browser Use per agent and approve/reject exact browser tasks in Playground before they execute.
• Create, pause, resume, trigger, inspect, and delete durable scheduled automations.
• Connect agents to Notion, Google Calendar, or custom MCP servers, including OAuth, encrypted credentials, allowlists, and mutation approvals.
• Inspect memory types (personas, toolbox, conversations, workflows, long-term, short-term, entity, summaries, shared, cache).
• Configure continual learning, choose user or reviewed developer authority for newly promoted skills, inspect trajectory gates, and activate/demote learned skills.
• Fine-tune the models behind memory (memory routing, embeddings, reranking) on data held in the connected provider. The Models in use cards show whether each fine-tuned version beats what is in use now and its untrained base on the same test examples, and swap it in or back with one click.
• Enable the memory-first learning control plane, inspect immutable event and artifact counts, compile pending events, and approve reversible forgetting.
• Plan memory retention (a dry run over conversation, knowledge, entity, summary and workflow records whose retention decayed), approve it as reversible suppression, review suppressed memories and restore them.
• Review run traces by agent and thread.
• Run AgentMemBench, LongMemEval-V2, LoCoMo-Plus, BEAM, MemoryAgentBench, and legacy LongMemEval in Evalground.
• Manage runtime keys and defaults in Settings, including the Forgetting mechanism section (importance rater, recency decay and weights, suppression thresholds, reflection). Each agent's form has a Forgetting (per-agent overrides) group for the same values.
• Create agents from templates (productivity, personal finance, research, customer support, writing, study coach) or from your own, and see the configuration and its Python SDK equivalent as you edit (see Creating agents).
• Set the agent's background model (summaries, compaction and consolidation), its reranker (Voyage, Cohere, OpenAI Decisions or a fine-tuned one) and its memory router under Model → Memory models (see Memory routing and reranking). Under Memory → Conversation privacy and memory upkeep you can seal conversations, choose where entity facts live, and turn on background consolidation.
• Consolidate an agent's memory from Continual learning → Control plane: plan, review each change, apply it with an approver, undo it later. The Playground's Memory tab shows how the agent remembers, and the memory evolution timeline labels every change a plan made (see Memory consolidation).

1. Install UI Dependencies

For local development against this repo:

pip install -e ".[ui]"

For package usage:

pip install "memorizz[ui]"

If you also want all optional integrations (Oracle, MongoDB, sandbox, docs, etc.):

pip install "memorizz[all]"

memorizz doctor lists the optional extras and whether each is installed. A store whose driver is missing names the extra to add, for example Oracle needs the oracle extra: pip install 'memorizz[oracle]'. With a uv tool install, add the UI too: uv tool install --force 'memorizz[ui,oracle]'.

2. Start The UI

memorizz ui

Default URL: http://127.0.0.1:8765. It opens in your browser once the server is running; memorizz ui --no-open (or MEMORIZZ_UI_OPEN_BROWSER=false) skips that, and it is skipped over SSH, in CI and on a Linux machine without a display. Ctrl+C stops the server at once, even with a page still open.

Optional host/port overrides:

memorizz ui --host 0.0.0.0 --port 9000

Connect at startup

The UI connects before the first page loads when you name a store:

# Oracle, read-only. The password comes from ORACLE_PASSWORD, or you are asked.
memorizz ui --backend oracle --dsn localhost:1521/FREEPDB1 --user MEMORIZZ --read-only

# MongoDB. The URI comes from MONGODB_URI, or you are asked.
memorizz ui --backend mongodb --db memorizz

# A FileSystem store
memorizz ui --backend filesystem --path ~/.memorizz/memory

Passwords, URIs and tokens are never flags. --password-env NAME reads the Oracle password from another variable, and --uri-env NAME the MongoDB URI.

Without flags, the UI connects to the store the environment names: MEMORIZZ_BACKEND plus that provider's own variables (ORACLE_USER, ORACLE_PASSWORD, ORACLE_DSN; MONGODB_URI; MEMORIZZ_MEMORY_ROOT or the CLI's store; MEMORIZZ_NOTION_DATA_SOURCE_ID and NOTION_TOKEN). Without MEMORIZZ_BACKEND, a complete Oracle login, then MONGODB_URI, then MEMORIZZ_MEMORY_ROOT, is used. --no-connect or MEMORIZZ_UI_AUTO_CONNECT=false starts on the connect page instead. Connecting at startup uses the same code as the connect form. If it fails, the UI still starts and the connect page shows why.

The Mac app

MemoRizz.dmg (also the Download for Mac button on the website) holds MemoRizz.app, which shows the local UI in its own window, for macOS 13 or later on Apple silicon or Intel:

• On launch it shows the UI already running on port 8765, or runs memorizz ui and shows it once it answers. Quitting stops the server it started; one it found running is left alone.
• Without MemoRizz installed, it offers to install it with uv (uv tool install --python 3.12 'memorizz[ui,mcp]', installing uv first when needed).
• Links to other sites open in your browser, downloads go to ~/Downloads, and View → Show Server Log opens ~/Library/Logs/MemoRizz/ui.log.
• MEMORIZZ_UI_PORT picks another port and MEMORIZZ_APP_COMMAND the memorizz to run.

The app is signed but not yet notarized by Apple, so the first launch is blocked: open System Settings → Privacy & Security and choose Open Anyway. To build it yourself, run packaging/macos/build.sh (see packaging/macos/README.md).

3. Connect To A Memory Provider

When the UI is not connected, it opens the /connect page.

The header on every page shows the connection: the provider and a short target such as user@host:1521/FREEPDB1 (Oracle), host/database (MongoDB) or the store's folder (FileSystem). It never shows a password, token or URI credentials. Select it to open the connect page.

Oracle

• Required: Username, Password, DSN
• Optional: Schema (defaults to Username)
• Example DSN: localhost:1521/FREEPDB1

MongoDB

• Required: Connection URI
• Optional: Database Name (defaults to memorizz)
• Example URI: mongodb://localhost:27017

Filesystem

• Required: Storage Path
• The CLI's store is ~/.memorizz/memory (or MEMORIZZ_MEMORY_ROOT when set), so the CLI and the UI see the same agents when both use it.

The connect page finds the stores on this computer: the CLI's store and any other folder under ~/.memorizz that holds agents, each with its agent count. Click one to use it. When MEMORIZZ_BACKEND is unset, no MongoDB URI or Oracle login is in the environment and the CLI's store already has agents, the page starts on FileSystem with that path filled in. A path that does not exist yet becomes a new, empty store when you connect.

For Oracle embedding consistency across UI, SDK, and evaluations, first run memorizz oracle preflight --json, then set the dimension reported by the existing schema:

export MEMORIZZ_DEFAULT_EMBEDDING_PROVIDER=openai
export MEMORIZZ_DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
export MEMORIZZ_DEFAULT_EMBEDDING_DIMENSIONS=384  # example; use preflight value

Embedding check

When the UI connects, it compares the store's vectors with the embedding model it is set up to search with. It reads the declared size of Oracle's VECTOR columns, MongoDB's vector index sizes (or one stored embedding per collection), or one stored embedding per FileSystem store. It also reads the embedding settings saved with the store's agents, when there are any.

• If the store records one model, its vectors have that size, and the model can run here (OpenAI, Ollama or Voyage AI, with its key set), the UI searches with it for this session.
• Otherwise the dashboard and the connect page say what differs, for example: This store holds 256-dimension vectors from openai text-embedding-3-small; the UI is configured for ollama nomic-embed-text (768). Searches will not match until you …. The header shows Embeddings differ.

The check reads only. It never re-embeds anything.

Read-only mode

memorizz ui --read-only or MEMORIZZ_UI_READ_ONLY=true makes the UI refuse every change. Every page shows a Read-only badge in the header. Buttons and forms that would change data (create agent, save, send, run, approve, delete, rate cards, budgets) are turned off, with a tooltip saying the UI is read-only. Filters and search still work. The server refuses changes either way. A read-only UI does not load Oracle's in-database embedding model into the database.

4. Navigation Map

Once connected, the sidebar is your main navigation. Its pages are grouped under Build, Memory, Connect, Operate and Admin, and it folds to icons with the arrow beside the logo.

• Search. The field at the top of every page (⌘K on a Mac, Ctrl+K elsewhere) finds any page, any agent in the connected store and a few actions such as Create agent. Type to filter, use the arrow keys to move and Enter to open. Before you type, it lists the pages you opened last.
• Where you are. The top bar names the sidebar group and area of the page you are on, such as Operate / Observability. Select the area to go back to its first page.
• Keyboard shortcuts. Press ?, or the keyboard button in the top bar, for the full list, including the shortcuts of the page you are on. Press g then a letter to open a page:

Keys	Page	Keys	Page
g o	Overview	g l	Continual learning
g a	Agents	g c	MCP connections
g h	Agent harnesses	g k	Skills
g p	Playground	g t	Observability
g u	Automations	g e	Evalground
g m	Memory types	g s	Settings

Shortcuts do nothing while you type in a field or while a dialog is open. - Waiting for you. The bell in the top bar counts what needs a person: tool calls and harness runs held for approval, consolidation plans and persona changes to review, automations whose last run failed and failure alerts that are firing. Each item links to the page where you act on it. - Switch store. Select the store name, in the top bar or at the foot of the sidebar, to list the FileSystem stores on this computer and connect to another one. Connect to another store or database opens the connect page. - First steps. On a new store the Overview lists five steps, from creating an agent to scheduling it, and ticks each one as the store fills. Hide removes the list in this browser. - Your name. Select the person button in the top bar and enter your name or email. It is kept in this browser, fills the approver field of approval, review and undo forms, and signs your changes in the activity log. Compact tables in the same menu shows more rows on every table. - Activity. Admin → Activity lists the changes made through the UI: who, what, which record and when. Filter it, save a view or export it as CSV. It records the route and the IDs in it, never message text, form values or secrets, and chat messages are not listed. The file is ~/.memorizz/audit/ui_activity.jsonl; set MEMORIZZ_UI_ACTIVITY_LOG to write it elsewhere. - Budget meter. Once a monthly budget is set on Usage & cost, the foot of the sidebar shows this month's spend against it on every page. - Run drawer. Select a row under Recent runs (Overview or Observability) to read the run in a drawer; Open the full trace goes to its timeline. - Row menus and export. The ⋮ at the end of an agent or memory row lists its actions. Export CSV on a table page downloads the rows shown, with the filters applied. - Customize the Overview. Customize hides or reorders the Overview's sections, and Compared with chooses what its change figures compare against. Both choices stay in this browser or in the page's address. - Preview pane. In the playground, a reply containing an HTML page, SVG, Markdown, JSON, CSV or a long code block has an Open preview button. The pane opens beside the conversation with Preview, Code, Copy and Download. HTML and SVG render in a sandboxed frame that cannot reach MemoRizz; scripts in the page run only after you tick Run this page's scripts. - Playground home. The Playground opens on a message box. Pick the agent in the box, type and press Enter: the conversation opens in that agent's playground with your message sent. Open without a message goes straight to the agent, and the agents you used last are listed under Jump back in. - Filters and views. On a table page, each filter in use shows as a chip you can remove. Views saves the current filters, sort order and time range under a name and applies it again later. Views are kept in this browser. - Several rows at once. Tick rows to act on them together: add agents to favorites, copy their IDs or delete them; copy or download memory records as JSON; compare two runs of one agent from the Overview's recent runs. Deleting agents removes the agent records only. Their memories, conversations and traces are kept. - Theme. The UI follows your system's light or dark setting until you choose one with the sun and moon button at the foot of the sidebar (Ctrl/⌘+Shift+L). The connect and sign-in pages follow the same choice. - Disconnect. The button beside the theme switch asks before it disconnects. Nothing is deleted.

Section	Route	Purpose
Overview	/dashboard	Runs, success rate, run time, tokens and spend across every agent, each with its change from the period before, plus what needs attention and the memory counts.
Agents	/agents	Browse agents, sort, quick-chat, and jump into edit/playground.
Create Agent	/agents/new	Start from a template or a blank form; set identity, model, persona, memory, learning, tools and runtime, with a live summary and the Python SDK code. ?template=<key> opens it filled in.
Playground	/playground and /agents/{id}/playground	Interactive chat, thread switching, token/context stats, and per-agent runtime config. Timers show as a live card above the chat box.
MCP Connections	/mcp	Configure/test MCP servers, authorize OAuth, inspect capabilities, and invoke governed tools.
Automations	/automations	Create schedules, inspect runs, and manage worker-backed agent jobs.
Memory Types	/memory/{type}	Browse stored memory entries by type (personas, toolbox, workflow-memory, skillbox, conversations, etc.). Workflows lists every MCP and desktop control run with its steps.
Continual Learning	/memory/workflows and /memory/skills	Review canonical trajectory classes, run gated distillation, inspect persisted skill authority, and activate/demote skills.
Fine-tuning	/fine-tuning	Models in use cards (compare, Swap in, Swap back); datasets grouped by job, with test sets; each dataset's Data → Train → Results steps (generation and review, training with live loss curves, the verdict, where it goes wrong, versions compared on the same sets).
Model registry	/fine-tuning/models	Every model per job: what runs now, each fine-tuned version as a family tree (data, training result and its significance, fixed-set scores, size), failed runs with their errors, and the base models to start from; swap in, rename or delete a version.
Learning Control Plane	/learning-control-plane	Inspect scoped event/artifact counts, compile pending events, plan/apply reversible forgetting of compiled artifacts, plan/approve/restore reversible suppression of primary memories, and review, approve and undo persona learning changes.
Agent Harnesses	/harnesses	Probe adapters, launch bounded runs, decide exact approvals, cancel work, and inspect verification evidence.
Traces	/traces	Filter/search agents and inspect thread-level trace timelines.
Memory Evolution	/traces/memory-evolution	Scroll memory versions, inspect actors and origins, and follow explicit branches; also embedded in playground and harness evidence.
Evalground	/evalground	Run local open-model memory suites, monitor logs, and review run history/results.
Settings	/settings	Save credentials and defaults, including the Forgetting mechanism section; shows the actual .env target, precedence warnings and the active memory provider. Existing clients need reconnection.

Settings includes Notion credentials, its memory data-source ID and separate vector backend. For guided access checks or explicitly creating a new Notion area, use memorizz notion connect in a terminal. Saving settings does not switch the active UI provider or migrate memories: use Connect to reconnect. Restart other CLI/MCP processes to load changed defaults. Tokens are never prefilled into the page. The shared env writer uses atomic, owner-only POSIX files; keep them out of version control and review warnings about project .env or exported values overriding your save.

5. Suggested First Run Workflow

1. Open Settings and add at least OPENAI_API_KEY.
2. Create an agent in Agents -> Create Agent. To evaluate learned procedures, enable Continual learning, choose User context or Developer instructions, and keep Require shadow review enabled. Developer authority cannot be saved without review. Enable Memory-first learning control plane to use bounded EvidencePack retrieval and the operator page. Enable Tool call cache to reuse the results of repeated calls to tools marked cacheable, and to MCP tools their server marks read-only and idempotent, for five minutes (Tool call cache). Select Browser Use under Browser Control only after installing the isolated browser-use CLI and configuring its matching LLM key.
3. Open that agent in Playground.
4. Send a message and confirm streaming response.
5. Switch to Traces to inspect events for that run.
6. Review memory entries under Memory Types (especially conversations/summaries/cache).
7. Open Learning Control Plane to inspect the same scope and its compiler or forgetting state.
8. Open Agent Harnesses to inspect local adapter readiness or launch a bounded repository task. Direct edits pause until a host operator approves the exact envelope.

Creating agents

Agents → Create agent starts with the templates. Use template fills in the form below it: name, instruction, persona, and the settings that template needs; the templates fold away and a banner names the one in use. Nothing is saved until you select Save agent, so review and change anything first. Start blank clears it again.

Template	What it sets up
Personal productivity assistant	Gmail, Google Calendar and Notion over MCP; drafts but never sends.
Personal finance assistant	Budgets, bills and savings goals with the arithmetic shown; background consolidation keeps figures current. Gives general information, not investment advice, and never stores card or account numbers.
Research assistant	Web search with citations when a Tavily or Firecrawl key is set; tool-result cache.
Customer support agent	Answers from the knowledge base; every conversation sealed, so one customer's details never reach another; no automations.
Writing partner	Drafts and edits in your voice and learns your style.
Study coach	Explains, quizzes and brings back what you got wrong.

A template with MCP connections attaches them when you save the agent, then opens MCP Connections so you can sign in to each one.

Save as template, at the bottom of the create and edit forms, keeps the form's settings as a template of your own: instructions, persona, model, and the memory, tool and runtime settings. Connections made from the Notion, Gmail and Google Calendar presets carry over without their sign-ins. Memory IDs, delegates, file paths, WhatsApp, other MCP servers and any key or token in the advanced LLM config are left out. Your templates are JSON files in ~/.memorizz/agent-templates/ (or $MEMORIZZ_HOME/agent-templates/), readable only by you, and show on the create page marked Yours, with Delete. Saving under an existing name replaces that template.

The form is grouped into Identity, Model, Persona, Memory, Learning, Tools & integrations, Runtime & orchestration, and Automations & channels; each section's header shows what is set in it. Beside the form, an overview lists the sections, summarises the configuration (models, memory types, whether conversations are sealed, consolidation, integrations, limits), and shows the same agent as Python SDK code. Select Expand to read it full width, or Copy. API keys never appear in it; the code reads them from the environment.

Agent Harnesses in the UI

The /harnesses page is an operator surface, not a vendor terminal emulator. It shows adapter capability probes, bounded launch controls, durable runs and events, token/cost data when the adapter reports it, workspace changes, host verification, and pending exact-envelope proposals. MEMORIZZ_UI_READ_ONLY=true blocks launches, cancellation, approval, rejection, and resume endpoints. The memagent adapter runs a saved agent: pick one, or MemoRizz uses the one you last ran a harness with (native execution never wins automatic routing). Running items spin and update in place; select a run to see its trajectory, and Continue keeps talking to the same harness with the run's setup. Filter the runs by task, harness, MemAgent name or ID, and tick two to four runs for Compare selected: their facts, timelines and steps side by side, including two MemAgents (for example the same agent with and without a tool cache). Codex and Claude Code sessions run with the MemoRizz plugin appear here too, marked plugin session, with their full trajectories (see See each session's trajectory). See Local UI in the meta-harness guide.

Agent create/edit forms can persist runtime mode, where an external harness owns the full turn, or delegate mode, where MemAgent receives governed specialist tools. See the Memory-First Meta-Harness guide.

Browser control in the UI

Install Browser Use and its Chromium outside the MemoRizz environment:

uv tool install --python 3.12 browser-use
browser-use install              # downloads Chromium

In Settings -> Browser Control, choose the Browser Use LLM provider/model, set allowed/prohibited domains, and configure step and wall-clock limits. API keys are stored in the shared MemoRizz environment file; agent records retain only secret-free policy. Browser control remains disabled for an agent until it is selected in the create/edit form or Playground.

When the model requests browser_control, Playground renders the exact task, arguments, policy reason, and proposal identifier. Approve & resume consumes that single-use proposal; Reject prevents execution. A model-visible approved or confirm field does not exist.

See the Browser Control guide.

Playground conversations

• Stop a reply: while a reply streams, the send button turns into a red stop button; click it or press Esc. The partial answer is kept.
• Rename or delete: hover a conversation in the left pane. The pencil renames it in place (Enter saves, Esc cancels; an empty name goes back to the first question). The bin asks for confirmation, then deletes the conversation's messages, summaries and tool logs for this agent. Run traces stay on the Traces page.
• Rename the agent: click its name at the top of the chat, type the new name and press Enter (Esc cancels). The agent list and the CLI show the new name too; in the CLI, /name does the same.
• Watch the CLI live: when you chat with the same agent in the CLI (memorizz or memorizz run), each turn appears in the open playground as it streams: your question marked "Sent from the CLI", the tools it uses and the answer as it is written. Once the turn ends the stored conversation is shown. A turn in another conversation shows a notice with a button to open it. The CLI writes its running turns to ~/.memorizz/live/ (removed after an hour), so this works when the UI and the CLI share a machine and MEMORIZZ_HOME.
• Watch delegates work: when the agent hands parts of a request to its delegates, each one gets a row in the reply: its name and harness, what it is doing now, how long it has worked, and when it ends, done or failed with the reason. A harness delegate's row links to its run on Agent Harnesses and has a live log of its commands and their output, tool calls, file edits and messages, read from the run's record while it works. A crew run from the CLI shows the same rows in the open playground.
• Settings: the Save button stays at the bottom of the Settings tab and shows "Unsaved changes" once you edit a field.

Enabling what an agent can't do yet

When a question needs something the agent lacks, such as web search, email, calendar, notes, running code or a browser, the playground shows a card under the reply instead of letting the model improvise. The card is built from the agent's live configuration each time it appears, so it only offers what is actually missing:

• Web search: use Tavily or Firecrawl in one click when its key is already set, or paste a key (saved like the Settings page, in ~/.memorizz/.env); or find a search server in the MCP Registry.
• Email, calendar, notes: connect Gmail, Google Calendar or Notion; if a connection exists but is not signed in, sign in from the card and return to the playground.
• Run code, browser: a link to the agent's settings.

Once something is enabled the card offers Ask again. The agent also lists what it cannot do in its instructions and calls request_capability rather than claiming it can or can't.

MCP in the UI

Open MCP Connections and select an agent. Presets are available for Notion, Google Calendar, and local stdio servers. Bearer tokens, OAuth client secrets, custom header values, and stdio environment secrets move to the encrypted credential store rather than agent JSON. Use Test, Tools, Resources, and Prompts to inspect a connection; mutating tool calls enter the same durable approval lifecycle.

The page also shows commands for exposing MemoRizz itself as a local stdio or authenticated Streamable HTTP MCP server. See the MCP Connectivity and MemoRizz MCP Server guides.

For developer authority, an activated skill is sent as a native developer message to OpenAI and through Anthropic's top-level system parameter. Only application-owned, reviewed skills should use it; system policy and live tool results remain higher-trust inputs. See the Continual Learning guide.

Evalground Requirements

The five memory-suite adapters require a running Ollama daemon for local nomic-embed-text embeddings and an official dataset path. The default Ollama reader (for example, qwen2.5:3b) uses no external API. Selecting an OpenAI reader keeps memory and embeddings local but requires OPENAI_API_KEY and records an estimated token cost. Neither route requires Oracle. The legacy LongMemEval option still requires an Oracle connection, OPENAI_API_KEY, an agent, and its downloaded dataset files.

Security Notes

• The local UI is intended for development/local usage.
• Default bind is localhost (127.0.0.1).
• Authentication is disabled by default, but built-in token login and signed sessions are enabled when MEMORIZZ_UI_AUTH_TOKEN is set.
• Avoid exposing the UI directly on public networks.
• Browser actions can change external systems. Keep approval enabled and use a narrow domain allowlist for production agents.

For an operator deployment, use a read-only database identity and configure authentication, a separate session secret, secure cookies behind HTTPS, redacted or metadata-only trace content, and audit logging. See Observability and Trace Inspection and Configuration and Secrets.

Troubleshooting

UI Fails To Start

• Confirm UI extras are installed: pip install "memorizz[ui]"
• If using editable install, reinstall dependencies: pip install -e ".[ui]"

Connection Errors

• Oracle: verify DSN/user/password and Oracle client requirements.
• MongoDB: verify URI and DB permissions.
• Filesystem: verify the path is writable.
• A missing driver names its extra, for example pip install 'memorizz[oracle]'. Run memorizz doctor to see every extra.
• If the UI did not connect at startup, the connect page says why.

Port In Use

Start on a different port:

memorizz ui --port 9000