CLI Guide¶

The Memorizz CLI turns the library into a tool: an interactive, Claude-Code-style terminal agent backed by the full Memorizz harness (memory backends, providers, tools). It streams replies token-by-token, supports / slash commands, and — by default — keeps one persistent agent whose memory carries across sessions.

It also runs a 100% local stack (Ollama LLM + Ollama embeddings + on-disk memory, no API key) and can launch the Local UI.

Install¶

The CLI ships in the base package, so the memorizz command works straight away:

uv tool install memorizz       # recommended
pipx install memorizz
pip install memorizz

For the fully-local Ollama stack (Ollama SDK + FAISS filesystem vector store), add the local extra:

uv tool install "memorizz[local]"     # == memorizz[ollama,filesystem]

Other providers are extras: memorizz[anthropic], memorizz[mongodb], memorizz[oracle], memorizz[ui], or everything with memorizz[all].

Homebrew & npm

A Homebrew tap (brew install RichmondAlake/memorizz/memorizz) and an npm bootstrapper (npm i -g memorizz, which installs the real tool via uv) are also available for non-Python-first workflows.

Quickstart¶

Option A — Local, no API key (Ollama)¶

# 1. install + run Ollama, then pull a tool-capable chat model + an embedder
ollama pull qwen2.5:7b
ollama pull nomic-embed-text

# 2. launch the REPL
memorizz

With no cloud key set and an Ollama daemon running, Memorizz auto-selects Ollama for the LLM, Ollama (nomic-embed-text) for embeddings, and an on-disk filesystem store under ~/.memorizz/memory.

Option B — Cloud (OpenAI / Anthropic)¶

export OPENAI_API_KEY=sk-...      # or ANTHROPIC_API_KEY=...
memorizz

Cloud keys are auto-detected (Anthropic → OpenAI → Azure → local Ollama). You can also save a key from inside the REPL with /login.

The REPL¶

Running memorizz with no arguments launches the interactive loop:

Type plain text to chat; the reply streams live and renders as Markdown.
For reasoning models (e.g. qwen3, deepseek-r1), the model's thinking is shown dimmed above the answer, and tool activity is shown as it happens.
Ctrl-C during a reply aborts just that reply (you stay in the REPL).
Ctrl-C at the prompt, Ctrl-D, or /exit saves the agent and quits.
Press Tab to autocomplete slash commands.

Slash commands¶

Command	Description
`/help`	List all commands + the current mode/model.
`/model [name]`	Show or switch the chat model (keeps the provider).
`/provider [name]`	Switch provider: `openai`/`anthropic`/`ollama`/`azure`/`huggingface`/`mlx`.
`/ollama [list\\|pull <tag>\\|host <url>]`	List/pull Ollama models or set `OLLAMA_HOST`.
`/web [on\\|off\\|tavily\\|firecrawl]`	Enable/disable internet search (Tavily/Firecrawl).
`/code [on\\|off]`	Toggle coding tools (file read/write + bounded commands, scoped to cwd).
`/browser [status\\|on\\|off\\|run <task>]`	Inspect/configure Browser Use or run an explicit host browser task.
`/approvals [status/action]`	List, approve, reject, cancel, or resume durable generic tool proposals.
`/memory [id]`	Show or switch the active memory id.
`/history`	Print the current conversation history.
`/conversations [search]`	Open a searchable picker and resume a saved conversation thread.
`/forget <id>`	Delete a single stored memory by id.
`/new`	Start a fresh conversation thread (keeps long-term memory).
`/clear`	Erase the agent's entire stored memory (asks to confirm).
`/cls`	Clear the terminal screen.
`/agents`	List saved agents.
`/agent <id>`	Load a saved agent by id.
`/persona [name \\| goals \\| background]`	Show or set the agent's persona.
`/persona-reset`	Clear the persona (revert to default).
`/tools`	List the agent's registered tools.
`/ingest <file>`	Ingest a file into the knowledge base.
`/ui [--port N] [--host H]`	Launch the local web UI.
`/login [provider]`	Log in / save an API key — lists platforms to pick from if none given.
`/config`	Show resolved config + paths.
`/docs [cli\\|ui]`	Open the documentation in your browser.
`/exit`	Save the agent and quit.

Modes¶

Memory assistant (default). A conversational agent with persistent long-term memory — it remembers facts you share and recalls them in later turns and later sessions.

Coding mode. Launch with memorizz chat --code, or type /code in the REPL, to enable the agent's self-aware tools: read/write files and run a bounded set of commands, scoped to the current working directory (writes on, deletes off).

Browser-control mode. Launch with memorizz chat --browser-control (or use /browser on) to attach the configured Browser Use provider. Model-initiated browser calls pause as durable proposals; a model cannot set an approved or confirm argument. /browser run <task> is a direct, explicit host action and therefore does not represent a model approval.

