LINZA

LINZA - локальный MCP-сервер для агентской работы с папками знаний

Не меняет данные. Меняет взгляд.

LINZA работает с Obsidian vault, Markdown-папками, документами, статьями, логами и черновиками. Она нужна, когда материалов уже слишком много и вы хотите разобрать базу, выделить в ней основные области и научить агента хорошо ориентироваться в ней.

English version

LINZA читает выбранную папку, строит рядом локальную SQLite-базу .linza/linza.db и дает агенту рабочую карту: какие темы есть в материалах, какие форматы повторяются, какие заметки могут быть связаны, где видны цепочки причина/следствие и что может пригодиться в будущих сессиях.

Исходные файлы остаются нетронутыми. LINZA не переписывает заметки при индексации, не превращает сырой лог в правило и не учит агента за вашей спиной. Она превращает гипотезы в короткие предложения: возможные действия с доказательствами. Пользователь решает, агент выполняет.

doctor -> index -> map -> review intents -> teach -> grow preview -> explicit apply

---

Зачем нужна LINZA

LINZA собирает несколько конкретных вещей, которые помогают агентам работать с базой:

1. Карта папки Сколько заметок найдено, свежий ли индекс, какие области видны и какие материалы ждут вашего ревью.

2. Области Крупные смысловые группы. Их названия остаются черновиками, пока вы не примете или не переименуете их.

3. Форматы материалов Логи, черновики, спецификации, исследовательские заметки, кейсы, правила и другие повторяющиеся формы, найденные в папке.

4. Связи Возможные соседства, иерархия, причина/следствие и маршруты между узлами. LINZA должна показывать не только как связаны документы, но и почему.

5. Память для будущих агентов Короткие кандидаты: что помнить, когда вспоминать, что устарело или выглядит сомнительно.

6. Пакеты контекста Компактные подборки для агента: выбранный контекст с источниками, связями и границами.

---

Форматы материалов

“Формат материала” - это пользовательское имя для повторяющейся формы заметок. Например: лог диагностики, решение, черновик статьи, исследовательская заметка, спецификация.

LINZA сначала видит только структуру: длину, заголовки, списки, ссылки, таблицы, папки, повторяющиеся признаки. Поэтому первый результат может называться нейтрально: type-001. Пользователь может сказать: “это логи”. Тогда LINZA сохраняет соответствие type-001 -> логи в .linza.

Внутри API остаются старые совместимые ключи material_type, type_name и role. Снаружи документация и пользовательский вид говорят “формат”, потому что это ближе к тому, как пользователь реально думает о материалах.

Важная граница:

• принять название формата значит записать решение в .linza;
• записать role: логи в YAML можно только отдельным предложением на ревью;
• текст заметки не меняется.

---

Как выглядит ревью

LINZA присылает примерно такую информацию:

LINZA готова

Материал:
- 42 заметки проиндексированы
- 3 входящих артефакта ждут ревью
- служебная база: .linza/linza.db

Следующий шаг:
1. Посмотреть найденные области
2. Принять, переименовать или пропустить 3-5 предложений
3. Ничего не будет записано без dry-run/apply

Предложение:
Принять формат материала "логи диагностики" по 8 примерам
Почему: похожая структура, повторяющиеся заголовки, близкие чанки
Что изменится: название формата сохранится в .linza; Markdown-заметки не меняются

Внутри каждый интент остается структурой с ID, доказательствами и готовыми данными для проверки и последующего подтверждения и записи. Вам LINZA возвращает готовое пользовательское представление, чтобы агент мог показать понятный ответ вместо JSON.

Хороший интент всегда отвечает на главный вопрос: почему LINZA так думает? В нем должны быть источники, чанки, тип связи, уверенность и честное описание того, что изменится после применения.

---

学習と成長

自律性のモデルは次のとおりです。

1. review_next は、提案をユーザーにわかりやすい形式で表示します。
2. ユーザーは承認、名前の変更、またはスキップを行います。
3. apply_review_items は、最初に dry-run を実行します。
4. 確認後、選択したインテントを .linza に記録します。この種類の記録が対応している場合は、コンパクトな YAML に記録します。
5. teach は、承認された良い例を選びます。
6. grow は、それらの例に基づいて類似のインテントを提案し、selected_rules によって、それらがバッチに含まれた理由を説明します。

誤った内容を承認した場合は、承認を取り消せます。

agent_workspace(action="history")
agent_workspace(action="revoke_approval", approval_id=17, dry_run=false)

LINZA は古い記録を削除せず、YAML を自動的にロールバックしようともしません。承認を取り消し済みとしてマークし、アクティブな例として使わなくなったことを示し、履歴に記録を残します。

