How to Install & Use Aperio‐lite?

How to Install & Use Aperio-lite?

Aperio-lite is the zero-terminal, zero-configuration version of Aperio.
Download, unzip, double-click — you're running.

---

Prerequisites

• macOS (Apple Silicon or Intel), Windows (x64), or Linux (x64)
• 8 GB RAM minimum (16 GB recommended)
• About 2 GB of free disk space for the app + model

No Docker, no API keys, no command line needed.

---

Step 1 – Download

Get the latest aperio-lite.zip from the releases page.

📦 The zip includes Aperio-lite itself plus all required dependencies.

Step 2 – Unzip

Double-click the zip to extract the folder.

Step 3 – Launch

Inside the folder, double-click START (or START.bat on Windows).

A browser window will open at http://localhost:31337 with a setup wizard that:

1. Checks your system
2. Downloads the best AI model for your RAM (no manual selection needed)
3. Initializes the database
4. Opens the chat interface

That's it. No configuration files. No terminal commands.

---

What Aperio-lite gives you

• Chat with persistent memory — the agent remembers you across conversations
• MCP server — expose your memory to other AI agents (Cursor, Windsurf, Claude Desktop, etc.)
• Local AI — everything runs on your machine using the vendored llama.cpp engine
• Local embeddings — powered by @huggingface/transformers, no API calls

---

How to use it

Chat interface

Type naturally. Aperio remembers:

• remember that I prefer Python over JavaScript — saves a preference
• What did I say about my preferred language? — recalls from memory
• Save this as a wiki article about my setup — writes to persistent wiki

Available commands

In the chat, type /help for the full command list. Key ones:

Command	What it does
/remember <text>	Save to memory (or just say "remember that...")
/memories	Browse your saved memories
/self	Read agent's own memory store
/forget <id>	Delete a specific memory
/help <command>	Detailed docs (e.g. /help attach)
/lang <code>	Switch interface language (e.g. /lang de)
/restart	Start a fresh conversation
/discuss on	Enable two-agent cross-review mode
/model <provider> <model>	Switch AI model on the fly

MCP (Model Context Protocol)

Aperio-lite runs an MCP server that other AI agents can connect to. Configure your MCP host (Claude Desktop, Cursor, Windsurf, CodeWhale, etc.):

{
  "mcpServers": {
    "aperio": {
      "command": "node",
      "args": ["/path/to/aperio-lite/mcp/index.js"]
    }
  }
}

The MCP server gives external agents access to your memory, wiki, file system, web search, and more.

---

Troubleshooting

Q: The browser doesn't open automatically
Open http://localhost:31337 manually.

Q: Nothing happens when I double-click START
Run START from a terminal to see error output. Common issues:

• Port 31337 is already in use (change it in the wizard)
• Antivirus blocking the app

Q: How do I update Aperio-lite?
Download the latest zip and extract over your existing folder. Your memories are stored separately and preserved.

Q: Can I switch to a cloud AI provider?
Yes — once running, open the Settings overlay in the sidebar and change AI_PROVIDER. You'll need an API key for the selected provider.

---

See also

• Commands — full command reference
• MCP Tools Guide — how to use MCP tools
• Troubleshooting — common issues