Internet access¶

Give the agent web search + page reading via Tavily or Firecrawl. No extra install is needed — the providers call the REST APIs directly.

export TAVILY_API_KEY=tvly-...      # or FIRECRAWL_API_KEY=fc-...
memorizz                            # internet tools auto-enable when a key is set

Or manage it from the REPL:

/login tavily       # save the key AND enable internet immediately
/web                # show status  (also: /web on | off | tavily | firecrawl)

When enabled, the agent gains internet_search (web search) and open_web_page (fetch + read a full page). It can search, then open the most relevant result for deeper detail (Tavily runs at advanced search depth for ~5x richer results). Use a 7B+ model for reliable multi-step web use.

Persistent agent & memory¶

Unlike a stateless chat, the CLI reuses one persistent agent across launches. The default agent id and active memory/thread pair are stored in ~/.memorizz/state.json, so the selected conversation resumes after relaunch.

Action	Command	Effect
New conversation, keep long-term memory	`/new`	Starts a fresh thread; past facts still recalled semantically.
Resume a previous conversation	`/conversations`	Search by title, preview, memory ID, or thread ID; select with ↑/↓ and Enter.
Forget one memory	`/forget <id>`	Deletes a single stored entry.
Wipe everything	`/clear`	Erases all stored memory after confirmation; keeps persona + tools.

One-shot mode¶

Run a single prompt and print the reply (pipe-friendly, no REPL):

memorizz run "Summarize what you remember about my project."
memorizz run --code "Add a docstring to utils.py and run the tests."
memorizz run --browser-control "Read the title of example.com."

One-shot turns share the same persistent agent + memory as the REPL.

Configuration¶

Memorizz centralizes config under ~/.memorizz/:

Path	Purpose
`~/.memorizz/.env`	API keys and `MEMORIZZ_*` defaults.
`~/.memorizz/memory/`	Default filesystem memory store.
`~/.memorizz/state.json`	Persistent agent id + active memory/thread ids.
`~/.memorizz/history`	REPL input history.

Overrides: MEMORIZZ_HOME (the home dir) and MEMORIZZ_ENV_FILE (the env file). A project-local ./.env is still honored for backwards compatibility. The CLI and the Local UI read/write the same .env, so configuring once applies to both.

Useful commands:

memorizz init           # interactive key wizard
memorizz init --local   # configure the local Ollama stack
memorizz config         # show paths, providers, embeddings, and learning mode
memorizz capabilities   # report installed features/provider readiness
memorizz oracle preflight --index-policy lazy

Browser control¶

Browser control is explicit opt-in; an LLM API key alone never enables it. Keep Browser Use in its own tool environment because its MCP dependency line can differ from MemoRizz's:

uv tool install --python 3.12 browser-use
browser-use install
browser-use doctor

export MEMORIZZ_BROWSER_CONTROL_PROVIDER=browseruse
export MEMORIZZ_BROWSER_USE_COMMAND=browser-use
# Optional only when the entry point has no discoverable Python shebang:
# export MEMORIZZ_BROWSER_USE_PYTHON_COMMAND=/opt/browser-use/bin/python
export MEMORIZZ_BROWSER_USE_LLM_PROVIDER=openai
export MEMORIZZ_BROWSER_USE_ALLOWED_DOMAINS="example.com,*.notion.so"
export MEMORIZZ_BROWSER_USE_MAX_STEPS=25
export MEMORIZZ_BROWSER_USE_TASK_TIMEOUT=600

The provider resolves the isolated interpreter behind the Browser Use entry point, runs a private fixed worker for each bounded task, passes only an environment allowlist, blocks direct IP navigation by default, and closes the worker/browser on success, error, or timeout. Configure the matching credential (BROWSER_USE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY) in the environment; credentials are not serialized into the agent record.

/browser status
/browser on
/browser run Read the title at https://example.com
/browser off

For a model-requested task, use the generic approval lifecycle:

/approvals pending
/approvals approve PROPOSAL_ID operator@example.com reviewed
/approvals resume PROPOSAL_ID
# Or execute the approved call without a subsequent model continuation:
/approvals resume PROPOSAL_ID --no-model

See the Browser Control guide for SDK, builder, UI, domain-policy, result, and custom-provider details.

To run the CLI against Oracle with an existing external-vector schema, keep the embedding mode and dimensions aligned with the schema:

export MEMORIZZ_BACKEND=oracle
export ORACLE_USER=memorizz_user
export ORACLE_PASSWORD=...
export ORACLE_DSN=localhost:1521/FREEPDB1
export MEMORIZZ_ORACLE_IN_DATABASE_EMBEDDING=false
export MEMORIZZ_DEFAULT_EMBEDDING_PROVIDER=openai
export MEMORIZZ_DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
export MEMORIZZ_DEFAULT_EMBEDDING_DIMENSIONS=256