---

インストール

1. パッケージをインストールする

python -m pip install linza-mcp

LINZA で PDF を直接読み取る場合は、次を実行してください。

python -m pip install "linza-mcp[pdf]"

通常のインストールで Markdown、TXT、JSON、DOCX、XLSX に対応できます。[pdf] を追加すると、ローカル PDF 抽出ツール pypdf がインストールされます。

2. フォルダーを選択する

LINZA は、Obsidian vault、プロジェクトの作業フォルダー、ドキュメント専用のフォルダーなど、任意の Markdown フォルダーで動作します。

以下の例では、/absolute/path/to/workspace-or-vault をご自身のパスに置き換えてください。

3. MCP クライアントを接続する

Claude Desktop、Cursor、OpenCode などの MCP クライアントでは、通常、次の形式を使用します。

{
  "mcpServers": {
    "linza": {
      "command": "linza-mcp",
      "env": {
        "LINZA_VAULT": "/absolute/path/to/workspace-or-vault"
      }
    }
  }
}

VS Code / Copilot MCP では、servers キーを使用します。

{
  "servers": {
    "linza": {
      "type": "stdio",
      "command": "linza-mcp",
      "env": {
        "LINZA_VAULT": "/absolute/path/to/workspace-or-vault"
      }
    }
  }
}

起動時に LINZA_VAULT を設定する必要はありません。設定されていない場合、サーバーは ./vault を使用します。ただし、実際に使用する場合は、明示的にフォルダーを指定することをおすすめします。

4. 起動を確認する

linza-mcp --version

接続後、エージェントに次のように依頼してください。

Проверь LINZA через agent_workspace(action="doctor").
Проиндексируй папку и покажи первые 3-5 предложений.

---

埋め込み

LINZA は、埋め込みサーバーがなくても起動し、ツールを表示できます。意味検索、トピックマップ、関連付けの提案には埋め込みが必要です。

最も簡単なローカル環境での方法は LM Studio です。

1. LM Studio を開きます。
2. text-embedding-granite-embedding-278m-multilingual、nomic-embed-text-v1.5、またはその他の適切なモデルなど、埋め込みモデルをダウンロードします。
3. Local Server を起動します。
4. http://127.0.0.1:1234/v1 でエンドポイントにアクセスできることを確認します。

LM Studio の環境変数の例：

$env:LINZA_EMBED_PROVIDER="lmstudio"
$env:LINZA_EMBED_URL="http://127.0.0.1:1234/v1"
$env:LINZA_EMBED_MODEL="your-embedding-model-name"

次のものに対応しています。

• lmstudio - 推奨されるローカルモード
• ollama - Ollama を使用するローカルオプション
• openai - /embeddings を備えた任意の OpenAI 互換エンドポイント

プロバイダー、モデル、または次元数を変更した場合は、全件を再インデックスしてください。LINZA は埋め込みのシグネチャを検証し、サイドカーが古い場合や、異なるベクトル空間が混在している場合は、グラフ／検索のワークフローを停止します。

---

主な MCP ツール

デフォルトでは、LINZA は MCP ツールを 7 つだけ表示します。通常の作業にはこれで十分です。状態の確認、フォルダーのインデックス作成、検索、ファイルの読み取り、カウンターの確認、vault の診断、agent_workspace を通じたエージェントの操作ができます。

ツール	用途
agent_workspace	診断、マップ、インポート、レビュー、学習、成長、関連付け、メモリ、コンテキストのエクスポートをまとめて行うための入口
guide_next_steps	次の安全な手順を、わかりやすい言葉で表示
index_all	Markdown フォルダーを .linza/linza.db にインデックス
search	意味検索と語彙検索
read_file	指定した Markdown ファイルを読み取り
get_stats	サービスデータベースのカウンターをすばやく確認
scan_vault	書き込みを行わずにフォルダーを診断

低レベルのツールは実装の詳細とみなされ、agent_workspace を通じて利用できるため、7 つのツールだけで完全なモードとして使用できます。

Режимы agent_workspace

Action	Режим
doctor	Проверить готовность LINZA и показать, чего не хватает
map	Собрать карту рабочей папки без записи
teach	Выбрать сильные принятые примеры для обучения
grow	Показать или применить рост по принятым примерам; по умолчанию dry-run
review_next	Показать следующие предложения на ревью; интенты базы имеют ID rq-*, интенты артефактов и рабочей папки - aw-*
apply_review_items	Показать или применить точные выбранные ID; по умолчанию dry-run
history	Показать принятые и отозванные одобрения
revoke_approval	Мягко отозвать одобрение, не удаляя историю
ingest_artifacts	Сохранить вставленный или извлеченный материал в sidecar
analyze_inbox	Найти события, кандидаты памяти и фрагменты знания в артефактах
connect	Объяснить возможную связь между двумя заметками или узлами
search_memory	Искать по подтвержденной памяти и контексту артефактов
export_context	Собрать компактный пакет контекста для другого агента
record_trace	Сохранить структурированные следы работы агента, не raw chain-of-thought
analyze_trace	Разобрать сохраненный trace для ревью
review_calibr	Проверить уроки калибровки, полученные из traces

