Mnemos

A memory & knowledge server for AI agents
named after the Titaness of memory, built for AI agents that need to remember

🇬🇧 English · 🇷🇺 Русский

Features · Quick start · What it is · Architecture · Surfaces · Docs

✨ Features

One local server — and a connected agent harness gets the full memory stack.

Autonomy for an arbitrary harness, LLM-driven enrichment, and package publishing (PyPI / npm) are partial — the full, honest map lives in docs/en/features.md.

🚀 Quick start

Four steps to a working memory store, wired into VS Code Copilot.

1 · Install

curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash

The installer does everything for you — no Python or venv knowledge required:

• creates an isolated environment at ~/.mnemos/venv;
• drops a mnemos launcher into ~/.local/bin, so the CLI just works in any shell (no venv activation needed);
• offers to wire up VS Code MCP integration right there (or run it later — see step 3).

Prefer a non-interactive run? Add --mcp / --no-mcp to decide up front, e.g. … | bash -s -- --mcp.

2 · Write & recall

mnemos add "First memory — Mnemos remembers across sessions" \
  --tags project:mnemos,agent:tech-writer,mnemos:learning

mnemos search "remembers across sessions"

That's the whole loop: write, find, never lose it. Every entry carries a tag contract (project: / agent: / mnemos:) so memories stay organised.

3 · Connect VS Code (MCP)

If you answered yes during install, you're already done — just reload your VS Code window. To set it up manually, or on another machine:

curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/mcp-setup.sh | bash

Then reload the VS Code window (Ctrl+Shift+P → Reload Window). The mnemos_* tools appear in Copilot's tool picker, and your agents can call mnemos_add / mnemos_search directly.

4 · Deploy behavioral instructions

mnemos integration setup

This deploys memory-usage instructions, skills, and a prompt mode to your agent harness (Copilot ~/.copilot/, generic Copilot, Cursor, and Hermes Agent ~/.hermes/), plus two universal targets: zcode (native ~/.zcode/ skills + MCP config) and agents (the AGENTS.md standard ~/.agents/ — read natively by ZCode, Claude Code, Codex, Cursor and friends). Agents will now know when and how to use Mnemos memory — not just have the tools available. Use --home <dir> to install into another environment's home (e.g. a container).

