# Verifiable Memory Bank

**Русский** | [English](README.en.md) | [Українська](README.uk.md)

Verifiable Memory Bank создает локальную воспроизводимую внешнюю память для
людей и AI-клиентов. К каждому результату прикреплено точное доказательство,
поэтому найденный фрагмент можно проверить в именованном нормализованном
представлении, а его происхождение вернуть к неизменяемым исходным байтам,
датам, атрибуции и SHA-256.

<p align="center">
  <img src="docs/images/verifiable-memory-overview.png" width="470" alt="Обзор архитектуры Verifiable Memory Bank">
</p>

## Зачем это нужно

По папке документов трудно искать. Векторная база находит похожие
формулировки, но одно сходство не доказывает утверждение. Verifiable Memory
Bank разделяет эти задачи:

- исходные байты хранятся в неизменяемом хранилище с адресацией по содержимому;
- детерминированные адаптеры превращают поддерживаемые форматы в
  неперекрывающиеся сегменты;
- политика доверия помечает материал как `canon`, `context` или `unresolved`;
- полнотекстовый поиск SQLite и TF-IDF плюс NumPy SVD дают точный и смысловой
  поиск;
- Reciprocal Rank Fusion объединяет оба рейтинга в режиме `hybrid`;
- каждый результат содержит стабильный `segment_id`, а `evidence` связывает
  его с хешированным нормализованным представлением через TextPosition и
  TextQuote selectors и с исходным объектом через SHA-256;
- MCP-сервер только для чтения открывает AI-клиентам тот же интерфейс,
  ориентированный на доказательства.

Банк не считает автоматическим подтверждением смысловую близость, свежую дату
публикации, результат OCR, цитату или речь без надёжной атрибуции.

## Быстрый старт

Нужны Python 3.11 или новее и [`uv`](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/axrbarsic/verifiable-memory-bank.git
cd verifiable-memory-bank
uv tool install .

memory-bank --bank .memory-bank init
memory-bank --bank .memory-bank ingest examples/sample-corpus
memory-bank --bank .memory-bank search "amber current" --mode hybrid --limit 5
```

Скопируйте `segment_id` из результата и откройте точное доказательство:

```bash
memory-bank --bank .memory-bank evidence SEGMENT_ID
memory-bank --bank .memory-bank health
```

Флаг `--json` после `memory-bank` или подкоманды включает машиночитаемый вывод.
Тот же банк можно выбрать через `MEMORY_BANK_HOME`.

В [подробном руководстве](docs/quick-start.md) описаны конфигурация, JSON,
загрузка из inbox, приёмка и устранение неполадок.

Вымышленный sample corpus намеренно оставлен на английском. Это стабильная
fixture для воспроизводимых англоязычных поисковых тестов, а не часть
пользовательской документации.

## Интерфейс CLI

```text
memory-bank --bank PATH [--json] init
memory-bank --bank PATH [--json] ingest INPUT [INPUT ...]
memory-bank --bank PATH [--json] ingest-inbox [INBOX]
memory-bank --bank PATH [--json] status
memory-bank --bank PATH [--json] search QUERY [--mode exact|semantic|hybrid] [--limit N]
memory-bank --bank PATH [--json] source SOURCE_ID
memory-bank --bank PATH [--json] evidence SEGMENT_ID
memory-bank --bank PATH [--json] dossier TOPIC [--limit N]
memory-bank --bank PATH [--json] chronology TOPIC [--limit N]
memory-bank --bank PATH [--json] health
memory-bank --bank PATH [--json] accept
memory-bank --bank PATH [--json] migrate
```

Все фильтры и аргументы показывает `memory-bank COMMAND --help`.

## MCP

`memory-bank-mcp` обслуживает один банк через stdio и не предоставляет
инструменты изменения. Безопасный для desktop запуск по умолчанию использует
`~/.memory-bank`, а CLI использует локальный для проекта `.memory-bank`.
Переменная `MEMORY_BANK_HOME` выбирает другой абсолютный путь для обоих:

```json
{
  "mcpServers": {
    "verifiable-memory-bank": {
      "command": "memory-bank-mcp",
      "env": {
        "MEMORY_BANK_HOME": "/absolute/path/to/.memory-bank"
      }
    }
  }
}
```

Доступны инструменты `status`, `search`, `dossier`, `chronology`, `source` и
`evidence`. Перед тем как представить существенное утверждение подтверждённым,
клиент должен получить точное доказательство.

MCP возвращает переносимый `object_ref` и не передает абсолютный путь банка или
локальный `file:` URI в контекст модели. Локальный CLI и Python API сохраняют
операторский `object_path`.

## Плагин Codex

В `plugins/verifiable-memory-bank/` находится плагин с переиспользуемым
процессом проверки доказательств. [Руководство по установке](docs/plugin-installation.md)
объясняет подключение через marketplace Codex и запуск MCP-сервера.

## Форматы и расширение

В ядро входят детерминированные адаптеры для обычного текста, разметки,
структурированных данных и субтитров. Опциональные extras добавляют PDF, OCR и
медиа:

```bash
uv tool install '.[pdf]'
uv tool install '.[ocr]'
uv tool install '.[media]'
uv tool install '.[all]'
```

Неизвестный формат получает `needs_adapter`, а не вымышленный успешный
результат. См. [руководство по адаптерам](docs/adapters.md) и рабочий
[пример собственного адаптера](examples/custom-adapter.py).

## Доверие и доказательства

Доверие задаётся явной политикой, а не поисковой оценкой. `canon` может сделать
прямой первичный материал допустимым для подтверждения, `context` объясняет или
цитирует его, а `unresolved` сохраняет материал, которому ещё нужны атрибуция
или проверка. Сегменты `quote`, `ocr` и `derived` сами по себе не проходят этот
gate. Поле `claim_evaluation: not_evaluated` напоминает, что банк не
проверял entailment конкретного тезиса.

Подробности: [доверие и доказательства](docs/trust-and-evidence.md),
[`examples/trust-config.yaml`](examples/trust-config.yaml) и
[`examples/acceptance.yaml`](examples/acceptance.yaml).

## Архитектура и проверка

При загрузке система строит полную версию-кандидат, проверяет базу данных,
хеши объектов, смещения сегментов, полнотекстовый индекс, семантический артефакт
и ссылки, запечатывает effective trust policy в manifest, затем атомарно
переключает указатель `ACTIVE`. Читатели видят либо предыдущую валидную сборку,
либо новую валидную сборку.

- [Техническая архитектура](docs/architecture.md)
- [Мультимодельный prior-art аудит](docs/prior-art-audit.md)
- [Архитектурный рассказ](docs/architecture.ru.md)
- [Политика безопасности](SECURITY.md)
- [Модель приватности](PRIVACY.md)

Для разработки репозитория:

```bash
make install
make check
make acceptance
```

`make acceptance` строит wheel, устанавливает его в чистое окружение Python
3.13, дважды загружает sample corpus, проверяет идемпотентность и активацию,
затем вызывает search, health и acceptance через установленный CLI.

## Лицензии

| Материал | Лицензия |
| --- | --- |
| Программный код и исполняемые примеры | 0BSD |
| Документация и оригинальные иллюстрации | CC0-1.0 |
| Полностью вымышленный sample corpus и YAML-примеры | CC0-1.0 |
| Загруженные пользователем материалы | Проект их не перелицензирует |

См. полную [карту лицензий](LICENSES/README.md), [текст 0BSD](LICENSE) и
[юридический текст CC0-1.0](LICENSES/CC0-1.0.txt).