Metadata-Version: 2.5
Name: mnemos-memory-server
Version: 4.0.0
Summary: Standalone memory & knowledge server for AI agents — forked from ai-brain
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: aiohttp<4.0,>=3.14.1
Requires-Dist: aiosqlite>=0.20
Requires-Dist: apscheduler>=3.10
Requires-Dist: cryptography>=48.0.1
Requires-Dist: fastapi>=0.138.0
Requires-Dist: grpcio-tools<2,>=1.62
Requires-Dist: grpcio<2,>=1.62
Requires-Dist: httpx>=0.28.1
Requires-Dist: huggingface-hub>=0.30
Requires-Dist: idna>=3.15
Requires-Dist: onnxruntime>=1.20
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.0
Requires-Dist: pygments>=2.20.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: pyotp~=2.9
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.0
Requires-Dist: slowapi~=0.1.9
Requires-Dist: starlette<2.0,>=1.3.0
Requires-Dist: tokenizers>=0.21
Requires-Dist: trafilatura>=1.12
Requires-Dist: typer>=0.26.7
Requires-Dist: urllib3>=2.7.0
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: watchdog>=4.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25; extra == 'all'
Requires-Dist: bandit[toml]>=1.7; extra == 'all'
Requires-Dist: google-generativeai>=0.5; extra == 'all'
Requires-Dist: mcp[cli]<3.0,>=2.0; extra == 'all'
Requires-Dist: mypy>=1.11; extra == 'all'
Requires-Dist: ollama>=0.3; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: pip-audit>=2.7; extra == 'all'
Requires-Dist: pymupdf>=1.24; extra == 'all'
Requires-Dist: pytest-asyncio>=0.24; extra == 'all'
Requires-Dist: pytest-cov>=7.0; extra == 'all'
Requires-Dist: pytest>=9.0.3; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: ruff<0.16,>=0.15; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: azure
Requires-Dist: openai>=1.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=7.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == 'docx'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5; extra == 'gemini'
Provides-Extra: mcp
Requires-Dist: mcp[cli]<3.0,>=2.0; extra == 'mcp'
Provides-Extra: ollama
Requires-Dist: ollama>=0.3; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: openvino
Requires-Dist: optimum[openvino]>=1.19; extra == 'openvino'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.24; extra == 'pdf'
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=3.0; extra == 'sentence-transformers'
Provides-Extra: training
Requires-Dist: onnx>=1.17; extra == 'training'
Requires-Dist: sentence-transformers>=3.0; extra == 'training'
Requires-Dist: torch>=2.2; extra == 'training'
Requires-Dist: transformers>=4.51; extra == 'training'
Description-Content-Type: text/markdown

<!-- markdownlint-disable MD041 MD033 -->
<p align="center">
  <img src="docs/assets/mnemos-banner.svg" alt="Mnemos — memory &amp; knowledge server for AI agents" width="100%">
</p>

<h1 align="center">Mnemos</h1>

<p align="center">
  <strong>A memory &amp; knowledge server for AI agents</strong><br>
  <em>named after the Titaness of memory, built for AI agents that need to remember</em>
</p>

<p align="center">
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python"></a>
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/license-Apache_2.0-blue" alt="License: Apache-2.0"></a>
  <a href="https://github.com/Korrnals/mnemos/releases"><img src="https://img.shields.io/github/v/release/Korrnals/mnemos?label=version&color=blueviolet" alt="Version"></a>
</p>

<p align="center">
  <strong>🇬🇧 English</strong> · <a href="README.ru.md">🇷🇺 Русский</a>
</p>

<p align="center">
  <a href="#-features">Features</a> ·
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-what-mnemos-is">What it is</a> ·
  <a href="#%EF%B8%8F-architecture">Architecture</a> ·
  <a href="#%EF%B8%8F-three-surfaces-one-core">Surfaces</a> ·
  <a href="#-documentation">Docs</a>
</p>

---

## ✨ Features

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

