iwe-org/iwe: a markdown knowledge graph with an LSP, a CLI and an MCP server

The problem IWE solves: database-style queries without a database

Most note tools force a choice. A folder tree is easy to own and impossible to query by relationship. A database-backed tool queries well and takes your notes hostage. IWE's README frames the target user directly: people who want queries such as "all drafts under this subtree" or "every accepted decision in Q1" while the notes stay as .md files in a local directory that you can read, edit and git push.

The second audience is AI agents. IWE itself contains no model. It exposes the same operations (search, retrieve, create, refactor) over a CLI and over a Model Context Protocol server, and the README positions this as retrieval by structure rather than similarity guessing. The pitch is that a note has parents, children and cross-references, and an agent that knows those can pull usable context in one call instead of assembling fragments from a vector index.

That framing also sets the boundary. If your retrieval problem is fuzzy semantic recall over prose that has no deliberate link structure, IWE does not attempt to solve it. The README says the project composes with external tooling such as ripgrep, full-text or vector search: whatever finds the note, IWE supplies the context around it.

Nesting links, cross-references and multiple parents

The mechanism is a link convention, not a schema you have to learn. A link placed on its own line means "this topic includes that subtopic"; the README calls these inclusion links, and they build the tree you browse and refactor. Inline links are cross-references and form the looser web between topics. Because inclusion is a link rather than a filesystem move, one note can sit under several parents at once. The README's example is a Meditation note belonging to both Health and Productivity without duplicating the file.

Retrieval then has something to walk. When you fetch a note, IWE can include context from the notes above it in the hierarchy, so a single call returns a topic with its surrounding structure rather than an isolated document. That is the whole trick, and it is worth being clear about the trade-off: the value of IWE is proportional to how consistently you write those standalone links. A directory of markdown with only inline links gives the graph very little to traverse.

The workspace is split into crates named liwe, diwe, iwe, iwes and iwec, with an LSP stack built on lsp-server and lsp-types and markdown parsed through pulldown-cmark and jotdown. That layout is the honest signal of what the project is: an editor-facing language server plus a CLI plus a separate MCP binary, sharing one library core.

Installing IWE and running a first query

The README's install section is written for the Claude Code plugin, and it states the only requirement plainly: the IWE CLI, version 0.20.0 or newer, on your PATH, because the plugin's hooks are iwe subcommands and it ships no runtime scripts. The plugin itself is added from its own marketplace:

/plugin marketplace add iwe-org/skills
/plugin install iwe@iwe-org

Then, inside the repository you want remembered, you initialise the workspace:

/iwe:init

The README notes that without a MEMORY.md, or without the CLI installed, every hook exits silently, so the plugin stays inert in other repositories. It also says iwe init offers to write the policy for you when it finds a .claude/ directory. That policy is what lets the background capture agent run the CLI and nothing else:

{ "permissions": { "allow": ["Bash(iwe:*)"] } }

For the CLI side, the README's example of preparing context for an AI conversation is a fuzzy search followed by a structural retrieval:

iwe find --fuzzy auth

iwe retrieve --key authentication --expand-includes 2

The first command finds an entry point by fuzzy match; the second takes a key and expands inclusion links two levels, which is where parent context enters the result. The README's benchmark page claims 20,000 files processed in under a second, a number I have not reproduced. If you do not use Claude Code, the README says the four skills reach Codex, Cursor and OpenCode through the skills CLI, installing as ordinary project skills named /init, /distill, /reflect and /graph:

npx skills add iwe-org/skills

Automatic session capture is described as a Claude Code plugin feature; other runtimes get the skills but you invoke them by hand.

What the engine refuses: expect guards and document schemas

The most opinionated part of IWE is that agent writes are checked rather than trusted. A mutation carries expect guards declaring how many documents and blocks it may touch. The whole update validates before anything is written, and a mismatch aborts with the offending blocks named. Over MCP the README says the guards are mandatory: an edit that will not declare its blast radius is refused outright.

The second check is schemas. Frontmatter and document structure are validated against per-type document schemas covering required fields, enums, ISO dates and required sections. A schema-violating MCP write is rejected with the violation named, and the same checks run on demand from the CLI via iwe schema validate. A third layer surfaces warnings for what a mutation disturbed, such as dangling links and orphan pages, and iwe stats similarity flags near-duplicates.

This is a real design position, and it has a cost. An agent that would happily append a paragraph to a loosely structured note will fail here until the note conforms. Teams that treat frontmatter as optional will spend their first sessions fixing documents instead of writing. The payoff is that an agent cannot silently rewrite forty files when it meant to touch one, which is the failure mode that makes people distrust automated note editing in the first place.

MCP server, editor support and the OKF format