Enable workflow capture and learned-skill retrieval for one CLI launch:

MEMORIZZ_CONTINUAL_LEARNING=1 memorizz chat --code

To keep it enabled, add the setting to ~/.memorizz/.env, then restart the CLI:

MEMORIZZ_CONTINUAL_LEARNING=1

The startup banner and /config report the live learning state. Continual learning needs tool-calling runs to produce workflow trajectories; ordinary text-only chat has no procedure to promote. Repeat a successful tool workflow with at least two distinct queries, then use memorizz ui → Continual Learning to inspect trajectory classes, run a promotion cycle, and review or activate learned skills.

The agent form also selects the authority for newly promoted skills. Keep the default user role for selectively retrieved guidance. Choose developer only for application-owned procedures; MemoRizz requires shadow review and explicit activation before those skills can enter the provider's developer/system-equivalent instruction channel.

Launch the Local UI¶

memorizz ui                         # http://127.0.0.1:8765
memorizz ui --host 0.0.0.0 --port 9000

See the Local UI Guide for details.

Command reference¶

memorizz                 # launch the interactive REPL (default)
memorizz chat [--code] [--browser-control] [--provider P] [--model M]
memorizz run [--code] [--browser-control] "<prompt>"  # one-shot
memorizz ui [--host H] [--port N]
memorizz init [--local]
memorizz mcp serve [--transport stdio|streamable-http]
memorizz config
memorizz mcp --help
memorizz --version
memorizz oracle install|setup|setup-schema|preflight|teardown
memorizz automations run [--poll-interval N] [--lease-seconds N] [--concurrency N]
# Uses MEMORIZZ_BACKEND=filesystem|mongodb|oracle (filesystem by default)

MCP connections¶

Configure, authorize, inspect, and call local or remote MCP servers without leaving the terminal:

# Notion hosted MCP (OAuth)
memorizz mcp add notion --preset notion
memorizz mcp login notion

# Google Calendar hosted MCP (OAuth client from Google Cloud Console)
memorizz mcp add calendar --preset google-calendar \
  --client-id "$GOOGLE_OAUTH_CLIENT_ID" \
  --client-secret "$GOOGLE_OAUTH_CLIENT_SECRET"
memorizz mcp login calendar

# Inspect or invoke
memorizz mcp list
memorizz mcp test notion
memorizz mcp tools notion --json
memorizz mcp call notion search --arguments '{"query":"roadmap"}'

Mutating calls return a durable proposal instead of executing immediately:

memorizz mcp approvals --status pending
memorizz mcp approve PROPOSAL_ID --approver operator@example.com
memorizz mcp resume PROPOSAL_ID
# Or: memorizz mcp reject PROPOSAL_ID --approver operator@example.com

The proposal binds the exact tool and argument hash, expires, and can be consumed once. Secrets supplied to mcp add are immediately moved to the encrypted credential store and omitted from the public per-agent JSON. See the MCP Connectivity guide for transports, policy, deployment settings, and the UI workflow.

Back-compatible commands

The earlier forms still work with a deprecation notice: memorizz run local → memorizz ui, memorizz run automations → memorizz automations run, and memorizz install-oracle → memorizz oracle install (etc.).

Choosing an Ollama model¶

The agent always sends tools, so the local model must support tool-calling:

Recommended: qwen2.5:7b, qwen2.5:3b, or llama3.1:8b — tool-capable, non-reasoning, good quality.
Reasoning models (qwen3, deepseek-r1, qwq, magistral) work — Memorizz auto-enables their "thinking" so reasoning is surfaced and answers aren't truncated — but for a snappy default a non-reasoning instruct model is better.
Smaller models (3b, even 0.5b) give simpler answers but stay snappy — plain chat exposes no tools by default, so they no longer loop. gemma models lack tool-calling in Ollama, so only use them for plain chat (not /code).
For web search + memory reasoning, prefer 7B+ (qwen2.5:7b / llama3.1:8b): smaller models tend to answer from guesswork instead of reading their memory or chaining internet_search → open_web_page.

Zero-config auto-selection already prefers tool-capable, non-reasoning families.

Troubleshooting¶

"This model can't tool-call." Your Ollama model lacks tool support (e.g. gemma). Pull a tool-capable model and switch:

ollama pull llama3.1:8b
# then in the REPL:
/model llama3.1:8b

No provider configured. Set a key (/login or export OPENAI_API_KEY=...) or start Ollama and pull a model, then relaunch.

Semantic recall seems weak (local stack). Pull the embedder so memory uses vectors instead of brute-force text matching:

ollama pull nomic-embed-text

Slow startup. A default install is lean (no PyTorch). If import memorizz feels heavy, ensure you didn't install memorizz[huggingface] unless you need local HuggingFace models/embeddings.