LINZA is a local MCP server for agents to work with knowledge folders. Its positioning is "do not change the data, change the perspective." LINZA is suitable for Obsidian vaults, Markdown folders, documents, articles, journals, and drafts. It can be used when there is too much material, when a knowledge base needs to be organized, when main domains need to be divided, and when agents need to navigate within it better.
Main capabilities
LINZA reads a selected folder, builds a local SQLite database .linza/linza.db alongside it, and provides agents with a work map, including:
- Folder map: how many notes were found, whether the index is up to date, which domains are visible, and which materials are awaiting review.
- Domains: larger semantic groupings whose names remain drafts until the user accepts or renames them.
- Material formats: recurring note forms such as journals, drafts, specs, research notes, cases, rules, etc.
- Associations: possible neighboring relationships, hierarchies, causalities, and paths between nodes, with an explanation of why they are related.
- Memory for future agents: brief candidates explaining what to remember, when to recall it, and what is outdated or questionable.
- Context packages: compact context prepared for agents, including sources, associations, and boundaries.
Material formats
A "material format" is the user's name for a recurring note form. LINZA initially sees only structure (length, headings, lists, links, tables, folders, recurring features), so the first result may be neutrally named type-001. The user can state "this is a journal," and LINZA then stores the correspondence type-001 -> journal in .linza. Internally, the API retains the compatible keys material_type, type_name, and role; external documentation and the user view use "format." Accepting a format name means writing the decision into .linza; writing role: journal in YAML can only be done through a separate review proposal; the note body does not change.
Review flow
LINZA returns user-readable proposals, each internally retaining an ID, evidence, and data awaiting confirmation. A good proposal answers "why does LINZA think this," including sources, chunks, association type, confidence, and an honest description of what will happen after applying it.
Autonomous model:
- review_next displays proposals in a user-readable form.
- The user accepts, renames, or skips.
- apply_review_items first performs a dry-run.
- After confirmation, the selected intent is written into .linza, or into compact YAML when supported.
- teach selects good accepted examples.
- grow proposes similar intents based on these examples and explains why selected_rules entered that batch. If something wrong is accepted, approval can be gently revoked: LINZA does not delete old records and does not automatically roll back YAML; instead, it marks the approval as revoked, stops using it as an active example, and leaves a trace in the history.
Installation and Usage
- Install the package. A normal installation is enough to handle Markdown, TXT, JSON, DOCX, and XLSX; [pdf] additionally adds the local PDF extractor pypdf.
- Choose a folder. LINZA can handle any Markdown folder: an Obsidian vault, a project work folder, or a standalone document folder. In the examples, /absolute/path/to/workspace-or-vault must be replaced with the actual path.
- Connect an MCP client. MCP clients such as Claude Desktop, Cursor, and OpenCode usually use the standard format; VS Code / Copilot MCP uses the servers key. LINZA_VAULT is not required at startup; when it is not set, the server uses ./vault, but for actual use it is recommended to specify the folder explicitly.
- Verify startup. After connecting, have the agent call the relevant tools. LINZA can start and display tools without an embedding server; embeddings are used for semantic search, topic maps, and association suggestions.
The simplest local embedding path is LM Studio: open LM Studio, download an embedding model (such as text-embedding-granite-embedding-278m-multilingual, nomic-embed-text-v1.5, or another suitable model), start the Local Server, and confirm that the endpoint http://127.0.0.1:1234/v1 is available. Supported providers include lmstudio (the recommended local mode), ollama (a local option via Ollama), and openai (any OpenAI-compatible endpoint with /embeddings). If the provider, model, or dimensions are changed, a full index rebuild is required; LINZA checks the embedding signature and stops graph/search workflows when the sidecar is stale or contains mixed vector spaces.
MCP Tools
By default, LINZA shows only 7 MCP tools, which are enough for routine work: check status, index a folder, search, read files, view counts, diagnose the vault, and guide the agent via agent_workspace. Lower-level tools are treated as implementation details and are accessed through agent_workspace. Development and auditing can use a separate lower-level mode; full tool descriptions are in the Tool Catalog.
Incoming Material
LINZA can receive material that is not yet a note: pasted text, local .md/.txt/.json, local .docx/.xlsx, local .pdf (requires pypdf or PyPDF2 to be installed). LINZA itself does not access the browser; the agent uses its own browser, web-fetch, or connector to extract readable text and passes it to LINZA as an artifact, for example source_kind="web_article" or source_kind="browser_capture". Imported text is treated as analysis material, not as agent instructions; this is the prompt injection boundary: instructions in articles, logs, chats, or PDFs will not be executed. Memories, rules, and YAML appear only after review.
Security Model
LINZA is a local, review-gated sidecar. Additional rules: review_next writes nothing; apply_review_items defaults to dry-run; visible YAML edits are compact and require precisely selected IDs; history shows what has been accepted and revoked; revoke_approval gently revokes approval, the history is retained but active learning and the graph assistant ignore it; if a source file changes after indexing, map, teach, grow, and connect stop.
Agent Instructions
The repository contains portable operational skills that explain how the agent starts with doctor,When to show review proposals, how to handle pages via external browser/web-fetch tools, and why apply operations should go through a dry-run first and use only exact IDs.
Limitations and Status
LINZA is currently in alpha. The core safety contract should remain stable: indexing, material import, search, maps, and grow preview do not rewrite the original note body. Low-level advanced tools and internal code boundaries may still change while the server is being polished. See the repository for how to run the full test suite. See the repository for environment variables and more details. The project is licensed under MIT (c) 2026 Semiotronika.
