@korrlabs/mnemos-pi 2.15.0

package/README.ru.md

@@ -0,0 +1,378 @@
+<!-- markdownlint-disable MD041 MD033 -->
+<p align="center">
+  <img src="docs/assets/mnemos-banner.svg" alt="Mnemos — сервер памяти и знаний для AI-агентов" width="100%">
+</p>
+
+<h1 align="center">Mnemos</h1>
+
+<p align="center">
+  <strong>Сервер памяти и знаний для AI-агентов</strong><br>
+  <em>назван в честь титаниды памяти, создан для AI-агентов, которым нужна память</em>
+</p>
+
+<p align="center">
+  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python"></a>
+  <a href="pyproject.toml"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
+  <a href="https://github.com/Korrnals/mnemos/releases"><img src="https://img.shields.io/github/v/release/Korrnals/mnemos?label=version&color=blueviolet" alt="Version"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">🇬🇧 English</a> · <strong>🇷🇺 Русский</strong>
+</p>
+
+<p align="center">
+  <a href="#-возможности">Возможности</a> ·
+  <a href="#-быстрый-старт">Быстрый старт</a> ·
+  <a href="#-что-такое-mnemos">Что это</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** | Запись видна сразу после сохранения, фоновая дообработка с бесшовной подменой, карантин с нейтральной ретракцией |
+| **Автозащита** | Детекторы инъекций / секретов на входе и публикации, скан каждой выдачи, полный аудит с привязкой к записи |
+| **Автоконвейер** | Фоновый обработчик: кластеризация, дедупликация, гейт качества, публикация |
+
+Автономность для произвольного харнесса, LLM-дообогащение и публикация пакетов
+(PyPI / npm) — частично; полная честная карта: [docs/ru/features.md](docs/ru/features.md).
+
+---
+
+## 🚀 Быстрый старт
+
+Четыре шага до рабочего хранилища памяти, подключённого к 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 · Запись и поиск
+
+```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 · Установка поведенческих инструкций
+
+```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>
+
+**Из исходников** (для разработки):
+
+```bash
+git clone https://github.com/Korrnals/mnemos.git
+cd mnemos
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+**Готовый wheel** (зафиксировать конкретную версию):
+
+<!-- version:pip -->
+```bash
+pip install https://github.com/Korrnals/mnemos/releases/download/v3.0.0/mnemos-3.0.0-py3-none-any.whl
+```
+<!-- /version:pip -->
+
+**Контейнер одной командой** — скачивает образ, создаёт тома, запускает на порту 8787:
+
+```bash
+export MNEMOS_API__TOTP_MASTER_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
+curl -fsSL https://raw.githubusercontent.com/Korrnals/mnemos/main/scripts/install.sh | bash -s -- --container
+```
+
+Полное руководство — [container-deployment.md](docs/ru/admin/runbooks/container-deployment.md).
+
+</details>
+
+<details>
+<summary><strong>🐳 Запуск готового образа напрямую (GHCR)</strong></summary>
+
+<br>
+
+Образ публикуется в `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.0.0
+<!-- /version:image -->
+
+curl -s http://localhost:8787/health | jq
+```
+
+<!-- version:tags -->
+Теги: `:3.0.0` (фиксированная) · `:latest` (rolling). Работает и с `docker` — замените `podman` на `docker`.
+<!-- /version:tags -->
+
+</details>
+
+> 📘 Пошаговое руководство первого запуска с MCP- и HTTP-серверами —
+> [getting-started.md](docs/ru/user/getting-started.md).
+
+---
+
+## 🧩 Что такое Mnemos
+
+**Однотенантный, локально-ориентированный сервер памяти** для AI-агентов. Одно ядро in-process, три
+эквивалентных поверхности управления и слой хранения, который можно прочитать своими глазами.
+
+|  | Возможность | Что это даёт |
+|---|------------|-------------------|
+| 🔎 | **Гибридный поиск** | Векторная близость + полнотекстовый FTS5 по каждой записи |
+| 🧪 | **Конвейер знаний** | Жизненный цикл `raw → processing → processed → published` с конечным автоматом |
+| 🧠 | **Recall на агента** | Сфокусированная поверхность recall в контексте проекта каждого агента |
+| ⚙️ | **Движок политик** | Планирование и триггеры автоматизации над хранилищем памяти |
+| 🧹 | **Контекстный фильтр** | Пятиступенчатая очистка логов / 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 |
+| 📂 | **Path-scoped rules** | Ингест правил проекта и применение их по пути файла |
+| 🗂️ | **Obsidian vault** | Markdown-зеркало, которое люди могут смотреть, править и grep'ать |
+
+SQLite для метаданных, локальный векторный индекс на numpy + SQLite для recall и Obsidian-совместимый
+vault для людей в процессе.
+
+---
+
+## 🏗️ Архитектура
+
+<details open>
+<summary><strong>Схема системы</strong> — клиенты → интерфейсы → ядро → хранилище</summary>
+
+<br>
+
+```mermaid
+flowchart TB
+    subgraph CLIENTS["Клиенты"]
+        C1(["VS Code · Copilot\nstdio MCP"])
+        C2(["CLI — mnemos …"])
+        C3(["HTTP API клиент"])
+    end
+
+    subgraph IFACE["Слой интерфейсов"]
+        MCP["mcp_server.py"]
+        FAPI["api/main.py · FastAPI"]
+        TYPER["cli/main.py · Typer"]
+    end
+
+    MGR(["MemoryManager\nmanager.py"])
+
+    subgraph PROC["Подсистемы обработки"]
+        CF["Context Filter\nfilter/"]
+        PP["Knowledge Pipeline\npipeline/"]
+        RE["Recall Engine\nrecall/"]
+        PE["Policy Engine\npolicy/"]
+    end
+
+    subgraph BG["Фоновые сервисы"]
+        WA["Watchers\nwatchers/"]
+        AC["Auto-collect\nauto_collect.py"]
+    end
+
+    subgraph STORE["Слой хранения"]
+        SQ[("SQLite\nFTS5 · traces · projects")]
+        VS[("Vector Store\nnumpy + SQLite")]
+        VLT[("Obsidian Vault\nmarkdown mirror")]
+    end
+
+    C1 -->|"stdio"| MCP
+    C2 --> TYPER
+    C3 --> FAPI
+    MCP --> MGR
+    TYPER --> MGR
+    FAPI --> MGR
+    MGR --> CF
+    MGR --> PP
+    MGR --> RE
+    MGR --> SQ
+    MGR --> VS
+    MGR --> VLT
+    CF -.->|"raw + clean"| SQ
+    PP -->|"status transitions"| SQ
+    PP -->|"published upsert"| VS
+    RE -->|"FTS5 MATCH"| SQ
+    RE -->|"cosine search"| VS
+    PE -->|"schedule / trigger"| MGR
+    WA -->|"file events"| MGR
+    AC -.->|"checkpoint reminder"| MCP
+```
+
+</details>
+
+Более глубокий разбор — модель данных, конечные автоматы, границы безопасности, эксплуатационные аспекты —
+в [architecture/overview.md](docs/ru/architecture/overview.md).
+
+---
+
+## 🎛️ Три поверхности, одно ядро
+
+Один и тот же `MemoryManager` управляет всеми тремя интерфейсами. Выберите подходящий клиенту.
+
+| Поверхность | Когда использовать… | Документация |
+|---------|--------------|-----------|
+| **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 даёт им место, где можно это сохранить — структурированно, с поиском, по контракту — чтобы то,
+что они узнали, не исчезало с закрытием сессии. Музы, в конце концов, были не для богов. Они были для
+песен.
+
+---
+
+## 📚 Документация
+
+| Страница | Содержание |
+|------|----------------|
+| [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) | Архитектура, модель данных, конечные автоматы, границы безопасности |
+| [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/) | Отчёты о завершённых этапах — итоговый отчёт по каждой фазе дорожной карты |
+| [CHANGELOG.md](CHANGELOG.md) | Release notes — формат Keep a Changelog |
+
+---
+
+## 🤝 Интеграции
+
+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>` — которую должна нести каждая запись.
+
+---
+
+## ⚖️ Исходный код и лицензия
+
+- **Исходник** — этот репозиторий, [github.com/Korrnals/mnemos](https://github.com/Korrnals/mnemos).
+- **Лицензия** — MIT (см. [pyproject.toml](pyproject.toml)).
+
+## 🌱 Участие
+
+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>

package/integrations/extensions/mnemos-mcp.ts

@@ -0,0 +1,178 @@
+/**
+ * mnemos-mcp — MCP bridge for the Pi coding agent.
+ *
+ * Pi (npm @earendil-works/pi-coding-agent)
+ * 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.
+ *
+ * Deployed by:  mnemos integration setup --target pi
+ * Location:     ~/.pi/agent/extensions/mnemos-mcp.ts
+ * Requires:     `mnemos` on PATH (override with MNEMOS_BIN env var).
+ * Reload:       /reload  (Pi hot-reloads extensions) or /mnemos to reconnect.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const MNEMOS_BIN = process.env.MNEMOS_BIN ?? "mnemos";
+const REQ_TIMEOUT_MS = 60_000;
+
+interface McpTool {
+	name: string;
+	description?: string;
+	inputSchema?: Record<string, unknown>;
+}
+
+export default function mnemosMcpBridge(pi: ExtensionAPI) {
+	let child: ChildProcess | null = null;
+	let nextId = 1;
+	let buffer = "";
+	let started = false;
+	let registeredNames = new Set<string>();
+	const pending = new Map<
+		number,
+		{ resolve: (v: unknown) => void; reject: (e: Error) => void; timer: NodeJS.Timeout }
+	>();
+
+	// ── JSON-RPC plumbing ──────────────────────────────────────────────────
+	function send(obj: unknown): void {
+		if (!child?.stdin?.writable) throw new Error("mnemos MCP: stdin not writable");
+		child.stdin.write(JSON.stringify(obj) + "\n");
+	}
+
+	function request(method: string, params?: unknown): Promise<any> {
+		const id = nextId++;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				reject(new Error(`mnemos MCP: timeout on ${method}`));
+			}, REQ_TIMEOUT_MS);
+			pending.set(id, { resolve, reject, timer });
+			send({ jsonrpc: "2.0", id, method, params });
+		});
+	}
+
+	function handleLine(line: string): void {
+		line = line.trim();
+		if (!line) return;
+		let msg: any;
+		try {
+			msg = JSON.parse(line);
+		} catch {
+			return; // non-RPC noise on stdout
+		}
+		if (msg.id !== undefined && pending.has(msg.id)) {
+			const p = pending.get(msg.id)!;
+			pending.delete(msg.id);
+			clearTimeout(p.timer);
+			if (msg.error) p.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+			else p.resolve(msg.result);
+		}
+		// Server notifications (progress, …) are intentionally ignored.
+	}
+
+	function killChild(): void {
+		child?.stdin?.end();
+		child?.kill("SIGTERM");
+		child = null;
+		started = false;
+	}
+
+	async function startBridge(): Promise<McpTool[]> {
+		if (child) killChild();
+		buffer = "";
+		child = spawn(MNEMOS_BIN, ["mcp-server"], { stdio: ["pipe", "pipe", "ignore"] });
+		child.on("error", (e: Error) => {
+			started = false;
+		});
+		child.stdout!.setEncoding("utf8");
+		child.stdout!.on("data", (chunk: string) => {
+			buffer += chunk;
+			let nl: number;
+			while ((nl = buffer.indexOf("\n")) >= 0) {
+				handleLine(buffer.slice(0, nl));
+				buffer = buffer.slice(nl + 1);
+			}
+		});
+		child.on("exit", () => {
+			started = false;
+			for (const [, p] of pending) {
+				clearTimeout(p.timer);
+				p.reject(new Error("mnemos MCP: server exited"));
+			}
+			pending.clear();
+		});
+
+		await request("initialize", {
+			protocolVersion: "2024-11-05",
+			capabilities: {},
+			clientInfo: { name: "pi-mnemos-bridge", version: "1.0.0" },
+		});
+		send({ jsonrpc: "2.0", method: "notifications/initialized" });
+		const res = await request("tools/list", {});
+		started = true;
+		return (res.tools ?? []) as McpTool[];
+	}
+
+	// ── Register MCP tools as native Pi tools ───────────────────────────────
+	function registerTool(tool: McpTool): boolean {
+		if (registeredNames.has(tool.name)) return false;
+		const schema =
+			tool.inputSchema && tool.inputSchema.type === "object"
+				? Type.Unsafe(tool.inputSchema)
+				: Type.Object({});
+
+		pi.registerTool({
+			name: tool.name,
+			label: tool.name.replace(/^mnemos_/, "🧠 "),
+			description: tool.description ?? `mnemos MCP tool ${tool.name}`,
+			promptSnippet: `Persistent shared memory: ${tool.description?.slice(0, 120) ?? tool.name}`,
+			parameters: schema as never,
+			async execute(_toolCallId: string, params: unknown) {
+				if (!started) await startBridge();
+				const result = await request("tools/call", {
+					name: tool.name,
+					arguments: params,
+				});
+				const parts: Array<{ type: string; text?: string }> = result.content ?? [];
+				const text = parts
+					.map((p) => (p.type === "text" ? p.text ?? "" : `[${p.type}]`))
+					.join("\n")
+					.trim();
+				return {
+					content: [{ type: "text", text: text || "(empty result)" }],
+					details: { isError: result.isError ?? false },
+				};
+			},
+		});
+		registeredNames.add(tool.name);
+		return true;
+	}
+
+	async function connect(ctx: { ui?: { notify: (m: string, l?: string) => void } }): Promise<void> {
+		try {
+			const tools = await startBridge();
+			registeredNames = new Set();
+			let fresh = 0;
+			for (const t of tools) if (registerTool(t)) fresh++;
+			ctx.ui?.notify(`🧠 mnemos: ${fresh} memory tools online (${tools.length} served)`, "info");
+		} catch (e) {
+			ctx.ui?.notify(`🧠 mnemos: bridge failed — ${(e as Error).message}`, "warning");
+		}
+	}
+
+	// ── Lifecycle ────────────────────────────────────────────────────────────
+	pi.on("session_start", (_event: unknown, ctx: Parameters<Parameters<typeof pi.on>[1]>[1]) =>
+		connect(ctx as { ui?: { notify: (m: string, l?: string) => void } }),
+	);
+	pi.on("session_end", () => killChild());
+	process.on("exit", () => killChild());
+
+	// Manual control: /mnemos reconnects the bridge and re-registers tools.
+	pi.registerCommand("mnemos", {
+		description: "Reconnect the mnemos MCP memory bridge",
+		handler: async (_args: string, ctx: any) => connect(ctx),
+	});
+}

package/integrations/skills/.gitkeep

@@ -0,0 +1,2 @@
+# Skill files (SKILL.md) are added by Stream B (Tech Writer).
+# This directory is the source pack shipped with the package.

package/integrations/skills/mnemos-agent-recall.md

@@ -0,0 +1,53 @@
+---
+name: mnemos-agent-recall
+description: Agent-scoped memory recall — what did THIS agent (or a teammate) previously learn, decide, or leave open
+---
+
+# Mnemos Agent Recall
+
+Pull the latest memories written by a specific agent slug (yours or a
+teammate's). Use it to resume another agent's thread of work or to check
+what a specialist agent already established before duplicating it.
+
+## WHEN
+
+- **Resuming work after a context reset** — your own latest entries first.
+- **Taking over from another agent** — review their trail before changing
+  their decisions.
+- **Team coordination** — check what `gcw-tech-lead` / `reviewer` / etc.
+  already decided in this project.
+
+## STEPS
+
+1. **Recall your own trail**:
+
+   ```text
+   mnemos_agent_recall(agent=<your-slug>, limit=10)
+   ```
+
+2. **Scope to the project** to cut noise from other work:
+
+   ```text
+   mnemos_agent_recall(agent=<slug>, project=<project-slug>, limit=10)
+   ```
+
+3. **Narrow with a query** when the trail is long:
+
+   ```text
+   mnemos_agent_recall(agent=<slug>, query="auth refactor", limit=5)
+   ```
+
+4. **For open work**, follow up with `mnemos_workflow(action="get", …)` on
+   entries tagged `mnemos:open-question`.
+
+## DISCIPLINE
+
+- Agent recall is a **trail, not a search** — for topical questions use
+  `mnemos-recall` (hybrid search) instead.
+- Entries appear newest-first; if the trail is stale, check
+  `mnemos_list_recent` before assuming the agent stopped writing.
+
+## See also
+
+- Skill `mnemos-recall` — topical semantic search
+- Skill `mnemos-workflow` — lifecycle of open questions

package/integrations/skills/mnemos-cache-align.md

@@ -0,0 +1,48 @@
+---
+name: mnemos-cache-align
+description: Stabilize prompt prefixes for provider KV caches — move dynamic tokens to the end before caching matters
+---
+
+# Mnemos Cache Align
+
+Relocate dynamic content (timestamps, UUIDs, session ids, tokens) to the
+END of a text so its prefix stays byte-identical across requests. That
+makes provider KV caches (Anthropic cache_control, OpenAI prefix caching)
+actually hit.
+
+## WHEN
+
+- **Repeated calls with a large shared prefix** — system prompts, tool
+  definitions, style guides — with only a volatile tail.
+- **Cache hit-rate is poor** despite stable-looking prompts — hidden
+  timestamps/ids at the top are usually the cause.
+- **Building a prompt template** that will fire many times.
+
+## STEPS
+
+1. **Align the text**:
+
+   ```text
+   mnemos_align_prefix(text=<prompt>, profile="code")
+   ```
+
+   Profiles: `code` (keeps bare identifiers in place — avoids mangling
+   long symbol names), `docs`, `default`.
+
+2. **Use the aligned text** as the stable prefix; append the truly
+   per-request values AFTER it.
+
+3. **Verify by diffing** two aligned outputs for the same logical content —
+   the prefix must be byte-identical.
+
+## DISCIPLINE
+
+- Align ONCE at template build time, not per request.
+- Don't align user-facing prose where order carries meaning — this is for
+  machine-consumed prompts.
+- `code` profile skips bare tokens deliberately; the default profile is
+  more aggressive.
+
+## See also
+
+- Skill `mnemos-compress` — shrinking big outputs that changed anyway