Skip to content

Getting Started

This guide takes you from a fresh machine to a working mnemoai command.

1. Requirements

Required:

  • Python 3.11+
  • Access to at least one chat model provider

Choose one provider to start:

Provider What you need
Ollama (local, easiest) Install Ollama, then pull a chat model such as ollama pull qwen3.5:4b
Amazon Bedrock AWS credentials with Bedrock model access in your target region
Bedrock Mantle AWS credentials or a Bedrock API key, plus a Mantle model available in your account/region
Amazon SageMaker AI AWS credentials and a deployed SageMaker endpoint
OpenAI OPENAI_API_KEY environment variable
Anthropic ANTHROPIC_API_KEY environment variable
LiteLLM A LiteLLM-compatible provider, API base, and credentials as needed

Optional, depending on features you enable:

  • Embedding model — needed for high-quality RAG, episodic memory, and ACE playbook refinement.
  • Vision model — needed for image analysis.
  • Brave Search API key — needed for web search.
  • ripgrep — recommended for fast content search.

2. Install Mnemo AI

Recommended isolated install:

uv tool install mnemoai-assistant

Alternatives:

pipx install mnemoai-assistant
# or
pip install mnemoai-assistant

The published package name is mnemoai-assistant; the terminal command and Python import package are both mnemoai.

Upgrade later with:

uv tool upgrade mnemoai-assistant
# or: pip install -U mnemoai-assistant

3. First run setup

Start the assistant:

mnemoai

If no config exists, Mnemo AI opens an interactive setup wizard. It asks for:

  • chat model provider and model name;
  • provider connection details, such as Ollama host/port, AWS region, SageMaker input format, LiteLLM API base/key, or Mantle protocol;
  • optional vision and embedding model settings;
  • profile name;
  • optional Brave Search API key;
  • feature toggles such as RAG, memory, web crawling, routing, and orchestration.

The wizard writes your user config to:

~/.mnemoai/config/config.yaml

You can edit that file later or run /config inside Mnemo AI to re-run the configurator.

4. Verify it works

After setup, try a simple prompt:

What files are in the current directory?

If the assistant lists files or uses the file-reading tools, the core loop is working. If something doesn't work, see Troubleshooting.

Useful startup flags:

mnemoai              # verbose mode: shows thinking/reasoning when available
mnemoai --no-verbose # hides thinking/reasoning output

5. Ollama quick setup

For a fully local setup:

ollama pull qwen3.5:4b
mnemoai

If you enable RAG, episodic memory, or ACE playbook refinement, also pull an embedding model and configure it under RAG.EMBED_MODEL_ID:

ollama pull qwen3-embedding:0.6b

Here is a deliberately minimal, everything-off Ollama config — the smallest thing that runs. This is not what the first-run wizard writes: the bundled template (and the shipped config.yaml.example) enable RAG, episodic memory, the playbook, web search, and web crawling by default. Start minimal and switch features on as you need them:

MODEL_ID:
  NAME: qwen3.5:4b
  TYPE: ollama
  HOST: localhost
  PORT: 11434
  TEMPERATURE: 0.6

PROFILE:
  NAME: default

ENABLE_RAG: false
ENABLE_EPISODIC_MEMORY: false
ENABLE_PLAYBOOK: false
ENABLE_WEB_SEARCH: false
ENABLE_WEB_CRAWL: false

To see the full, annotated defaults instead, see the complete example config. For normal installs, save manual configs at ~/.mnemoai/config/config.yaml.

6. Where config files live

Config resolution order, first match wins:

  1. $MNEMOAI_CONFIG — explicit config path.
  2. ~/.mnemoai/config/config.yaml — normal user config for installed mnemoai.
  3. ~/.mnemoai/config.yaml — legacy flat location.
  4. <package>/utils/config.yaml — package-relative fallback, mainly useful for source checkouts.

On first run, Mnemo AI also seeds examples you can copy or inspect:

~/.mnemoai/config/config.yaml.example
~/.mnemoai/config/config.yaml.bedrock.example
~/.mnemoai/config/config.yaml.bedrock.mantle.example
~/.mnemoai/mcp/mcp.json.example

Prompts live separately in:

~/.mnemoai/config/prompts.yaml

Install ripgrep for faster content search:

brew install ripgrep

sudo apt install ripgrep

sudo dnf install ripgrep

Verify:

rg --version

Without ripgrep, Mnemo AI falls back to slower grep-based searches.

8. Developer install from a checkout

Use this path if you want to edit the source.

git clone https://github.com/brunopistone/mnemoai.git
cd mnemoai
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PYTHONPATH=src python -m mnemoai

Or install the checkout as a command:

uv tool install .        # or: pipx install .
mnemoai

For live source edits without reinstalling, keep using:

PYTHONPATH=src python -m mnemoai

You can also use the wrapper under bash/system-command-app/ if you want a mnemoai command that runs your working tree directly.

9. Next steps

  • Learn commands and feature toggles in Usage.
  • Configure providers and advanced model parameters in Configuration.
  • Add RAG, external MCP servers, web tools, memory, and skills — browse the Guides.
  • See Development if you want to run tests or contribute.