npm - @korrlabs/mnemospi - Versions diffs - 3.2.0 → 4.1.0 - Mend

@korrlabs/mnemospi 3.2.0 → 4.1.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 (5) hide show

package/LICENSE +216 -21
package/README.md +116 -195
package/README.ru.md +135 -207
package/integrations/extensions/mnemos-mcp.ts +25 -0
package/package.json +10 -2

package/LICENSE CHANGED Viewed

@@ -1,21 +1,216 @@
-MIT License
-Copyright (c) 2026-present Korrnals
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright [yyyy] [name of copyright owner]
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   Copyright 2026 Korrnals
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md CHANGED Viewed

@@ -11,8 +11,10 @@
 </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-MIT-blue" alt="License: MIT"></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>
@@ -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.
+Three commands from an empty machine to an agent that remembers — and knows when to look.
-### 1 · Install
+### 1 · Install the server
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash
+pip install mnemos-memory-server
 ```
-The installer does everything for you — no Python or venv knowledge required:
+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.
-- 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).
+> ⚠️ Mind the name: `pip install mnemos` (without `-memory-server`) is an unrelated project.
-> 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
+### 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>
+### 3 · Verify — then try it
-<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/v3.1.0/mnemos-3.1.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).
+That is the whole loop: **write, find, never lose it — and the agent knows when to look.**
-</details>
-<details>
-<summary><strong>🐳 Run the pre-built image directly (GHCR)</strong></summary>
-<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:3.1.0
-<!-- /version:image -->
-curl -s http://localhost:8787/health | jq
-```
+## ✨ Features
-<!-- version:tags -->
-Tags: `:3.1.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 |
-> 📘 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,8 +134,8 @@ 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 |
@@ -207,6 +144,38 @@ 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:
+| 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
 <details open>
@@ -217,7 +186,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 +252,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 +266,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`
-  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** — MIT (see [pyproject.toml](pyproject.toml)).
+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,12 +7,14 @@
 <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-MIT-blue" alt="License: MIT"></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>
@@ -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>
 ---
-## ✨ Возможности
-Один локальный сервер — и подключённый агентский харнес получает полный стек памяти.
-| Область | Что даёт |
-|---------|----------|
-| **Универсальное подключение** | 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** | Запись видна сразу после сохранения, фоновая дообработка с бесшовной подменой, карантин с нейтральной ретракцией |
-| **Автозащита** | Детекторы инъекций / секретов на входе и публикации, скан каждой выдачи, полный аудит с привязкой к записи |
-| **Автоконвейер** | Фоновый обработчик: кластеризация, дедупликация, гейт качества, публикация |
+AI-агенты забывают всё, когда сессия заканчивается. Mnemos даёт им место, куда это можно
+положить — структурированно, с поиском, по контракту — чтобы то, что агент узнал, не исчезало
+с закрытием окна.
-Автономность для произвольного харнесса, 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 · Установка
+Три команды от пустой машины до агента, который помнит — и знает, когда заглянуть.
-```bash
-curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash
-```
-Установщик делает всё за вас — знание Python или venv не требуется:
-- создаёт изолированное окружение в `~/.mnemos/venv`;
-- кладёт лаунчер `mnemos` в `~/.local/bin`, чтобы CLI работал в любом шелле (**активировать venv не нужно**);
-- тут же предлагает настроить интеграцию VS Code MCP (или сделайте это позже — см. шаг 3).
-> Нужен неинтерактивный запуск? Добавьте `--mcp` / `--no-mcp`, чтобы выбрать заранее, например
-> `… | bash -s -- --mcp`.
-### 2 · Запись и поиск
+### 1 · Установите сервер
 ```bash
-mnemos add "Первая запись — Mnemos помнит между сессиями" \
-  --tags project:mnemos,agent:tech-writer,mnemos:learning
-mnemos search "помнит между сессиями"
+pip install mnemos-memory-server
 ```
-Это весь цикл: **записал, нашёл, не потерял.** Каждая запись несёт
-[контракт тегов](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
-```
+Всё в одном пакете: сервер памяти, CLI `mnemos`, REST API и MCP-сервер, с которым разговаривает
+ваш агентский харнес. Модель эмбеддингов встроена — поиск работает полностью офлайн,
+без API-ключей и без загрузок.
-Затем **перезагрузите окно VS Code** (`Ctrl+Shift+P → Reload Window`). Инструменты `mnemos_*` появятся
-в палитре инструментов Copilot, и агенты смогут вызывать `mnemos_add` / `mnemos_search` напрямую.
+> ⚠️ Не перепутайте имя: `pip install mnemos` (без `-memory-server`) — посторонний проект.
-### 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/v3.1.0/mnemos-3.1.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:3.1.0
-<!-- /version:image -->
-curl -s http://localhost:8787/health | jq
-```
+## ✨ Возможности
-<!-- version:tags -->
-Теги: `:3.1.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,52 @@ 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 для людей в контуре.
+---
+## 🤝 Подключение любого харнеса
+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 +186,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 +200,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 +242,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 +267,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`
-  в 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).
-- **Лицензия** — MIT (см. [pyproject.toml](pyproject.toml)).
+## ⚖️ Лицензия и вклад
-## 🌱 Участие
+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,9 +1,9 @@
 {
   "name": "@korrlabs/mnemospi",
-  "version": "3.2.0",
+  "version": "4.1.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": "MIT",
+  "license": "Apache-2.0",
   "author": "Korrnals",
   "homepage": "https://github.com/Korrnals/mnemos",
   "repository": {
@@ -55,5 +55,13 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "pipeline": {
+    "npmPublishNames": [
+      "pi-mnemos",
+      "mnemos-pi",
+      "@korrlabs/mnemospi",
+      "@korrlabs/mnemos-pi"
+    ]
   }
 }