IWE ships a server binary named iwec that speaks the Model Context Protocol, so tools such as Claude Desktop, Cursor and Windsurf can work with the notes directly. The README states the server watches your files for changes, so edits made in your editor are reflected immediately rather than after a restart. The CLI and the MCP server expose the same operations, so choosing between them is about your setup, not about capability.

On the editor side, the README lists real LSP integration for VS Code, Neovim, Zed and Helix, with search, refactor, rename and autocomplete. That is a narrower list than a general-purpose language server, and it reflects the project's scope: this is not a markdown linter you can bolt onto any client, it is a server whose features assume the inclusion-link convention.

IWE also speaks OKF, the Open Knowledge Format, which the README describes as markdown with YAML frontmatter, the format IWE already manages. Three commands are named for it: iwe init --okf scaffolds a conformant bundle, iwe schema validate checks conformance mechanically, and iwe find --filter '{type: …}' queries OKF frontmatter directly. If you already keep a knowledge catalog in that format, this is the shortest path into the project.

Where IWE is the wrong tool

The README is explicit that IWE has no built-in AI. If you want a tool that summarises, embeds or answers questions on its own, this is not it; you bring Claude, Codex, Gemini or any MCP client, and IWE supplies structure. Projects that expect the note tool to be the model will be disappointed.

The second limitation is structural rather than technical. Everything valuable here depends on links that someone wrote on purpose. Import a thousand markdown files with no inclusion links and the graph is a flat list; the parent context that retrieval promises does not exist to be fetched. The README's own framing, retrieval by structure rather than similarity guessing, is a description of the requirement as much as the feature.

A third boundary is operational. The MCP path means running the iwec server and granting an agent permission to call iwe, which the README handles with an explicit allow rule for Bash(iwe:*). Organisations that will not let an agent execute a CLI against their notes have a real reason to stop at the editor LSP, where the same graph is available with no agent in the loop. The README does not document rollback for a rejected or partially applied mutation beyond the fact that validation happens before any write.

Compared with Obsidian and Logseq

The closest alternatives are Obsidian and Logseq, and the difference is architectural rather than cosmetic. Both of those are applications that own a vault: they render the graph, they run plugins inside their own process, and their link semantics are defined by the app. IWE is a set of binaries and a library. There is no vault to open, and the graph is consumed by an editor through LSP or by an agent through MCP.

That inversion has consequences. You lose the polished browsing UI and the plugin ecosystem. You gain the ability to put the graph inside a script, a CI check or an agent's tool list, and you gain the expect-guard and schema validation layer that an app plugin would have to reimplement. For a solo writer who wants a pleasant interface for their notes, Obsidian is the more direct answer. For a team that wants markdown in git, checked mutations and an agent-readable structure, IWE is addressing a problem those apps were not built around.

The honest caveat is maturity of surface area. Obsidian and Logseq have years of accumulated workflows and community answers. IWE's README points to its own docs, discussions, subreddit and an X account, and the concepts pages it links are the authoritative place to check before you restructure an existing vault.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-24, which is recent. Releases are frequent: iwe-v0.20.1 landed on 2026-08-24, iwe-v0.20.0 on 2026-08-24, and iwe-v0.19.1 on 2026-08-15. The workspace Cargo.toml declares version 0.24.0 with rust-version 1.82, so the crates and the release tags are moving at their own pace, and a pre-1.0 version number means the CLI surface can change between minor releases. The README's own plugin instructions pin a floor of 0.20.0 for the CLI, which is the practical upgrade constraint: plugin hooks call iwe subcommands, so a CLI older than the plugin expects will fail at the hook rather than at install.

Licensing is Apache-2.0, declared both in the repository's LICENSE-APACHE file and in the workspace package metadata. That is a permissive licence with an explicit patent grant, which matters if you embed the crates rather than just run the binary. It is not legal advice, and if you redistribute a modified iwe inside a product, read the licence text and your own counsel's view of the notice requirements.

The upgrade cost is mostly your own content, not the binary. Schemas are per-type and validated on write, so tightening a schema in a new version can turn previously accepted frontmatter into a rejected write. Run iwe schema validate across the workspace after any CLI upgrade and before you let an agent write again.

Editorial conclusion

Adopt IWE if your notes already live in git as markdown and you want editors and agents to read the same link structure, and if you are willing to run a Rust CLI plus, for MCP, the iwec server. Do not adopt it if you need embeddings-based retrieval, a hosted sync service, or a GUI for non-technical collaborators; the README describes none of those. Before committing, verify two things on your own corpus: that your nesting links follow the inclusion-link convention the concepts page describes, and that iwe schema validate passes on the frontmatter you already have, since a schema-violating write is rejected rather than coerced.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes