Mnemos

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

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

Quick start · Features · What it is · Connect a harness · Architecture · Docs

AI agents forget everything when a session ends. Mnemos gives them a place to lay it down — structured, searchable, governed by contract — so what they learn does not vanish with the closing of a window.

• Local-first. One process on your machine. SQLite + a bundled embedding model; nothing leaves the host, no API keys, works offline.
• One server, any harness. VS Code Copilot, Claude Code, Cursor, OpenCode, Codex, Windsurf, ZCode, pi, Hermes — the same MCP wire, one line each.
• The agent learns to use it. Not just tools: always-on instructions, a skill pack, and a memory-first prompt mode, deployed into your harness in one command.

🚀 Quick start

Three commands from an empty machine to an agent that remembers — and knows when to look.

1 · Install the server

pip install mnemos-memory-server

One package, everything included: the memory server, the mnemos CLI, the REST API, and the MCP server your agent harness talks to. The embedding model ships inside — search works fully offline, no API keys, nothing downloaded.

⚠️ Mind the name: pip install mnemos (without -memory-server) is an unrelated project.

2 · Connect your harness — and teach it to use memory

mnemos integration setup

One pass: detects the agent harnesses on your machine, registers the Mnemos MCP server in each supported one (VS Code Copilot, Cursor, ZCode, OpenCode, pi, Hermes, and everything reading the ~/.agents standard — Claude Code, Codex and friends), and deploys the behavioral pack — always-on instructions and memory skills, so the agent recalls at session start, checkpoints before its context gets compacted, and treats memory as a priority instead of forgetting the tools exist.

Running a harness that reads nothing standard? One paste block per harness: Connect Mnemos to any harness.

3 · Verify — then try it

mnemos doctor

PASS / WARN / FAIL per check: store, config, MCP transport, harness registration (--fix repairs the common warnings). Then give it a memory:

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

That is the whole loop: write, find, never lose it — and the agent knows when to look.

📘 Want every detail? The extended guide covers all install variants (uv tool, pipx, CLI-only, external LLM extras, installer script, container), per-harness connection walkthroughs, configuration, and troubleshooting: Getting Started — the complete first run.

✨ Features

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

Autonomy for an arbitrary harness and LLM-driven enrichment are partial — the full, honest map lives in docs/en/features.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.

🤝 Connect any harness

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

• Native targets — mnemos integration setup --target <name> deploys the behavioral pack and registers the MCP server in one pass (integration guide).
• One-line presets — integrations/mcp-presets.md: every harness above, copy-paste ready.
• Adapter template — integrations/adapter-template.md: Connect / Expose / Configure + acceptance checklist for any harness that speaks MCP stdio.
• Hermes Agent runs Mnemos in-process: pip install mnemos-memory-server in the Hermes environment, then mnemos integration setup --target hermes (details).

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

🏗️ Architecture

flowchart TB
    subgraph CLIENTS["Clients"]
        C1(["Agent harness\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 HTTP surface also exposes the A2A Sessions API — a persistent backend for multi-step agent conversations that survive restarts. See a2a-sessions.md.

📚 Documentation

📖 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.

⚖️ License & contributing

Apache-2.0 — see LICENSE and NOTICE. Source: github.com/Korrnals/mnemos.

Contributions are welcome — CONTRIBUTING.md has the development setup, the branch and commit conventions, and the quality gate a change must pass.