← Back to directory
I

IWE

Official
Turn a folder of Markdown notes into a queryable knowledge graph for you and your AI agents
Category
Filesystem #13 of 24
Stars
★ 1.8k Very popular
Transport
stdio (local process)
Runtime
Node.js · Prebuilt binary
Credentials
No credential needed
License
Apache-2.0
Last commit
Tools
5
56FMRS · C

IWE is an Apache-2.0, Rust-built, local-first knowledge graph and memory system that turns a markdown directory into a graph and exposes it through an editor LSP plus a CLI and an MCP server (iwec over stdio, also runnable via npx as @iwe-org/mcp). It pairs fuzzy/full-text search with graph structure so one retrieve call returns parent context, children, and cross-references, and it enforces declared blast-radius guards and schema validation on agent writes. It suits people who keep knowledge as plain markdown and want AI agents retrieving structured context rather than similarity guesses; it is not for those wanting cloud hosting, a built-in AI model, or a stable library-level API. The main risks are the agent's write access to the notes directory and the network dependency introduced by running the server through npx.

Strongest · Documentation 13/20 Weakest · Reliability 8/20

Reliability
8/20
Security and permissions
11/20
Maintenance
13/20
Documentation
13/20
Setup experience
11/20
Why each score
Reliability 8/20
Static review sees only the README and server.json; nothing was executed, and no CI workflow or committed test covering MCP initialization or the tool-list handshake is present in the supplied material, so the calibration cap of 12 applies. The described iwec behavior (serving the current notes directory, watching file changes, mandatory expect write guards, schema validation) is internally consistent with the manifest's npm package @iwe-org/mcp over stdio, but both versions are 0.0.0 placeholders, so release-to-source correspondence and the match between declared and actual tools cannot be verified. Error handling and dependency controllability are unverifiable — deducted.
Security and permissions 11/20
No malware, credential theft, or covert exfiltration appears: the manifest declares no network endpoints or secret env vars, and the README states local-first with no cloud or database, running inside the user's notes directory. Open concerns remain: the MCP surface includes mutating operations (create/update/rename/delete); the README claims expect guards are mandatory over MCP, yet there is no verifiable permission model, filesystem boundary (whether reads/writes can escape cwd), or explicit confirmation flow for dangerous operations, and npx -y pulls a remote package without disclosed integrity or signature checks. No red line is triggered, but confidence in least privilege and confirmation is insufficient, so the score is deliberately conservative.
Maintenance 13/20
The repository is not archived, has zero open issues, and shows active signals: a documentation site, Discussions plus Twitter/Reddit channels, editor plugins and skills ecosystem repos, and a clear Apache-2.0 license. However, static evidence contains no commit history, release cadence, dependency update record, or security response channel (e.g. SECURITY.md), and the manifest sits at 0.0.0, indicating a versioning/governance gap. Sustained maintenance cannot be confirmed, so points are deducted.
Documentation 13/20
Documentation layers are reasonably complete: the README covers installation (brew/npm/cargo/conda), MCP client configuration examples including cwd, a core CLI command table, editor integrations, and OKF support, with links to iwe.md pages for the CLI Reference, MCP Server, and Working with AI. Deductions: MCP tool parameters, response shapes, error formats, directory permission boundaries, and troubleshooting are not given as reviewable text in this repository but delegated to external links that cannot be verified here; rate limits, cost, and data-boundary disclosures are absent.
Setup experience 11/20
The install path is clear and multiplatform, with Homebrew, npm global install, Cargo, and conda commands, and MCP client config given as two JSON examples (direct iwec and npx -y @iwe-org/mcp) with cwd set — few steps. But per the static calibration, setup cannot exceed 15 without verifiable execution evidence (CI plus tests), and points are also deducted for the split naming between the npm package (@iwe-org/mcp) and the CLI (@iwe-org/iwe), the manual requirement to point the working directory at the notes folder, and 0.0.0 versions that make the usable release unconfirmable.

Static review · not runListed 2026-09-10

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local files

Best for

  • Individuals whose knowledge lives in plain markdown files and who value local-first, git-versioned notes.
  • AI agent users who want their note graph as agent memory and want retrieval by structure rather than similarity guessing.
  • Developers and writers who use both an editor LSP workflow and the command line over the same notes.
  • Teams that need agent writes to declare their blast radius and to pass schema and graph-hygiene checks.

Not for

  • People who want a cloud-hosted notes or memory service with no local file directory.
  • Users expecting the server to include its own AI model or inference — IWE has no built-in AI and must be paired with an external agent.
  • Scenarios that only need generic vector search and do not care about note hierarchy or link structure.
  • Builders who need a stable library-level API — the liwe crate is published but not yet API-stable.

Required permissions

  • Read markdown note files under the working directory the server is started in.
  • Write and modify note files in that directory, including creating, renaming, deleting, refactoring, and targeted block updates.
  • Watch the notes directory for file changes so editor edits are reflected immediately.
  • Communicate over stdio with MCP clients; running via npx requires network access to fetch the @iwe-org/mcp package.

