mnemo-cortex

Prerequisites (once)

1. Run Mnemo Cortex — locally, in Docker, or on a network box. The bridge is just an HTTP client; the server can be anywhere reachable. See the Install Guide. 2. Clone this repo somewhere your LLM host can reach:

   git clone https://github.com/GuyMannDude/mnemo-cortex.git
   cd mnemo-cortex/integrations/mcp-bridge && npm install
   

The full path to server.js and your Mnemo URL go into each host's config below.

---

Prerequisites

• Python 3.11+ — for the server
• Ollama (recommended) — local reasoning + embedding models, free, fully private. The init wizard also accepts OpenAI / Google / Anthropic / OpenRouter API keys if you'd rather use a cloud model.
• Node.js 18+ (only when running an MCP-bridge integration: Claude Desktop, LM Studio, OpenClaw, etc.)

Memory That Dreams, Compiles, and Connects

Every AI agent has amnesia. Mnemo Cortex fixes that — and then some. Persistent memory that survives across sessions, searches by meaning, and costs $0 to run.

Deploy Your Way

• Shared — One Mnemo for all agents. Cross-agent search and dreaming. Full team awareness.
• Isolated — Separate Mnemo per agent or per customer. Zero bleed between tenants.
• Hybrid — Shared for internal agents + isolated for customer-facing bots. This is what we run.

Cloud memory services make you choose one shared store. Mnemo lets you architect for your actual privacy and separation needs.

---

📚 WikAI — Compiled Knowledge Base

A 3,000+ page wiki layer auto-compiled from Mnemo data. Organized into projects/, entities/, concepts/, and sources/. Searchable through three MCP tools: wiki_search, wiki_read, wiki_index.

The wiki is never edited directly. It's recompiled nightly by mnemo-wiki-compile.py from Mnemo data. Mnemo is the source of truth. The wiki is the study guide. If a page is wrong, fix the source memories in Mnemo and recompile.

The compiler clusters recent memories by topic, passes each cluster + the existing page to gemini-2.5-flash, and writes a fully-rewritten page that integrates the new information without bloating. Cross-references are validated against the live page set — no hallucinated wikilinks. Every page carries a provenance footer listing the Mnemo session IDs that fed it, so any claim is auditable. Per-page failures are isolated; one bad LLM call posts ⚠️ to #alerts and the run continues.

This is the Karpathy/Nate Jones hybrid in production: query-time facts in Mnemo + write-time synthesis in WikAI. Neither Mem0, Zep, nor Letta offer this. See Inspirations below.

---

Install Guide

Five steps from a fresh checkout to a running server connected to your agent. The CLI handles everything — mnemo-cortex init writes the config, mnemo-cortex start launches the API server, mnemo-cortex health verifies, and you point your agent at it via the matching integration.

Step 1: Install

git clone https://github.com/GuyMannDude/mnemo-cortex.git
cd mnemo-cortex
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

This registers two CLI commands: mnemo-cortex and the shorter alias mnemo.

Non-interactive install (for LLM agents and CI)

Skip the wizard — fill out a JSON manifest and run the robot installer.

```bash

Defaults are sensible; only edit robot.install if you want to change them

./robot-install.sh

The script emits a single JSON object on stdout for the caller to parse;
all human-readable progress goes to stderr.

On failure, `ok` is `false`, exit code is `1`, and `error` describes which step blew up.

The manifest covers service port + bind, reasoning + embedding provider,
the v3 provenance/decay thresholds, systemd unit name, and a smoke test
that exercises `/health` plus a save → recall round-trip. API keys are read from the install-time environment
(named in the manifest via `api_key_env`), copied into a 0600-permission
env file alongside the config, and loaded by the systemd unit.

**Sandbox testing** — override paths via env so you can dry-run without touching real state:

DRY_RUN=1 runs the dependency check and reports the paths each step would write, but skips every side effect — no venv, no pip install, no config or env file written, no systemd unit, no smoke test. API keys in the environment are never persisted to disk in dry-run.

Note on scope: robot.install sets up the Mnemo Cortex server. To use Mnemo from an agent (Hermes, Claude Desktop, AnythingLM, LM Studio, Ollama Desktop, Agent-Zero, OpenClaw, Claude Code), run the agent-specific integration installer afterward — see integrations/ for each guide. They wire the agent's MCP config to point at the server you just installed.

Verify Installation

After setup, run the test suite:

cd /path/to/mnemo-cortex
source .venv/bin/activate
pytest tests/test_agentb.py -v

If tests fail, check that all Python dependencies are installed (pip install -e .).

📜 How to Use Mnemo Effectively

Read THE-LANE-PROTOCOL.md — the operating practice for running agents with persistent memory. Feed it to your agent or follow it yourself. It takes 5 minutes per session and makes every cold start feel warm.

The protocol pairs with this product the way a recipe pairs with ingredients: Mnemo gives you the memory store, the Lane Protocol gives you the loop that makes it pay off. Distilled from real multi-agent sessions — terminal agents, chat agents, and autonomous workers running the same six-step ritual.

---

Quick Start

```bash

In your MCP bridge env

export MNEMO_DUMP=on

Optional — default is ~/.mnemo-cortex/dumps

export MNEMO_DUMP_DIR=~/dumps

In your MCP config or systemd unit:

BRAIN_DIR=/absolute/path/to/your/mnemo-plan ```

The bridge auto-enables brain-file tools (read_brain_file, write_brain_file, list_brain_files) when BRAIN_DIR exists. If it doesn't, those tools simply don't register — no install friction.

For the operating practice — when to read what, when to write what, the six-step session ritual — see THE-LANE-PROTOCOL.md.

LobeChat — MCP plugin

In Settings → Plugins → MCP → Add custom MCP server:

---

Jan — MCP via extensions

Jan exposes MCP through its Extensions panel. Settings → Extensions → MCP Servers → Add:

{
  "name": "mnemo-cortex",
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/mnemo-cortex/integrations/mcp-bridge/server.js"],
  "env": {
    "MNEMO_URL": "http://localhost:50001",
    "MNEMO_AGENT_ID": "jan"
  }
}

Restart Jan. Tools appear in the assistant configuration.

---

Step 5: Connect an integration

The server is now running. Pick your platform and follow its integration guide:

Each integration is a one-line MCP config or a drag-and-drop bundle. The server is the same; only the bridge config changes.

For other MCP-capable hosts (Open WebUI, llama.cpp, LobeChat, Jan, generic MCP clients), see Use With Any Local LLM above.

Mnemo Cortex vs OpenClaw Active Memory

OpenClaw 2026.4.10 shipped a native Active Memory plugin. Some people have asked whether it replaces Mnemo Cortex. Short answer: no — they solve different problems. Here's the difference, based on side-by-side testing on a sandbox agent.

Troubleshooting

Recall / cross-agent search returns "No chunks"

Most common cause: your embedding model setting doesn't match your provider's current model name. Model names change — check your provider's docs:

If you recently switched providers or updated your config, verify the model name is correct and that your API key has access to the embedding endpoint.

Health check fails on "Compaction model"

The compaction model (default: qwen2.5:32b-instruct via Ollama) must be running and reachable. Check:

curl http://localhost:11434/v1/models  # List loaded Ollama models

If you're using a remote Ollama instance, set MNEMO_SUMMARY_URL to point to it.

Server unreachable

If mnemo-cortex health can't reach the API, check:

curl http://localhost:50001/health    # Or your MNEMO_URL

Common causes: wrong port, firewall blocking, server not started. On multi-machine setups, ensure the target host's firewall allows the port (e.g., ufw allow from 10.0.0.0/24 to any port 50001).