npm - @korrlabs/mnemospi - Versions diffs - 4.0.0 → 4.2.0 - Mend

@korrlabs/mnemospi 4.0.0 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +124 -194
package/README.ru.md +143 -206
package/integrations/extensions/mnemos-mcp.ts +25 -0
package/package.json +9 -1

package/README.md CHANGED Viewed

@@ -11,6 +11,8 @@
 </p>
 <p align="center">
+  <a href="https://pypi.org/project/mnemos-memory-server/"><img src="https://img.shields.io/pypi/v/mnemos-memory-server?label=pypi&color=3776ab" alt="PyPI"></a>
+  <a href="https://www.npmjs.com/package/pi-mnemos"><img src="https://img.shields.io/npm/v/pi-mnemos?label=npm&color=cb3837" alt="npm"></a>
   <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>
@@ -21,166 +23,101 @@
 </p>
 <p align="center">
-  <a href="#-features">Features</a> ·
   <a href="#-quick-start">Quick start</a> ·
+  <a href="#-features">Features</a> ·
   <a href="#-what-mnemos-is">What it is</a> ·
+  <a href="#-connect-any-harness">Connect a harness</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 |
+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.
-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).
+- **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
-Four steps to a working memory store, wired into VS Code Copilot.
-### 1 · Install
+Three commands from an empty machine to an agent that remembers — and knows when to look.
-```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
+### 1 · Install the server
 ```bash
-mnemos add "First memory — Mnemos remembers across sessions" \
-  --tags project:mnemos,agent:tech-writer,mnemos:learning
-mnemos search "remembers across sessions"
+pip install mnemos-memory-server
 ```
-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
-```
+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.
-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.
+> ⚠️ Mind the name: `pip install mnemos` (without `-memory-server`) is an unrelated project.
-### 4 · Deploy behavioral instructions
+### 2 · Connect your harness — and teach it to use memory
 ```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).
+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.
-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`.
+Running a harness that reads nothing standard? One paste block per harness:
+[Connect Mnemos to any harness](integrations/mcp-presets.md).
-<details>
-<summary><strong>🛠️ Other ways to install</strong> — from source, released wheel, or container one-liner</summary>
-<br>
+### 3 · Verify — then try it
-**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
+mnemos doctor
 ```
-<!-- /version:pip -->
-**Container one-liner** — pulls the image, creates volumes, starts on port 8787:
+PASS / WARN / FAIL per check: store, config, MCP transport, harness registration (`--fix`
+repairs the common warnings). Then give it a memory:
 ```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