Risks and side effects

  • The agent holds write access to the notes directory; MCP writes must declare expect guards and validate before writing, but permitted changes still land on disk.
  • Pointing the MCP server at the wrong working directory lets the agent read and write markdown files in an unintended folder.
  • Using npx fetches an npm package from the network on first run, adding a dependency on the network and the upstream package.
  • Validation covers schemas, frontmatter, and graph-hygiene warnings, but dangling links, orphan pages, and near-duplicates are surfaced as warnings and still need human judgement.
  • The liwe crate in the repository is published but not yet API-stable, so projects building on it should pin versions.

Setup

Before you start

Runtime:Node.js · Prebuilt binary

  1. Install the CLI and the LSP/MCP server: Homebrew with brew install iwe-org/iwe/iwe; npm with npm install -g @iwe-org/iwe; Cargo with cargo install iwe iwes iwec; or conda-forge with conda install -c conda-forge iwe.
  2. Initialize your workspace: cd into your notes directory and run iwe init.
  3. Connect your AI agent: iwec serves the directory it runs in, so set the working directory to your notes, e.g. {"mcpServers":{"iwe":{"command":"iwec","cwd":"~/notes"}}} in the client config.
  4. No local install needed — have npx fetch the server on demand: set command to npx, args to ["-y", "@iwe-org/mcp"], and keep cwd pointing at your notes.
  5. Optional: give Claude Code memory by adding the plugin marketplace with /plugin marketplace add iwe-org/skills, installing /plugin install iwe@iwe-org, then running /iwe:init in the repository you want remembered.
.mcp.json
{
  "mcpServers": {
    "iwe": {
      "command": "iwec",
      "cwd": "~/notes"
    }
  }
}

Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "iwe": {
      "command": "iwec",
      "cwd": "~/notes"
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add iwe -- iwec

Run it in a terminal; replace any <…> placeholders with your own values first.

Check that it works

Run iwec (with cwd set to your notes directory) or npx -y @iwe-org/mcp in your client config; after connecting, the tool list should show find, retrieve, tree, update, and schema. You can also run iwe init first and ask the agent "what topics are in my notes?" to confirm it reads your markdown files.

Troubleshooting

  1. The agent sees the wrong set of notes: check that cwd in the MCP config points at the real notes directory, since iwec serves only the directory it runs in.
  2. Editor changes are not picked up immediately: confirm the MCP server process is running; it watches files for changes.
  3. An MCP write is rejected: read the named violation in the response — usually a missing mandatory expect guard or a document-schema violation (required fields, enums, ISO dates, required sections).
  4. Command-line checks disagree with MCP behaviour: run iwe schema validate on the CLI to reproduce the same checks on demand.
  5. npx fails to start: verify network access, or switch command to a locally installed iwec that is on PATH.
  6. Links or structure look wrong: watch for dangling-link and orphan-page warnings from mutations, and use iwe stats similarity to flag near-duplicates.
  7. Nothing is queryable on first use: run iwe init in the notes directory to initialize the workspace.

Things to try

Once connected, you can ask your AI assistant things like:

  • Fuzzy-search my notes for anything related to auth
  • Retrieve the authentication note and expand two levels of included parent context
  • Show the note hierarchy tree starting from the oauth node
  • Update this note's frontmatter to set status: accepted

Tools 5

find read-only
Search notes with fuzzy and full-text ranking, plus filters over frontmatter and graph edges.
retrieve read-only
Get a document together with its linked context in one call.
tree read-only
Show the note hierarchy from any starting point.
update writes
Guarded edits: frontmatter changes and targeted block operations.
schema read-only
Infer the store's schemas, or validate documents against them.

Use cases

Use a local markdown notes directory as long-term memory for a coding agent or a conversational agent.
Run database-style queries on notes without moving them into a database — "all drafts under this subtree", "every accepted decision in Q1".
Let agents perform the same search, retrieve, create, and refactor operations through either the CLI or the MCP server.
Get IDE-like features in the editor: link autocomplete, go to definition, backlinks, rename with automatic link updates, extract, and inline.
Scaffold, validate, and query conformant Open Knowledge Format (OKF) bundles of markdown with YAML frontmatter.

Supported clients

Claude Code
Claude Desktop
Cursor
Windsurf

Listed from the project's documentation, not tested by this site.

Overview

IWE is a memory system for people and their AI agents: it turns a directory of markdown files into a knowledge graph. Notes stay as plain .md files in a local directory — no cloud, no database, no lock-in, versionable with git. The same graph has two interfaces: an LSP server for editors (VS Code, Neovim, Zed, Helix, and any LSP-capable editor) and a CLI plus an MCP server (iwec) for AI agents. The MCP server watches the files it serves, so edits made in your editor are reflected immediately. IWE has no built-in AI; it works alongside Claude, Codex, Gemini, and any tool that speaks the Model Context Protocol. Retrieval is by structure rather than similarity guessing: search finds an entry point, and retrieve/tree supply parent context, children, and cross-references in a single call. Agent writes are checked, not trusted — over MCP every mutation must declare expect guards stating 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. Frontmatter and document structure are validated against per-type document schemas, and mutations surface warnings for dangling links and orphan pages. Written in Rust under the Apache-2.0 license.

Similar servers

Source revision 1bbc0dc9251d Data synced 2026-10-19 Read the FMRS scoring method