IWE: A Markdown Knowledge Graph with LSP, CLI, and MCP for Notes and Agents

The Problem: Notes Without Structure and Agents Without Context

IWE addresses a specific pain: your Markdown notes are a folder tree, but your questions are graph-shaped. You want to ask 'all drafts under this subtree' or 'every accepted decision in Q1' without moving your notes into a database. For AI agents, the problem is worse: they retrieve by similarity, not by structure, so they guess at context instead of knowing it. IWE is for people who write Markdown, link notes together, and want both their editor and their AI agents to navigate that structure. The README positions it as a memory system for you and your AI agents, with no cloud, no database, and no lock-in. It is not for everyone: if your notes are a pile of untitled files, the graph model gives you nothing to query.

The Mechanism: Inclusion Links, Cross-References, and Multiple Parents

IWE's core is a graph built from two kinds of links. Nesting links, called inclusion links, are a link on its own line meaning 'this topic includes that subtopic.' Regular inline links are cross-references that connect notes across topics. The same note can have multiple parents, so a 'Meditation' note can live under both 'Health' and 'Productivity' without duplicating the file. When you retrieve a note, IWE can include context from the notes above it in the hierarchy. This is the mechanism that makes retrieval powerful: a single call returns a topic plus its parent context, children, and cross-references. The graph is not a folder tree; it is a connected structure you browse in your editor and query from the command line. The README gives an example: `iwe find --fuzzy auth` finds an entry point, and `iwe retrieve --key authentication --expand-includes 2` expands the context.

Editor Integration: An LSP for VS Code, Neovim, Zed, and Helix

IWE ships a real LSP integration, which is a concrete feature for daily use. The documentation covers setup for VS Code, Neovim, Zed, and Helix. The LSP gives you search, refactor, rename, and autocomplete on your notes. This is not a plugin that opens a separate web view; it is a language server that understands the graph. The README does not give the exact LSP client configuration commands, so you would need to consult the docs at iwe.md/docs/editors/. The LSP is a significant differentiator: most note tools offer a web UI or a mobile app, but an LSP means your editor becomes the browser. The trade-off is that you must be comfortable configuring an LSP client in your editor, which is a non-trivial step for new users.

Getting It Running: CLI, Init, and the Claude Code Plugin

Installation is via the CLI, which is a Rust binary available on crates.io. The README shows two install paths. For Claude Code, you add a plugin: `/plugin marketplace add iwe-org/skills` and `/plugin install iwe@iwe-org`. Then in a repository you run `/iwe:init`. The plugin ships no runtime scripts; the only requirement is the IWE CLI version 0.20.0 or newer on your PATH. For other runtimes like Codex, Cursor, and OpenCode, you install skills via `npx skills add iwe-org/skills`, which gives you four project skills: `/init`, `/distill`, `/reflect`, and `/graph`. The README also mentions `iwe init --okf` to scaffold an Open Knowledge Format bundle, and `iwe schema validate` to check conformance. The CLI is the primary interface; the MCP server is a separate binary called `iwec`.

Agent Memory: The Claude Code Plugin and the `graph` Skill

The plugin for Claude Code captures what a session established into the repository's own IWE workspace. The README emphasizes that this memory is markdown you review as an ordinary diff, not a store you cannot inspect. The plugin carries the `graph` skill, which gives the agent bounded, graph-aware routes for finding, retrieving, creating, and refactoring notes. Automatic session capture is specific to the Claude Code plugin; other runtimes get the skills, invoked by hand. The plugin's background capture agent runs the CLI and nothing else, with a permission allowlist: `{ "permissions": { "allow": ["Bash(iwe:*)"] } }`. Without a `MEMORY.md` or without the CLI installed, every hook exits silently, so the plugin stays inert in other repositories. This is a thoughtful design: it does not interfere unless you opt in.

Write Safety: `expect` Guards and Schema Validation

IWE does not trust agent writes. A mutation carries `expect` guards stating how many documents and blocks it may touch. The whole update validates before anything is written; a mismatch aborts with the offending blocks named. Over MCP, the guards are mandatory: an edit that will not declare its blast radius is refused. Additionally, 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. From the CLI, `iwe schema validate` runs the same checks on demand. The README also mentions `iwe stats similarity` to flag near-duplicates. This is a real safety net for agent-driven edits, but it also means you must define schemas for your note types, which is an upfront cost.

Limitations and When IWE Is the Wrong Tool

IWE has no built-in AI. It works alongside Claude, Codex, Gemini, and any MCP-speaking tool, but it does not generate embeddings or do semantic search. The README says it pairs search with structure: fuzzy and full-text search finds the entry point, and the graph turns a hit into context. If you rely on vector similarity for retrieval, IWE is not a replacement; it composes with external tooling like ripgrep or vector databases, but you must wire that yourself. Another limitation is the linking model: you must organize notes with inclusion links and cross-references. If your notes are flat or you dislike link maintenance, the graph will be sparse and queries will return little. The benchmark claim of processing 20,000 files in under a second is in the docs, but the README does not specify the hardware or the exact test, so you should verify it on your own corpus.

Alternatives: How IWE Differs from Obsidian, Foam, and Vector Tools

The closest alternative is Obsidian, which also builds a graph from Markdown links and offers plugins for AI. The difference is architectural: Obsidian is a GUI application with a proprietary plugin ecosystem, while IWE is a CLI, LSP, and MCP server that you run locally. IWE's graph is queryable via commands and MCP, which means agents can navigate it programmatically; Obsidian's graph is primarily visual and its automation is less standardized. Another alternative is Foam, a VS Code extension that uses Markdown links and provides a graph view. Foam is editor-bound, whereas IWE's LSP works across multiple editors and its CLI is runtime-agnostic. For AI retrieval, vector databases like Pinecone or pgvector use similarity, not structure. IWE explicitly rejects similarity guessing in favor of structural retrieval. The README says it composes with vector tools, but the core value is graph context, not embeddings.

Maintenance and License: Apache-2.0, Active Development, and Upgrade Path

The project is licensed under Apache-2.0, which is permissive for commercial use, but you should read the license text for specifics. The repository is not archived, and the last push was 2026-08-24, with releases v0.20.1, v0.20.0, and v0.19.1 in August 2026. This indicates active maintenance, but it also means the CLI and MCP server may change between versions. The README mentions the plugin requires CLI 0.20.0 or newer, so you need to keep the CLI updated to match the plugin. The skills install via `npx skills add iwe-org/skills`, which suggests a separate update path. The documentation is hosted at iwe.md, and there is a GitHub discussions page for support. The upgrade cost is moderate: you must track CLI releases and test your schemas and MCP configuration after each update, but the plain Markdown format means your data itself is never locked in.

Editorial conclusion

Adopt IWE if you want database-style queries over plain Markdown notes, with editor integration and agent access via MCP, and you are comfortable with a Rust CLI and a specific linking model. Avoid it if your notes are unstructured or you need built-in AI features, as IWE has no AI of its own. Before adopting, verify that your editor has a working LSP client, that your notes can be organized with inclusion links and cross-references, and that your AI tools support MCP or can invoke the CLI. Check the benchmark claim of processing 20,000 files in under a second against your own note volume, and ensure your workflow accepts mandatory `expect` guards for MCP writes.

Official sources

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