+mnemos add "First memory — Mnemos remembers across sessions" \
+  --tags project:mnemos,agent:me,mnemos:learning
+mnemos search "remembers across sessions"
 ```
-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>
+That is the whole loop: **write, find, never lose it — and the agent knows when to look.**
-<br>
+> 📘 **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](docs/en/user/getting-started.md)**.
-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
-```
+## ✨ Features
-<!-- version:tags -->
-Tags: `:4.0.0` (pinned) · `:latest` (rolling). Works with `docker` too — swap `podman` for `docker`.
-<!-- /version:tags -->
+One local server — and a connected agent harness gets the full memory stack.
-</details>
+| 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** | VS Code Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, ZCode, pi, Hermes Agent — one-line MCP presets for all of them, [native deploy targets](docs/en/user/integration-guide.md) for most, multi-harness doctor (`mnemos doctor`) |
+| **Skill pack** | 14+ memory skills deployed into your harnesses |
+| **Flexible memory** | Hybrid search (full-text + vector, rank fusion) over the bundled offline model `mnema-embed-v1`, [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. Entries awaiting refinement sit at `pipeline_state=pending` until the processor runs — in CLI-only deployments (no daemon) start it with `mnemos processor start`; `mnemos doctor` reports the pending-queue depth |
-> 📘 For a guided first run covering the MCP and HTTP servers, see
-> [getting-started.md](docs/en/user/getting-started.md).
+Autonomy for an arbitrary harness and LLM-driven enrichment are partial — the
+full, honest map lives in [docs/en/features.md](docs/en/features.md).
 ---
@@ -197,14 +134,55 @@ control surfaces, and a storage layer you can read with your own eyes.
 | ⚙️ | **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 |
+| 🧷 | **CacheAligner** | 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** | 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.
+**Where this is going.** The shipped, measured rung is *stores and finds*. The next rungs —
+*collapse with checks* (session → project → cross-project synthesis: automatic by default, but never
+unconditional in authority — every derivative traces back to its sources, nothing pins without an
+operator) and, later, *builds understanding* — open only as pre-registered experiments prove them
+([ADR-0025](docs/project/adr/0025-memory-meta-level-lanes.md)). The invariant on that road is
+**zero silent losses**: a fact is either retained, or its loss is visible. And the shape of the
+ambition is a *nervous system, not a conductor* — memory that surfaces the right thing at the right
+moment, never one that conducts the agent.
+---
+## 🤝 Connect any harness
+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) | ✓ |
+| OpenCode | — | [preset](integrations/mcp-presets.md#opencode) | ✓ |
+| ZCode | `zcode` | — | ✓ |
+| Any AGENTS.md-standard harness | `agents` | — | ✓ |
+| pi | `pi` (bridge extension, also on npm as [`pi-mnemos`](https://www.npmjs.com/package/pi-mnemos)) | [preset](integrations/mcp-presets.md#pi) | ✓ |
+| [Hermes Agent](https://hermes-agent.nousresearch.com/) | `hermes` (native in-process `MemoryProvider` plugin) | — | — |
+- **Native targets** — `mnemos integration setup --target <name>` deploys the behavioral pack and
+  registers the MCP server in one pass ([integration guide](docs/en/user/integration-guide.md)).
+- **One-line presets** — [`integrations/mcp-presets.md`](integrations/mcp-presets.md): every harness
+  above, copy-paste ready.
+- **Adapter template** — [`integrations/adapter-template.md`](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](docs/en/user/integration-guide.md#hermes-agent)).
+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.
 ---
 ## 🏗️ Architecture
@@ -217,7 +195,7 @@ for the humans in the loop.
 ```mermaid
 flowchart TB
     subgraph CLIENTS["Clients"]
-        C1(["VS Code · Copilot\nstdio MCP"])
+        C1(["Agent harness\nstdio MCP"])
         C2(["CLI — mnemos …"])
         C3(["HTTP API client"])
     end
@@ -283,27 +261,12 @@ The same `MemoryManager` powers all three interfaces. Pick the one that fits you
 | Surface | Use it when… | Reference |
 |---------|--------------|-----------|
+| **MCP** — `mnemos mcp-server` | You are an agent harness — the path every connected agent takes | [mcp-tools.md](docs/en/user/mcp-tools.md) |
 | **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.
+The HTTP surface also exposes the **A2A Sessions API** — a persistent backend for multi-step agent
+conversations that survive restarts. See [a2a-sessions.md](docs/en/architecture/a2a-sessions.md).
 ---
@@ -312,73 +275,40 @@ gods' benefit. They were for the songs.
 | 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 |
+| [getting-started.md](docs/en/user/getting-started.md) | First run: install → first memory → first search → connect your harness |
+| [mcp-presets.md](integrations/mcp-presets.md) | Connect Mnemos to any harness — one-line MCP presets (VS Code, Claude Code, Cursor, OpenCode, Codex, Windsurf, pi, Hermes) |
+| [integration-guide.md](docs/en/user/integration-guide.md) | The behavioral pack: instructions, skills, prompt mode, deploy targets, agent wiring, Hermes plugin |
+| [features.md](docs/en/features.md) | What works out of the box, what is partial, what is planned |
 | [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) |
+| [mcp-tools.md](docs/en/user/mcp-tools.md) | Every `mnemos_*` tool exposed to agent harnesses |
+| [http-api.md](docs/en/user/http-api.md) | Every HTTP endpoint (memory CRUD, workflow, hooks, A2A Sessions) |
 | [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 |
+| [security.md](docs/en/admin/security.md) | Threat model, SSRF guard, FTS5 escape, auth model |
+| [runbooks/](docs/en/admin/runbooks/) | Install, migrate, backup / restore, dependency updates, container deployment |
 | [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 |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, git workflow, quality gate |
 ---
-## 🤝 Integrations
-Mnemos works with every MCP-capable agent harness. Three integration levels —
-pick the strongest one your harness supports:
+## 📖 The lore
-| 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.
+> 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.
-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.
+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.
 ---
-## ⚖️ Source &amp; license
+## ⚖️ License &amp; contributing
-- **Source** — this repository, [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
-- **License** — Apache-2.0 (see [LICENSE](LICENSE)).
+Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Source: [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
-## 🌱 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>
+Contributions are welcome — [CONTRIBUTING.md](CONTRIBUTING.md) has the development setup, the branch
+and commit conventions, and the quality gate a change must pass.

package/README.ru.md CHANGED Viewed

@@ -7,10 +7,12 @@
 <p align="center">
   <strong>Сервер памяти и знаний для AI-агентов</strong><br>
-  <em>назван в честь титаниды памяти, создан для AI-агентов, которым нужна память</em>
+  <em>назван в честь титаниды памяти, создан для агентов, которым нужно помнить</em>
 </p>
 <p align="center">
+  <a href="https://pypi.org/project/mnemos-memory-server/"><img src="https://img.shields.io/pypi/v/mnemos-memory-server?label=pypi&color=3776ab" alt="PyPI"></a>
+  <a href="https://www.npmjs.com/package/pi-mnemos"><img src="https://img.shields.io/npm/v/pi-mnemos?label=npm&color=cb3837" alt="npm"></a>
   <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>
@@ -21,160 +23,101 @@
 </p>
 <p align="center">
-  <a href="#-возможности">Возможности</a> ·
   <a href="#-быстрый-старт">Быстрый старт</a> ·
+  <a href="#-возможности">Возможности</a> ·
   <a href="#-что-такое-mnemos">Что это</a> ·
+  <a href="#-подключение-любого-харнеса">Подключить харнес</a> ·
   <a href="#%EF%B8%8F-архитектура">Архитектура</a> ·
-  <a href="#%EF%B8%8F-три-поверхности-одно-ядро">Поверхности</a> ·
   <a href="#-документация">Документация</a>
 </p>
 ---
-## ✨ Возможности
+AI-агенты забывают всё, когда сессия заканчивается. Mnemos даёт им место, куда это можно
+положить — структурированно, с поиском, по контракту — чтобы то, что агент узнал, не исчезало
+с закрытием окна.
-Один локальный сервер — и подключённый агентский харнес получает полный стек памяти.
-| Область | Что даёт |
-|---------|----------|
-| **Универсальное подключение** | MCP-сервер (26 инструментов, stdio) + REST API — любой харнесс с поддержкой MCP подключается одной строкой ([инструменты](docs/ru/user/mcp-tools.md) · [HTTP](docs/ru/user/http-api.md)) |
-| **Готовые интеграции** | zcode, стандарт `~/.agents` (Claude / Codex / Continue / Qwen и др.), pi — через [`mnemos integration`](docs/ru/user/integration-guide.md): таргеты развёртывания, однострочные MCP-пресеты, доктор мульти-харнесов |
-| **Пакет скиллов** | 14+ скиллов памяти деплоятся в харнесы |
-| **Гибкая память** | Гибридный поиск (полнотекстовый + векторный, слияние ранжирования), [теги-контракт](docs/ru/user/tag-contract.md), память по агентам и проектам, профили [контекстного фильтра](docs/ru/user/context-filter.md), сжатие CCR — экономия 70–90% токенов, оригиналы сохраняются |
-| **Сборка контекста** | `assemble_context`: поиск → сжатие → фильтр → скан секретов → выравнивание кэша → бюджет токенов, провенанс каждого блока |
-| **Мост контекста** | `on_context_rewrite` — при сжатии истории харнессом оригинал без потерь доступен по требованию |
-| **Хуки жизненного цикла** | `pre_llm_call` (впрыск контекста перед запросом модели), `on_session_start`, `post_tool_call` (авто-сжатие выводов инструментов) |
-| **Публикация v3.0.0** | Запись видна сразу после сохранения, фоновая дообработка с бесшовной подменой, карантин с нейтральной ретракцией |
-| **Автозащита** | Детекторы инъекций / секретов на входе и публикации, скан каждой выдачи, полный аудит с привязкой к записи |
-| **Автоконвейер** | Фоновый обработчик: кластеризация, дедупликация, гейт качества, публикация |
-Автономность для произвольного харнесса, LLM-дообогащение и публикация пакетов
-(PyPI / npm) — частично; полная честная карта: [docs/ru/features.md](docs/ru/features.md).
+- **Локальность прежде всего.** Один процесс на вашей машине. SQLite + встроенная модель эмбеддингов; ничего не покидает хост, без API-ключей, работает офлайн.
+- **Один сервер, любой харнес.** VS Code Copilot, Claude Code, Cursor, OpenCode, Codex, Windsurf, ZCode, pi, Hermes — один и тот же MCP-провод, одна строка на каждого.
+- **Агент учится этим *пользоваться*.** Не только инструменты: always-on инструкции, пакет скиллов и режим промпта «память прежде всего», разворачиваемые в ваш харнес одной командой.
 ---
 ## 🚀 Быстрый старт
-Четыре шага до рабочего хранилища памяти, подключённого к VS Code Copilot.
+Три команды от пустой машины до агента, который помнит — и знает, когда заглянуть.
-### 1 · Установка
+### 1 · Установите сервер
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash
+pip install mnemos-memory-server
 ```
-Установщик делает всё за вас — знание Python или venv не требуется:
-- создаёт изолированное окружение в `~/.mnemos/venv`;
-- кладёт лаунчер `mnemos` в `~/.local/bin`, чтобы CLI работал в любом шелле (**активировать venv не нужно**);
-- тут же предлагает настроить интеграцию VS Code MCP (или сделайте это позже — см. шаг 3).
+Всё в одном пакете: сервер памяти, CLI `mnemos`, REST API и MCP-сервер, с которым разговаривает
+ваш агентский харнес. Модель эмбеддингов встроена — поиск работает полностью офлайн,
+без API-ключей и без загрузок.
-> Нужен неинтерактивный запуск? Добавьте `--mcp` / `--no-mcp`, чтобы выбрать заранее, например
-> `… | bash -s -- --mcp`.
+> ⚠️ Не перепутайте имя: `pip install mnemos` (без `-memory-server`) — посторонний проект.
-### 2 · Запись и поиск
-```bash
-mnemos add "Первая запись — Mnemos помнит между сессиями" \
-  --tags project:mnemos,agent:tech-writer,mnemos:learning
-mnemos search "помнит между сессиями"
-```
-Это весь цикл: **записал, нашёл, не потерял.** Каждая запись несёт
-[контракт тегов](docs/ru/user/tag-contract.md) (`project:` / `agent:` / `mnemos:`), чтобы память оставалась упорядоченной.
-### 3 · Подключение к VS Code (MCP)
-Если во время установки вы ответили **да** — всё готово, просто перезагрузите окно VS Code.
-Чтобы настроить вручную или на другой машине:
-```bash
-curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/mcp-setup.sh | bash
-```
-Затем **перезагрузите окно VS Code** (`Ctrl+Shift+P → Reload Window`). Инструменты `mnemos_*` появятся
-в палитре инструментов Copilot, и агенты смогут вызывать `mnemos_add` / `mnemos_search` напрямую.
-### 4 · Установка поведенческих инструкций
+### 2 · Подключите харнес — и научите его пользоваться памятью
 ```bash
 mnemos integration setup
 ```
-Развёртывает инструкции использования памяти, скилы и режим промпта в ваш
-агентский харнес (Copilot `~/.copilot/`, обычный Copilot, Cursor). Агенты теперь
-*знают когда и как* использовать память Mnemos — а не просто имеют инструменты.
-Добавьте `--wire-agents --all`, чтобы в том же проходе выдать инструменты
-`mnemos/*` во фронтматтер Copilot-агентов. См. [руководство по интеграции](docs/ru/user/integration-guide.md#подключение-mcp-инструментов-к-агентам)
-по флагам wiring и [руководство по контекстному фильтру](docs/ru/user/context-filter.md)
-— пятиступенчатый очиститель шума, который запускается автоматически при каждом `mnemos_add`.
-<details>
-<summary><strong>🛠️ Другие способы установки</strong> — из исходников, готовый wheel или контейнер</summary>
-<br>
-**Из исходников** (для разработки):
+Один проход: находит агентские харнесы на вашей машине, регистрирует MCP-сервер Mnemos в каждом
+поддерживаемом харнесе (VS Code Copilot, Cursor, ZCode, OpenCode, pi, Hermes и всё, что читает
+стандарт `~/.agents`, — Claude Code, Codex и друзья) и разворачивает **поведенческий пакет** —
+always-on инструкции и скиллы памяти, чтобы агент вспоминал в начале сессии, делал чекпоинт
+до того, как его контекст сожмут, и относился к памяти как к приоритету, а не забывал,
+что инструменты существуют.
-```bash
-git clone https://github.com/Korrnals/mnemos.git
-cd mnemos
-uv venv && source .venv/bin/activate
-uv pip install -e ".[dev]"
-```
+Харнес, который не читает ничего стандартного? Один блок для копипаста на каждый:
+[Подключите Mnemos к любому харнесу](integrations/mcp-presets.md).
-**Готовый wheel** (зафиксировать конкретную версию):
+### 3 · Проверьте — и попробуйте
-<!-- 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
+mnemos doctor
 ```
-<!-- /version:pip -->
-**Контейнер одной командой** — скачивает образ, создаёт тома, запускает на порту 8787:
+PASS / WARN / FAIL по каждой проверке: хранилище, конфиг, MCP-транспорт, регистрация харнесов
+(`--fix` чинит типовые предупреждения). Затем дайте ему память:
 ```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
+mnemos add "Первая запись — Mnemos помнит между сессиями" \
+  --tags project:mnemos,agent:me,mnemos:learning
+mnemos search "помнит между сессиями"
 ```
-Полное руководство — [container-deployment.md](docs/ru/admin/runbooks/container-deployment.md).
-</details>
-<details>
-<summary><strong>🐳 Запуск готового образа напрямую (GHCR)</strong></summary>
+Это весь цикл: **записал, нашёл, не потерял — и агент знает, когда заглянуть в память.**
-<br>
+> 📘 **Хотите каждую деталь?** Расширенный гид покрывает все варианты установки (`uv tool`, `pipx`,
+> только CLI, внешние LLM-экстры, скрипт-установщик, контейнер), пошаговое подключение каждого
+> харнеса, конфигурацию и разбор неполадок:
+> **[Начало работы — полное руководство](docs/ru/user/getting-started.md)**.
-Образ публикуется в `ghcr.io/korrnals/mnemos` при каждом release-теге.
+---
-```bash
-# Сгенерируйте TOTP-ключ (обязательно — контейнер слушает 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 -->
-Теги: `:4.0.0` (фиксированная) · `:latest` (rolling). Работает и с `docker` — замените `podman` на `docker`.
-<!-- /version:tags -->
+Один локальный сервер — и подключённый агентский харнес получает полный стек памяти.
-</details>
+| Область | Что даёт |
+|---------|----------|
+| **Универсальное подключение** | MCP-сервер (26 инструментов, stdio) + REST API — любой харнесс с поддержкой MCP подключается одной строкой ([инструменты](docs/ru/user/mcp-tools.md) · [HTTP](docs/ru/user/http-api.md)) |
+| **Готовые интеграции** | VS Code Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, ZCode, pi, Hermes Agent — однострочные MCP-пресеты для всех, [нативные таргеты развёртывания](docs/ru/user/integration-guide.md) для большинства, мульти-харнесный доктор (`mnemos doctor`) |
+| **Пакет скиллов** | 14+ скиллов памяти разворачиваются в ваши харнесы |
+| **Гибкая память** | Гибридный поиск (полнотекстовый + векторный, слияние рангов) поверх встроенной офлайн-модели `mnema-embed-v1`, [контракт тегов](docs/ru/user/tag-contract.md), память по агентам и проектам, профили [контекстного фильтра](docs/ru/user/context-filter.md), сжатие CCR — экономия 70–90% токенов, оригиналы сохраняются |
+| **Сборка контекста** | `assemble_context`: поиск → сжатие → фильтр → скан секретов → выравнивание кэша → бюджет токенов, провенанс каждого блока |
+| **Мост контекста** | `on_context_rewrite` — когда харнес сжимает историю, оригинал без потерь доступен по требованию |
+| **Хуки жизненного цикла** | `pre_llm_call` — впрыск контекста, `on_session_start`, `post_tool_call` — авто-сжатие вывода инструментов |
+| **Публикация v3.0.0** | Запись видна сразу после сохранения, фоновая дообработка с бесшовной подменой, карантин с нейтральной ретракцией |
+| **Автозащита** | Детекторы инъекций / секретов на входе и на публикации, скан каждого вывода, полный аудит по каждой записи |
+| **Автоконвейер** | Фоновый процессор: кластеризация, дедупликация, гейт качества, публикация |
-> 📘 Пошаговое руководство первого запуска с MCP- и HTTP-серверами —
-> [getting-started.md](docs/ru/user/getting-started.md).
+Автономность для произвольного харнесса и LLM-дообогащение — частично; полная
+честная карта: [docs/ru/features.md](docs/ru/features.md).
 ---
@@ -185,19 +128,61 @@ curl -s http://localhost:8787/health | jq
 |  | Возможность | Что это даёт |
 |---|------------|-------------------|
-| 🔎 | **Гибридный поиск** | Векторная близость + полнотекстовый FTS5 по каждой записи |
+| 🔎 | **Гибридный поиск** | Векторная близость + SQLite FTS5 полнотекст по каждой записи |
 | 🧪 | **Конвейер знаний** | Жизненный цикл `raw → processing → processed → published` с конечным автоматом |
 | 🧠 | **Recall на агента** | Сфокусированная поверхность recall в контексте проекта каждого агента |
 | ⚙️ | **Движок политик** | Планирование и триггеры автоматизации над хранилищем памяти |
-| 🧹 | **Контекстный фильтр** | Пятиступенчатая очистка логов / stdout перед отправкой модели |
+| 🧹 | **Контекстный фильтр** | Пятиступенчатая очистка шума из логов / stdout до того, как что-то попадёт в модель |
 | 🗜️ | **Обратимое сжатие (CCR)** | Сжатие большого контента без потери данных — оригиналы кэшируются в SQLite, извлекаются по хеш-маркеру |
-| 🧷 | **CacheAligner (P1-5)** | Перенос динамического контента (таймстампы, UUID, session id, токены) в хвост, чтобы KV-кэши провайдеров (Anthropic `cache_control`, OpenAI prefix caching) попадали между запросами |
-| 🪶 | **Сокращение токенов вывода (P1-7)** | Опциональные параметры `verbosity` / `effort` на `mnemos_add` / `mnemos_search` / `mnemos_recall_context` управляют стилем вывода вызывающей стороны — обратная совместимость, значения по умолчанию — no-op |
+| 🧷 | **CacheAligner** | Перенос динамического контента (таймстампы, UUID, session id, токены) в хвост, чтобы KV-кэши провайдеров (Anthropic `cache_control`, OpenAI prefix caching) попадали между запросами |
+| 🪶 | **Сокращение токенов вывода** | Опциональные параметры `verbosity` / `effort` на `mnemos_add` / `mnemos_search` / `mnemos_recall_context` управляют стилем вывода вызывающей стороны — обратно совместимо, значения по умолчанию — no-op |
 | 📂 | **Path-scoped rules** | Ингест правил проекта и применение их по пути файла |
-| 🗂️ | **Obsidian vault** | Markdown-зеркало, которое люди могут смотреть, править и grep'ать |
+| 🗂️ | **Obsidian vault** | Markdown-зеркало, которое люди могут листать, править и грепать |
 SQLite для метаданных, локальный векторный индекс на numpy + SQLite для recall и Obsidian-совместимый
-vault для людей в процессе.
+vault для людей в контуре.
+**Куда это движется.** Отгруженная и измеренная ступень — *хранит и находит*. Следующие ступени —
+*свёртка с чеками* (синтез сессия → проект → кросс-проект: автоматическая по умолчанию, но никогда
+безусловная по авторитету — каждый итог возводим к исходникам, ничто не пиннится без оператора) и
+позже *строит понимание* — открываются только по мере подтверждения предрегистрированными
+экспериментами ([ADR-0025](docs/project/adr/0025-memory-meta-level-lanes.md)). Инвариант этого
+пути — **ноль тихих потерь**: факт либо сохранён, либо потеря видна. А форма амбиции — *нервная
+система, а не дирижёр*: память, которая поднимает нужное в нужный момент, но никогда не дирижирует
+агентом.
+---
+## 🤝 Подключение любого харнеса
+Mnemos работает с любым агентским харнесом с поддержкой MCP. Три уровня интеграции —
+выбирайте самый сильный из доступных для вашего харнеса:
+| Харнесс | Нативная цель | Однострочный MCP-пресет | Шаблон адаптера |
+|---------|---------------|-------------------------|-----------------|
+| VS Code Copilot | `copilot` (+ промпты через `generic-copilot`) | [mcp-setup.sh](scripts/mcp-setup.sh) | ✓ |
+| Claude Code | через `agents` | [пресет](integrations/mcp-presets.md#claude-code) | ✓ |
+| Cursor | `cursor` | [пресет](integrations/mcp-presets.md#cursor) | ✓ |
+| Codex | через `agents` | [пресет](integrations/mcp-presets.md#codex) | ✓ |
+| Windsurf | — | [пресет](integrations/mcp-presets.md#windsurf) | ✓ |
+| OpenCode | — | [пресет](integrations/mcp-presets.md#opencode) | ✓ |
+| ZCode | `zcode` | — | ✓ |
+| Любой харнесс стандарта AGENTS.md | `agents` | — | ✓ |
+| pi | `pi` (бридж-расширение, также на npm как [`pi-mnemos`](https://www.npmjs.com/package/pi-mnemos)) | [пресет](integrations/mcp-presets.md#pi) | ✓ |
+| [Hermes Agent](https://hermes-agent.nousresearch.com/) | `hermes` (нативный in-process плагин `MemoryProvider`) | — | — |
+- **Нативные таргеты** — `mnemos integration setup --target <имя>` разворачивает поведенческий пакет
+  и регистрирует MCP-сервер за один проход ([руководство по интеграции](docs/ru/user/integration-guide.md)).
+- **Однострочные пресеты** — [`integrations/mcp-presets.md`](integrations/mcp-presets.md): каждый
+  харнес из таблицы выше, готово к копипасту.
+- **Шаблон адаптера** — [`integrations/adapter-template.md`](integrations/adapter-template.md):
+  Connect / Expose / Configure + чеклист приёмки для любого харнеса, говорящего по MCP stdio.
+- **Hermes Agent** запускает Mnemos in-process: `pip install mnemos-memory-server` в Python-окружении
+  Hermes, затем `mnemos integration setup --target hermes`
+  ([подробнее](docs/ru/user/integration-guide.md#hermes-agent)).
+Общий контракт — [схема тегов](docs/ru/user/tag-contract.md) — `project:<slug>`, `agent:<slug>`
+и хотя бы один `mnemos:<subtype>` — обязательна для каждой записи памяти.
 ---
@@ -210,13 +195,13 @@ vault для людей в процессе.
 ```mermaid
 flowchart TB
-    subgraph CLIENTS["Клиенты"]
-        C1(["VS Code · Copilot\nstdio MCP"])
+    subgraph CLIENTS["Clients"]
+        C1(["Agent harness\nstdio MCP"])
         C2(["CLI — mnemos …"])
-        C3(["HTTP API клиент"])
+        C3(["HTTP API client"])
     end
-    subgraph IFACE["Слой интерфейсов"]
+    subgraph IFACE["Interface Layer"]
         MCP["mcp_server.py"]
         FAPI["api/main.py · FastAPI"]
         TYPER["cli/main.py · Typer"]
@@ -224,19 +209,19 @@ flowchart TB
     MGR(["MemoryManager\nmanager.py"])
-    subgraph PROC["Подсистемы обработки"]
+    subgraph PROC["Processing Subsystems"]
         CF["Context Filter\nfilter/"]
         PP["Knowledge Pipeline\npipeline/"]
         RE["Recall Engine\nrecall/"]
         PE["Policy Engine\npolicy/"]
     end
-    subgraph BG["Фоновые сервисы"]
+    subgraph BG["Background Services"]
         WA["Watchers\nwatchers/"]
         AC["Auto-collect\nauto_collect.py"]
     end
-    subgraph STORE["Слой хранения"]
+    subgraph STORE["Storage Layer"]
         SQ[("SQLite\nFTS5 · traces · projects")]
         VS[("Vector Store\nnumpy + SQLite")]
         VLT[("Obsidian Vault\nmarkdown mirror")]
@@ -266,38 +251,23 @@ flowchart TB
 </details>
-Более глубокий разбор — модель данных, конечные автоматы, границы безопасности, эксплуатационные аспекты —
-в [architecture/overview.md](docs/ru/architecture/overview.md).
+Более глубокий разбор — модель данных, конечные автоматы, границы безопасности, эксплуатационные
+аспекты — в [architecture/overview.md](docs/ru/architecture/overview.md).
 ---
 ## 🎛️ Три поверхности, одно ядро
-Один и тот же `MemoryManager` управляет всеми тремя интерфейсами. Выберите подходящий клиенту.
+Один и тот же `MemoryManager` питает все три интерфейса. Выберите тот, что подходит вашему клиенту.
 | Поверхность | Когда использовать… | Документация |
 |---------|--------------|-----------|
-| **CLI** — `mnemos …` | Вы работаете в шелле, нужен быстрый ad-hoc add / search или скрипты cron | [cli-reference.md](docs/ru/user/cli-reference.md) |
+| **MCP** — `mnemos mcp-server` | Вы — агентский харнес; путь, по которому идёт каждый подключённый агент | [mcp-tools.md](docs/ru/user/mcp-tools.md) |
+| **CLI** — `mnemos …` | Вы живёте в шелле, нужен быстрый ad-hoc add / search или скрипты для cron | [cli-reference.md](docs/ru/user/cli-reference.md) |
 | **HTTP** — `mnemos serve` | У вас не-MCP клиент — веб-дашборд, мобильное приложение, CI runner | [http-api.md](docs/ru/user/http-api.md) |
-| **MCP** — `mnemos mcp-server` | Вы VS Code Copilot или любой MCP-aware агент — путь Copilot-агентов | [mcp-tools.md](docs/ru/user/mcp-tools.md) |
-MCP-поверхность также предоставляет **A2A Sessions API** (M16) — постоянный бэкенд для многошаговых
-разговоров агентов. Пять endpoints (`POST /v1/sessions`, append-turn, range-load, …) позволяют агентам
-переживать рестарты без потери контекста. См. [a2a-sessions.md](docs/ru/architecture/a2a-sessions.md).
----
-## 📖 Лор
-> В «Теогонии» Гесиода **Мнемосина** (Μνημοσύνη) — титанида памяти. Она, от Зевса, родила девять муз и
-> через них сделала возможным воспоминание мира. Её имя — корень слова *мнемонический*, и к ней обращается
-> каждый певец, поэт и философ, прежде чем начать.
-Это программное обеспечение носит её имя, потому что создано для той же задачи: **сделать воспоминание
-возможным для тех, кто мыслит.** AI-агенты, оторванные от единственного разговора, теряют всё, что было
-до. Mnemos даёт им место, где можно это сохранить — структурированно, с поиском, по контракту — чтобы то,
-что они узнали, не исчезало с закрытием сессии. Музы, в конце концов, были не для богов. Они были для
-песен.
+HTTP-поверхность также открывает **A2A Sessions API** — постоянный бэкенд для многошаговых
+разговоров агентов, которые переживают рестарты. См. [a2a-sessions.md](docs/ru/architecture/a2a-sessions.md).
 ---
@@ -306,73 +276,40 @@ MCP-поверхность также предоставляет **A2A Sessions
 | Страница | Содержание |
 |------|----------------|
 | [docs/README.md](docs/README.md) | Главная страница документации — выбор языка (EN / RU) |
-| [getting-started.md](docs/ru/user/getting-started.md) | Первый запуск: установка → первая запись → первый поиск → MCP / HTTP |
-| [architecture/overview.md](docs/ru/architecture/overview.md) | Архитектура, модель данных, конечные автоматы, границы безопасности |
+| [getting-started.md](docs/ru/user/getting-started.md) | Первый запуск: установка → первая запись → первый поиск → подключение харнеса |
+| [mcp-presets.md](integrations/mcp-presets.md) | Подключение Mnemos к любому харнесу — однострочные MCP-пресеты (VS Code, Claude Code, Cursor, OpenCode, Codex, Windsurf, pi, Hermes) |
+| [integration-guide.md](docs/ru/user/integration-guide.md) | Поведенческий пакет: инструкции, скиллы, режим промпта, таргеты развёртывания, wiring агентов, плагин Hermes |
+| [features.md](docs/ru/features.md) | Что работает из коробки, что частично, что в планах |
+| [architecture/overview.md](docs/ru/architecture/overview.md) | Устройство системы, модель данных, конечные автоматы, границы безопасности |
 | [cli-reference.md](docs/ru/user/cli-reference.md) | Все подкоманды `mnemos` с флагами, значениями по умолчанию, примерами |
-| [mcp-tools.md](docs/ru/user/mcp-tools.md) | Все инструменты `mnemos_*` для VS Code Copilot |
-| [http-api.md](docs/ru/user/http-api.md) | Все HTTP endpoints (CRUD памяти + A2A Sessions, M16) |
-| [a2a-sessions.md](docs/ru/architecture/a2a-sessions.md) | Контракт agent-to-agent разговоров (M16) |
-| [tag-contract.md](docs/ru/user/tag-contract.md) | Схема `project:` / `agent:` / `mnemos:`, обязательная для каждой записи |
-| [security.md](docs/ru/admin/security.md) | Модель угроз, SSRF-защита, FTS5 escape, пиннинг HF Hub |
-| [runbooks/](docs/ru/admin/runbooks/) | Установка, миграция, резервное копирование, обновление зависимостей |
-| [container-deployment.md](docs/ru/admin/runbooks/container-deployment.md) | Сборка, push, compose, podman, Kubernetes, quadlet |
-| [adr/](docs/project/adr/) | Архитектурные решения (ADR) — *почему* за каждым дизайном |
-| [milestones.md](docs/project/milestones.md) | Журнал milestones со статусами |
-| [reports/](docs/project/reports/) | Отчёты о завершённых этапах — итоговый отчёт по каждой фазе дорожной карты |
+| [mcp-tools.md](docs/ru/user/mcp-tools.md) | Все инструменты `mnemos_*`, доступные агентским харнесам |
+| [http-api.md](docs/ru/user/http-api.md) | Все HTTP-эндпоинты (CRUD памяти, workflow, хуки, A2A Sessions) |
+| [tag-contract.md](docs/ru/user/tag-contract.md) | Схема `project:` / `agent:` / `mnemos:`, обязательная для каждой записи памяти |
+| [security.md](docs/ru/admin/security.md) | Модель угроз, SSRF-защита, FTS5 escape, модель аутентификации |
+| [runbooks/](docs/ru/admin/runbooks/) | Установка, миграция, резервное копирование / восстановление, обновление зависимостей, развёртывание в контейнере |
+| [adr/](docs/project/adr/) | Архитектурные решения (ADR) — *почему* за каждым решением в дизайне |
 | [CHANGELOG.md](CHANGELOG.md) | Release notes — формат Keep a Changelog |
+| [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md) | Настройка разработки, git-workflow, quality gate |
 ---
-## 🤝 Интеграции
+## 📖 Легенда
-Mnemos работает с любым харнессом, говорящим по MCP. Три уровня интеграции —
-выберите самый сильный из доступных для вашего харнесса:
-| Харнесс | Нативная цель | Однострочный MCP-пресет | Шаблон адаптера |
-|---------|---------------|-------------------------|-----------------|
-| VS Code Copilot | `copilot` (+ промпты через `generic-copilot`) | [mcp-setup.sh](scripts/mcp-setup.sh) | ✓ |
-| Claude Code | через `agents` | [пресет](integrations/mcp-presets.md#claude-code) | ✓ |
-| Cursor | `cursor` | [пресет](integrations/mcp-presets.md#cursor) | ✓ |
-| Codex | через `agents` | [пресет](integrations/mcp-presets.md#codex) | ✓ |
-| Windsurf | — | [пресет](integrations/mcp-presets.md#windsurf) | ✓ |
-| ZCode | `zcode` | — | ✓ |
-| Любой харнесс стандарта AGENTS.md | `agents` | — | ✓ |
-| [Hermes Agent](https://hermes-agent.nousresearch.com/) | `hermes` (нативный `MemoryProvider` плагин) | — | — |
-- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** — нативный `MemoryProvider` плагин
-  (`integrations/hermes/`): автоматический prefetch, sync-turn, зеркалирование встроенной памяти.
-  С версии плагина **3.0.0** (ADR-0017 D1) плагин работает **in-process** — требуется `pip install mnemos-memory-server`
-  в Python-окружении Hermes, а легаси-ключи конфигурации `base_url` / `api_key` / `totp_secret` удалены.
-  См. [руководство по интеграции](docs/ru/user/integration-guide.md#hermes-agent).
-- **Нативные цели** — `mnemos integration setup --target <имя>` развёртывает
-  поведенческий пакет и регистрирует MCP-сервер за один проход. См.
-  [руководство по интеграции](docs/ru/user/integration-guide.md).
-- **Однострочные MCP-пресеты** — [`integrations/mcp-presets.md`](integrations/mcp-presets.md):
-  Cursor, Claude Code, Codex и Windsurf подключаются вставкой одной строки.
-- **Шаблон адаптера** — [`integrations/adapter-template.md`](integrations/adapter-template.md):
-  Connect / Expose / Configure + чеклист приёмки для любого харнесса,
-  говорящего по MCP stdio.
+> В «Теогонии» Гесиода **Мнемосина** (Μνημοσύνη) — титанида памяти. Она, от Зевса, родила девять муз и
+> через них сделала возможным воспоминание мира. Её имя — корень слова *мнемонический*, и к ней
+> обращается каждый певец, поэт и философ, прежде чем начать.
-Общий контракт — [схема тегов](docs/ru/user/tag-contract.md) — `project:<slug>`, `agent:<slug>`
-и хотя бы один `mnemos:<subtype>` — которую должна нести каждая запись.
+Это программное обеспечение носит её имя, потому что создано для той же задачи: **сделать воспоминание
+возможным для тех, кто мыслит.** AI-агенты, не привязанные ни к одному разговору, теряют всё, что было
+до. Mnemos даёт им место, куда это можно положить — структурированно, с поиском, по контракту — чтобы
+то, что они узнали, не исчезало с закрытием сессии. Музы, в конце концов, были не для богов. Они были
+для песен.
 ---
-## ⚖️ Исходный код и лицензия
-- **Исходник** — этот репозиторий, [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
-- **Лицензия** — Apache-2.0 (см. [LICENSE](LICENSE)).
+## ⚖️ Лицензия и вклад
-## 🌱 Участие
+Apache-2.0 — см. [LICENSE](LICENSE) и [NOTICE](NOTICE). Исходники: [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
-PR приветствуются. Прочитайте [PLAN.md](PLAN.md) для roadmap и следуйте конвенциям в [docs/](docs/).
-Git-workflow: `feat/*` → `dev-<этап>` → `release/X.Y.Z` → `main`; `main` принимает только `release/*` и
-`hotfix/*` PR. Обязательны Conventional Commits. Запустите `make verify` перед открытием PR.
----
-<p align="center">
-  <sub><strong>Воспроизведите зелёное состояние:</strong> <code>make verify</code> запускает полный
-  quality gate — ruff + mypy --strict + bandit + pip-audit + 802 тестов. Если зелёно — готово к публикации.</sub>
-</p>
+Вклад приветствуется — в [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md): настройка окружения разработки,
+конвенции веток и коммитов и quality gate, который должно пройти каждое изменение.

package/integrations/extensions/mnemos-mcp.ts CHANGED Viewed

@@ -5,6 +5,9 @@
  * has no built-in MCP client by design: tools arrive via TypeScript
  * extensions. This extension spawns `mnemos mcp-server` over stdio, performs
  * the MCP handshake and registers every `mnemos_*` tool as a native Pi tool.
+ * It also injects the always-on mnemos behavioral pack into Pi's system
+ * prompt (before_agent_start hook) — Pi has no AGENTS.md surface, so the
+ * extension is the standing-instructions channel.
  *
  * Deployed by:  mnemos integration setup --target pi
  * Location:     ~/.pi/agent/extensions/mnemos-mcp.ts
@@ -19,6 +22,20 @@ import { Type } from "typebox";
 const MNEMOS_BIN = process.env.MNEMOS_BIN ?? "mnemos";
 const REQ_TIMEOUT_MS = 60_000;
+// Standing behavioral pack, injected into the system prompt on every turn
+// (mnemos:integration — kept in sync with integrations/agents_md/). Pi has
+// no AGENTS.md mechanism; for the bridge extension this hint IS the
+// always-on instructions channel.
+const MNEMOS_STANDING_HINT = [
+	"# Mnemos memory — always-on rules",
+	"",
+	"You have persistent shared memory through the `mnemos_*` tools.",
+	"- Session start: call mnemos_recall_context(project=<current-project>) BEFORE reading project files; surface a <=4-line memory header. Never block on failure.",
+	"- Before context compaction, session end or handoff: mnemos_save_context(project, goals, completed, next_steps) — unsaved context is lost.",
+	"- PRIORITY ops: mnemos_search before architectural decisions and before web searches; mnemos_add when you learn something non-obvious or make a decision; mnemos_agent_recall when resuming a named agent role.",
+	"- Tag contract on every mnemos_add/mnemos_ingest_url: exactly one project:<slug>, one agent:<slug>, at least one mnemos:<subtype>.",
+].join("\n");
 interface McpTool {
 	name: string;
 	description?: string;
@@ -164,6 +181,14 @@ export default function mnemosMcpBridge(pi: ExtensionAPI) {
 	}
 	// ── Lifecycle ────────────────────────────────────────────────────────────
+	// Standing hint: before_agent_start fires once per system-prompt build;
+	// returning an object with systemPrompt appends our pack to Pi's prompt
+	// (chained across extensions).
+	pi.on("before_agent_start", (event: { systemPrompt?: string }) => {
+		const base = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
+		if (base.includes("mnemos:integration")) return event; // hint already present — never duplicate
+		return { systemPrompt: base + (base ? "\n\n" : "") + MNEMOS_STANDING_HINT };
+	});
 	pi.on("session_start", (_event: unknown, ctx: Parameters<Parameters<typeof pi.on>[1]>[1]) =>
 		connect(ctx as { ui?: { notify: (m: string, l?: string) => void } }),
 	);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@korrlabs/mnemospi",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Mnemos memory & knowledge server — Pi extension. Spawns `mnemos mcp-server` over stdio and exposes every mnemos_* tool as a native Pi tool, plus the mnemos skill pack.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,5 +55,13 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "pipeline": {
+    "npmPublishNames": [
+      "pi-mnemos",
+      "mnemos-pi",
+      "@korrlabs/mnemospi",
+      "@korrlabs/mnemos-pi"
+    ]
   }
 }