Для разработки и аудита остается отдельный низкоуровневый режим. Полное описание инструментов: Tool Catalog.

---

Входящие артефакты

LINZA умеет принимать материал, который еще не стал заметкой:

• вставленный текст;
• локальные .md, .txt, .json;
• локальные .docx, .xlsx;
• локальные .pdf, если установлен pypdf или PyPDF2.

LINZA сама не ходит в браузер. Агент использует свой браузер, web-fetch или connector, извлекает читаемый текст и передает его в LINZA как артефакт, например source_kind="web_article" или source_kind="browser_capture".

Импортированный текст считается материалом для анализа, не инструкцией для агента. Это граница prompt injection: инструкции внутри статьи, лога, чата или PDF не исполняются. Память, правила и YAML появляются только после ревью.

---

Модель безопасности

LINZA - локальный review-gated sidecar.

Действие	Куда пишет	Меняет текст заметок?
Индексация, анализ, поиск	.linza/linza.db	Нет
Сырые артефакты	.linza/linza.db	Нет
Название формата материала	.linza/linza.db	Нет
domains или role в YAML	Только компактный YAML после ревью	Нет
Иерархия, причинные связи, память, уроки калибровки	.linza/linza.db	Нет
Отчеты	.linza/reports	Нет
Пакеты контекста	.linza/context-packs	Нет
write_file	Markdown-файл только при явном запросе	Может создать/заменить файл, dry-run по умолчанию

Дополнительные правила:

• review_next ничего не пишет;
• apply_review_items по умолчанию dry-run;
• видимые YAML-правки компактные и требуют точного выбранного ID;
• history показывает, что было принято и что отозвано;
• revoke_approval мягко отзывает одобрение: история остается, но активное обучение и помощники графа его игнорируют;
• map, teach, grow и connect останавливаются, если исходные файлы изменились после индексации.

---

Инструкции для агентов

В репозитории есть переносимый операторский skill:

agent-pack/skills/linza-operator/SKILL.md
agent-pack/skills/linza-operator/references/workflows.md
agent-pack/skills/linza-operator/references/safety-policy.md
agent-pack/skills/linza-operator/references/tool-audience.md

Он объясняет агенту, как начинать с doctor, когда показывать предложения на ревью, как работать со страницами через внешний browser/web-fetch инструмент и почему apply actions должны идти сначала через dry-run и только по точным ID.

---

Стабильность

LINZA пока alpha. Основной контракт безопасности должен оставаться стабильным: индексация, импорт артефактов, поиск, карта и grow preview не переписывают тела исходных заметок. Низкоуровневые advanced-инструменты и внутренние границы кода еще могут меняться, пока сервер полируется.

---

Проверка

Запустить полный набор тестов:

python -m unittest discover -s tests

---

環境変数

変数	起動に必要ですか？	説明
LINZA_VAULT	いいえ	Markdown フォルダーへのパス。デフォルトは ./vault です
LINZA_EMBED_PROVIDER	いいえ	推奨されるローカルモードには lmstudio を指定します。openai と ollama も使用できます
LINZA_EMBED_URL	いいえ	埋め込み API の URL。デフォルトは http://127.0.0.1:1234/v1 です
LINZA_EMBED_MODEL	いいえ	埋め込みモデル。セマンティックインデックス作成／検索を行う前に設定してください
LINZA_EMBED_KEY	いいえ	OpenAI 互換の埋め込み API 用のオプションキー
LINZA_BRIDGE_THRESHOLD	いいえ	セマンティックブリッジのしきい値。デフォルトは 0.55 です
LINZA_MAX_BRIDGE_PAIRS	いいえ	セマンティックブリッジの再計算対象となるメモのペア数の上限。デフォルトは 1000000 で、0 を指定するとガードが無効になります
LINZA_DEFAULT_PROFILE	いいえ	基本の検索プロファイル名。デフォルトは general です
LINZA_LANGUAGE	いいえ	guide_next_steps のヒントとレビュー経路の言語：auto、ru、en

---

リンク

• semiotronika.ru
• PyPI
• GitHub

MIT License (c) 2026 Maria Belkina

コサインは計算されます。構文は変化します。意味は残ります。