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 可处理任何 Markdown 文件夹：Obsidian vault、项目工作文件夹或单独的文档文件夹。

在以下示例中，将 /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

连接后，请 Agent：

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

---

嵌入

即使没有 embedding 服务，LINZA 也能启动并显示工具。语义搜索、主题图谱和关联建议则需要嵌入。

最简单的本地方式是使用 LM Studio：

1. 打开 LM Studio。
2. 下载嵌入模型，例如 text-embedding-granite-embedding-278m-multilingual、nomic-embed-text-v1.5 或其他合适的模型。
3. 启动 Local Server。
4. 确认 endpoint 可通过 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-compatible endpoint。

如果更换提供方、模型或维度，请执行完整重建索引。LINZA 会检查 embedding signature；如果 sidecar 已过期或包含混合向量空间，就会停止 graph/search 工作流。

---

主要 MCP 工具

默认情况下，LINZA 仅显示 7 个 MCP 工具。日常使用已足够：检查状态、为文件夹建立索引、搜索、读取文件、查看计数、诊断 vault，以及通过 agent_workspace 引导 Agent。

工具	用途
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	否	embeddings API 的 URL；默认值为 http://127.0.0.1:1234/v1
LINZA_EMBED_MODEL	否	嵌入模型；请在语义索引／搜索前设置
LINZA_EMBED_KEY	否	OpenAI-compatible embeddings 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 许可证 (c) 2026 Maria Belkina

余弦值在计算。语法在变化。语义仍在。