LINZA

Name: LINZA
Author: Semiotronika

CommunityIncomplete39/100Claim

pypi linza-mcpstdioMITupdated 26d ago

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

Source Website4

What can you do with LINZA?

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

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

English version

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

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

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

Зачем нужна LINZA

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

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

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

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

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 так думает? В нем должны быть источники, чанки, тип связи, уверенность и честное описание того, что изменится после применения.

Обучение и рост

Модель автономности такая:

review_next показывает предложения в понятном пользовательском виде.
Пользователь принимает, переименовывает или пропускает.
apply_review_items сначала делает dry-run.
После подтверждения выбранный интент записывается в .linza или в компактный YAML, если этот тип записи это поддерживает.
teach выбирает хорошие принятые примеры.
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

Если нужно читать PDF прямо через LINZA:

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

После подключения попросите агента:

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

Эмбеддинги

LINZA может запуститься и показать инструменты без embedding-сервера. Эмбеддинги нужны для смыслового поиска, карты тем и предложений связей.

Самый простой локальный путь - LM Studio:

Открыть LM Studio.
Скачать embedding-модель, например text-embedding-granite-embedding-278m-multilingual, nomic-embed-text-v1.5 или другую подходящую модель.
Запустить Local Server.
Проверить, что 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 - любой OpenAI-compatible endpoint с /embeddings.

Если меняете провайдер, модель или размерность, сделайте полный реиндекс. LINZA проверяет embedding signature и останавливает graph/search workflows, если sidecar устарел или содержит смешанные векторные пространства.

Основные MCP-инструменты

По умолчанию LINZA показывает только 7 MCP-инструментов. Этого хватает для обычной работы: проверить состояние, проиндексировать папку, искать, читать файл, смотреть счетчики, диагностировать 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`	Нет	URL embeddings API; по умолчанию `http://127.0.0.1:1234/v1`
`LINZA_EMBED_MODEL`	Нет	Модель эмбеддингов; задайте перед semantic indexing/search
`LINZA_EMBED_KEY`	Нет	Опциональный ключ для OpenAI-compatible embeddings API
`LINZA_BRIDGE_THRESHOLD`	Нет	Порог semantic bridge; по умолчанию `0.55`
`LINZA_MAX_BRIDGE_PAIRS`	Нет	Максимум пар заметок для пересчета semantic bridges; по умолчанию `1000000`, `0` отключает guard
`LINZA_DEFAULT_PROFILE`	Нет	Имя базового search-профиля; по умолчанию `general`
`LINZA_LANGUAGE`	Нет	Язык подсказок и маршрута ревью в `guide_next_steps`: `auto`, `ru`, `en`

Ссылки

Косинусы считаются. Синтаксис меняется. Семантика остается.

Install

Add LINZA to your client. Pick the one you use.

claude mcp add linza-mcp -- uvx linza-mcp

codex mcp add linza-mcp -- uvx linza-mcp

amp mcp add linza-mcp -- uvx linza-mcp

{
  "mcpServers": {
    "linza-mcp": {
      "command": "uvx",
      "args": [
        "linza-mcp"
      ]
    }
  }
}

Add to `claude_desktop_config.json`, then restart Claude Desktop.

{
  "mcpServers": {
    "linza-mcp": {
      "command": "uvx",
      "args": [
        "linza-mcp"
      ]
    }
  }
}

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.

code --add-mcp '{"name":"linza-mcp","command":"uvx","args":["linza-mcp"]}'

Or add the block manually to `.vscode/mcp.json` under `servers`.

{
  "mcpServers": {
    "linza-mcp": {
      "command": "uvx",
      "args": [
        "linza-mcp"
      ]
    }
  }
}

Add to `~/.codeium/windsurf/mcp_config.json`.

{
  "mcpServers": {
    "linza-mcp": {
      "command": "uvx",
      "args": [
        "linza-mcp"
      ]
    }
  }
}

Add to `cline_mcp_settings.json` via the MCP Servers panel.

{
  "mcpServers": {
    "linza-mcp": {
      "command": "uvx",
      "args": [
        "linza-mcp"
      ]
    }
  }
}

Add to `~/.gemini/settings.json`.

{
  "mcpServers": {
    "linza-mcp": {
      "type": "local",
      "command": "uvx",
      "args": [
        "linza-mcp"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Add to `~/.copilot/mcp-config.json`, or run `/mcp add` inside the CLI.

{
  "context_servers": {
    "linza-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "linza-mcp"
        ]
      }
    }
  }
}

Add to your Zed `settings.json`.

uvx linza-mcp

Run `goose configure`, choose **Add Extension → Command-line Extension**, and paste this command.

Versions	Published
0.2.2Latest	Jun 1, 2026
0.1.4	May 19, 2026
0.1.3	May 19, 2026

LINZA

What can you do with LINZA?

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

Зачем нужна LINZA

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

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

Обучение и рост

Установка

1. Установить пакет

2. Выбрать папку

3. Подключить MCP-клиент

4. Проверить запуск

Эмбеддинги

Основные MCP-инструменты

Режимы `agent_workspace`

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

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

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

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

Проверка

Переменные окружения

Ссылки

Install

Score

Version history

What can you do with LINZA?

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

Зачем нужна LINZA

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

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

Обучение и рост

Установка

1. Установить пакет

2. Выбрать папку

3. Подключить MCP-клиент

4. Проверить запуск

Эмбеддинги

Основные MCP-инструменты

Режимы agent_workspace

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

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

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

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

Проверка

Переменные окружения

Ссылки

Install

Score

Version history

Режимы `agent_workspace`