| Area | What you get |
|------|--------------|
| **Universal connectivity** | MCP server (26 tools, stdio) + REST API — any MCP-capable harness connects in one line ([tools](docs/en/user/mcp-tools.md) · [HTTP](docs/en/user/http-api.md)) |
| **Ready integrations** | zcode, the `~/.agents` standard (Claude / Codex / Continue / Qwen and more), pi — via [`mnemos integration`](docs/en/user/integration-guide.md): deploy targets, one-line MCP presets, multi-harness doctor |
| **Skill pack** | 14+ memory skills deployed into your harnesses |
| **Flexible memory** | Hybrid search (full-text + vector, rank fusion), [tag contract](docs/en/user/tag-contract.md), per-agent / per-project memory, [context-filter](docs/en/user/context-filter.md) profiles, CCR compression — 70–90% token savings, originals kept |
| **Context assembly** | `assemble_context`: search → compress → filter → secret scan → cache align → token budget, per-block provenance |
| **Context bridge** | `on_context_rewrite` — when the harness compacts history, the lossless original stays available on demand |
| **Lifecycle hooks** | `pre_llm_call` context injection, `on_session_start`, `post_tool_call` auto-compression of tool outputs |
| **Publication v3.0.0** | Entries visible immediately after save, background refinement with seamless swap, quarantine with neutral retraction |
| **Self-protection** | Injection / secret detectors on input and publication, every output scanned, full per-entry audit |
| **Auto-pipeline** | Background processor: clustering, deduplication, quality gate, publication |

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](docs/en/features.md).

---

## 🚀 Quick start

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

### 1 · Install