Add --wire-agents --all to also grant mnemos/* tools to Copilot agent frontmatter in the same pass. See the integration guide for wiring flags and the context filter guide for the five-stage noise stripper that runs automatically on every mnemos_add.

git clone https://github.com/Korrnals/mnemos.git
cd mnemos
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

pip install https://github.com/Korrnals/mnemos/releases/download/v4.0.0/mnemos_memory_server-4.0.0-py3-none-any.whl

export MNEMOS_API__TOTP_MASTER_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash -s -- --container

# Generate a TOTP master key (required — the container binds 0.0.0.0)
export MNEMOS_API__TOTP_MASTER_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")

podman run -d --name mnemos \
  -p 8787:8787 \
  -v mnemos-data:/data \
  -v mnemos-vault:/vault \
  -e MNEMOS_API__TOTP_MASTER_KEY="${MNEMOS_API__TOTP_MASTER_KEY}" \
<!-- version:image -->
  ghcr.io/korrnals/mnemos:4.0.0
<!-- /version:image -->

curl -s http://localhost:8787/health | jq

📘 For a guided first run covering the MCP and HTTP servers, see getting-started.md.

🧩 What Mnemos is

A single-tenant, local-first memory server for AI agents. One in-process core, three equivalent control surfaces, and a storage layer you can read with your own eyes.

SQLite for metadata, a local numpy + SQLite vector index for recall, and an Obsidian-compatible vault for the humans in the loop.

🏗️ Architecture

flowchart TB
    subgraph CLIENTS["Clients"]
        C1(["VS Code · Copilot\nstdio MCP"])
        C2(["CLI — mnemos …"])
        C3(["HTTP API client"])
    end

    subgraph IFACE["Interface Layer"]
        MCP["mcp_server.py"]
        FAPI["api/main.py · FastAPI"]
        TYPER["cli/main.py · Typer"]
    end

    MGR(["MemoryManager\nmanager.py"])

    subgraph PROC["Processing Subsystems"]
        CF["Context Filter\nfilter/"]
        PP["Knowledge Pipeline\npipeline/"]
        RE["Recall Engine\nrecall/"]
        PE["Policy Engine\npolicy/"]
    end

    subgraph BG["Background Services"]
        WA["Watchers\nwatchers/"]
        AC["Auto-collect\nauto_collect.py"]
    end

    subgraph STORE["Storage Layer"]
        SQ[("SQLite\nFTS5 · traces · projects")]
        VS[("Vector Store\nnumpy + SQLite")]
        VLT[("Obsidian Vault\nmarkdown mirror")]
    end

    C1 -->|"stdio"| MCP
    C2 --> TYPER
    C3 --> FAPI
    MCP --> MGR
    TYPER --> MGR
    FAPI --> MGR
    MGR --> CF
    MGR --> PP
    MGR --> RE
    MGR --> SQ
    MGR --> VS
    MGR --> VLT
    CF -.->|"raw + clean"| SQ
    PP -->|"status transitions"| SQ
    PP -->|"published upsert"| VS
    RE -->|"FTS5 MATCH"| SQ
    RE -->|"cosine search"| VS
    PE -->|"schedule / trigger"| MGR
    WA -->|"file events"| MGR
    AC -.->|"checkpoint reminder"| MCP

A deeper walkthrough — data model, state machines, security boundaries, operational concerns — lives in architecture/overview.md.

🎛️ Three surfaces, one core

The same MemoryManager powers all three interfaces. Pick the one that fits your client.

The MCP surface also exposes the A2A Sessions API (M16) — a persistent backend for multi-step agent conversations. Five endpoints (POST /v1/sessions, append-turn, range-load, …) let agents survive restarts without losing context. See a2a-sessions.md.

📖 The lore

In Hesiod's Theogony, Mnemosyne (Μνημοσύνη) is the Titaness of memory — she who, by Zeus, gave birth to the nine Muses and through them made the world's remembering possible. Her name is the root of mnemonic, and she is what every singer, poet, and philosopher prays to before they begin.

This software carries her name because it is built for the same task: to make remembering possible for the things that think. AI agents, unmoored from any single conversation, lose everything that came before. Mnemos gives them a place to lay it down — structured, searchable, governed by contract — so that what they learn does not vanish with the closing of a session. The Muses, after all, were not for the gods' benefit. They were for the songs.

📚 Documentation

🤝 Integrations

Mnemos works with every MCP-capable agent harness. Three integration levels — pick the strongest one your harness supports:

• Hermes Agent — native MemoryProvider plugin (integrations/hermes/): automatic prefetch, sync-turn, built-in memory mirroring. Since plugin 3.0.0 (ADR-0017 D1) the plugin runs in-process — it needs pip install mnemos-memory-server in the Hermes Python environment, and the legacy base_url / api_key / totp_secret config keys are gone. See the integration guide.
• Native targets — mnemos integration setup --target <name> deploys the behavioral pack and registers the MCP server in one pass. See the integration guide.
• One-line MCP presets — integrations/mcp-presets.md: connect Cursor, Claude Code, Codex, or Windsurf by pasting one line.
• Adapter template — integrations/adapter-template.md: Connect / Expose / Configure + acceptance checklist for any harness that speaks MCP stdio.

The shared contract is the tag schema — project:<slug>, agent:<slug>, and at least one mnemos:<subtype> — that every memory entry must carry.

⚖️ Source & license

• Source — this repository, github.com/Korrnals/mnemos.
• License — Apache-2.0 (see LICENSE).

🌱 Contributing

PRs welcome. Read PLAN.md for the roadmap and follow the conventions in the docs/ set.

Git workflow: feat/* → dev-<stage> → release/X.Y.Z → main; main accepts only release/* and hotfix/* PRs. Conventional Commits required. Run make verify before opening a PR.

_{Reproduce the green state: make verify runs the full quality gate — ruff + mypy --strict + bandit + pip-audit + 867 tests. If it's green, the change is good to ship.}