```bash
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 &amp; recall

```bash
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](docs/en/user/tag-contract.md) (`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:

```bash
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

```bash
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](docs/en/user/integration-guide.md#agent-mcp-wiring)
for wiring flags and the [context filter guide](docs/en/user/context-filter.md)
for the five-stage noise stripper that runs automatically on every `mnemos_add`.

<details>
<summary><strong>🛠️ Other ways to install</strong> — from source, released wheel, or container one-liner</summary>

<br>

**From source** (for development):

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

**Released wheel** (pin a specific version):

<!-- version:pip -->
```bash
pip install https://github.com/Korrnals/mnemos/releases/download/v4.0.0/mnemos_memory_server-4.0.0-py3-none-any.whl
```
<!-- /version:pip -->

**Container one-liner** — pulls the image, creates volumes, starts on port 8787:

```bash
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
```

See the full [container deployment guide](docs/en/admin/runbooks/container-deployment.md).

</details>

<details>
<summary><strong>🐳 Run the pre-built image directly (GHCR)</strong></summary>

<br>

Published to `ghcr.io/korrnals/mnemos` on every release tag.

```bash
# 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
```

<!-- version:tags -->
Tags: `:4.0.0` (pinned) · `:latest` (rolling). Works with `docker` too — swap `podman` for `docker`.
<!-- /version:tags -->

</details>

> 📘 For a guided first run covering the MCP and HTTP servers, see
> [getting-started.md](docs/en/user/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.

|  | Capability | What it gives you |
|---|------------|-------------------|
| 🔎 | **Hybrid search** | Vector similarity + SQLite FTS5 full-text over every memory |
| 🧪 | **Knowledge pipeline** | `raw → processing → processed → published` lifecycle with a state machine |
| 🧠 | **Per-agent recall** | A focused recall surface scoped to each agent's project context |
| ⚙️ | **Policy engine** | Schedule and trigger automation over the memory store |
| 🧹 | **Context filter** | Five-stage noise stripper for logs / stdout before anything hits a model |
| 🗜️ | **Reversible compression (CCR)** | Compress large content with zero data loss — originals cached in SQLite, retrievable via hash marker |
| 🧷 | **CacheAligner (P1-5)** | Relocate dynamic content (timestamps, UUIDs, session ids, tokens) to the tail so provider KV caches (Anthropic `cache_control`, OpenAI prefix caching) hit across requests |
| 🪶 | **Output token reduction (P1-7)** | Optional `verbosity` / `effort` params on `mnemos_add` / `mnemos_search` / `mnemos_recall_context` steer the caller's output style — backward compatible, defaults are a no-op |
| 📂 | **Path-scoped rules** | Ingest project rules and apply them by file path |
| 🗂️ | **Obsidian vault** | A markdown mirror humans can browse, edit, and grep |

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

---

## 🏗️ Architecture

<details open>
<summary><strong>System diagram</strong> — clients → interfaces → core → storage</summary>

<br>

```mermaid
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
```

</details>

A deeper walkthrough — data model, state machines, security boundaries, operational concerns — lives in
[architecture/overview.md](docs/en/architecture/overview.md).

---

## 🎛️ Three surfaces, one core

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

| Surface | Use it when… | Reference |
|---------|--------------|-----------|
| **CLI** — `mnemos …` | You live in a shell, want fast ad-hoc add / search, or are scripting cron jobs | [cli-reference.md](docs/en/user/cli-reference.md) |
| **HTTP** — `mnemos serve` | You have a non-MCP client — a web dashboard, a mobile app, a CI runner | [http-api.md](docs/en/user/http-api.md) |
| **MCP** — `mnemos mcp-server` | You are VS Code Copilot or any MCP-aware agent — the path Copilot agents take | [mcp-tools.md](docs/en/user/mcp-tools.md) |

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](docs/en/architecture/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

| Page | What it covers |
|------|----------------|
| [docs/README.md](docs/README.md) | Documentation landing — language picker (EN / RU) |
| [getting-started.md](docs/en/user/getting-started.md) | First run: install → first memory → first search → MCP / HTTP |
| [architecture/overview.md](docs/en/architecture/overview.md) | System shape, data model, state machines, security boundaries |
| [cli-reference.md](docs/en/user/cli-reference.md) | Every `mnemos` subcommand with flags, defaults, examples |
| [mcp-tools.md](docs/en/user/mcp-tools.md) | Every `mnemos_*` tool exposed to VS Code Copilot |
| [http-api.md](docs/en/user/http-api.md) | Every HTTP endpoint (memory CRUD + A2A Sessions, M16) |
| [a2a-sessions.md](docs/en/architecture/a2a-sessions.md) | Agent-to-agent conversation contract (M16) |
| [tag-contract.md](docs/en/user/tag-contract.md) | The `project:` / `agent:` / `mnemos:` schema enforced on every memory |
| [security.md](docs/en/admin/security.md) | Threat model, SSRF guard, FTS5 escape, HF Hub pinning |
| [runbooks/](docs/en/admin/runbooks/) | Install, migrate, backup / restore, dependency updates |
| [container-deployment.md](docs/en/admin/runbooks/container-deployment.md) | Build, push, compose, podman, Kubernetes, quadlet |
| [adr/](docs/project/adr/) | Architectural decision records — the *why* behind the design |
| [milestones.md](docs/project/milestones.md) | Milestone ledger with status legend |
| [reports/](docs/project/reports/) | Phase completion reports — final report per completed roadmap phase |
| [CHANGELOG.md](CHANGELOG.md) | Release notes — Keep a Changelog format |

---

## 🤝 Integrations

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

| Harness | Native deploy target | One-line MCP preset | Adapter template |
|---------|----------------------|---------------------|------------------|
| VS Code Copilot | `copilot` (+ prompts via `generic-copilot`) | [mcp-setup.sh](scripts/mcp-setup.sh) | ✓ |
| Claude Code | via `agents` | [preset](integrations/mcp-presets.md#claude-code) | ✓ |
| Cursor | `cursor` | [preset](integrations/mcp-presets.md#cursor) | ✓ |
| Codex | via `agents` | [preset](integrations/mcp-presets.md#codex) | ✓ |
| Windsurf | — | [preset](integrations/mcp-presets.md#windsurf) | ✓ |
| ZCode | `zcode` | — | ✓ |
| Any AGENTS.md-standard harness | `agents` | — | ✓ |
| [Hermes Agent](https://hermes-agent.nousresearch.com/) | `hermes` (native `MemoryProvider` plugin) | — | — |

- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** — 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](docs/en/user/integration-guide.md#hermes-agent).
- **Native targets** — `mnemos integration setup --target <name>` deploys the
  behavioral pack and registers the MCP server in one pass. See the
  [integration guide](docs/en/user/integration-guide.md).
- **One-line MCP presets** — [`integrations/mcp-presets.md`](integrations/mcp-presets.md):
  connect Cursor, Claude Code, Codex, or Windsurf by pasting one line.
- **Adapter template** — [`integrations/adapter-template.md`](integrations/adapter-template.md):
  Connect / Expose / Configure + acceptance checklist for any harness that
  speaks MCP stdio.

The shared contract is the [tag schema](docs/en/user/tag-contract.md) — `project:<slug>`, `agent:<slug>`,
and at least one `mnemos:<subtype>` — that every memory entry must carry.

---

## ⚖️ Source &amp; license

- **Source** — this repository, [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
- **License** — Apache-2.0 (see [LICENSE](LICENSE)).

## 🌱 Contributing

PRs welcome. Read [PLAN.md](PLAN.md) for the roadmap and follow the conventions in the [docs/](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.

---

<p align="center">
  <sub><strong>Reproduce the green state:</strong> <code>make verify</code> runs the full quality gate
  — ruff + mypy --strict + bandit + pip-audit + 867 tests. If it's green, the change is good to ship.</sub>
</p>
