IWE - Memory system for you and your AI agents

Turn your thinking into queryable context

IWE turns a directory of markdown files into a knowledge graph — a connected structure you browse from your editor and your AI queries from the command line. Same files, same links, two interfaces. No cloud, no database, no lock-in. Version everything with git.

IWE is for people who want database-style queries on their notes — "all drafts under this subtree", "every accepted decision in Q1" — without moving them into an actual database. Write in Markdown, structure with links, give AI agents the tools to navigate your knowledge. IWE itself has no built-in AI — it works alongside Claude, Codex, Gemini, and any tool that speaks the Model Context Protocol.

What You Get

• Plain markdown, full ownership. Your notes are .md files in a local directory. Read them, edit them, git push them. Nothing proprietary.
• A graph, not a folder tree. Link notes together and the same note can belong to multiple topics without copying the file. (How linking works)
• IDE features for your editor. Real LSP integration with VS Code, Neovim, Zed, and Helix — search, refactor, rename, autocomplete.
• Structured access for AI agents. CLI tools and an MCP server give agents parent context and structural navigation over the same notes you edit by hand — retrieval by structure, not similarity guessing.
• Memory for your coding agent. The IWE plugin for Claude Code reads a session with you and writes what you pick into the repository's own IWE workspace — markdown you review as an ordinary diff, not a store you can't inspect.
• Speaks OKF. An Open Knowledge Format bundle is markdown with YAML frontmatter — the format IWE already manages. iwe init --okf scaffolds a conformant bundle, iwe schema validate checks conformance mechanically, and iwe find --filter '{type: …}' queries OKF frontmatter directly.
• Fast. Built in Rust, processes 20,000 files in under a second.

Install

The hook is an iwe subcommand, so the plugin ships no runtime scripts — the only requirement is the IWE CLI (0.21.0 or newer) on your PATH.

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

Then, in the repository you want remembered:

/iwe:init

Let the memory skills run the CLI — they run iwe and nothing else:

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

Without a MEMORY.md — or without the CLI installed — the session-start hook exits silently, so the plugin stays inert in every other repository. iwe init also offers to write the policy for you when it finds a .claude/ directory.

The plugin carries the graph skill too, giving the agent bounded, graph-aware routes for finding, retrieving, creating, and refactoring notes. All four skills reach Codex, Cursor, and OpenCode through the skills CLI, where they install as ordinary project skills (/init, /distill, /reflect, /graph):

npx skills add iwe-org/skills

Nothing reaches memory unselected: /iwe:distill proposes, you select, and only then is anything written.

More information: plugin repository

How It Works

IWE treats your notes as a connected structure. You organize them with two types of links:

• Nesting — a link on its own line means "this topic includes that subtopic." Your notes form a tree you can browse and refactor. IWE calls these inclusion links.
• Cross-references — regular inline links connect notes across topics, creating a web of relationships.
• Multiple parents — the same note can live under several places at once. A "Meditation" note can belong to both "Health" and "Productivity" without duplicating the file.
• Context from parents — when you retrieve a note, IWE can include context from the notes above it in the hierarchy.

This structure makes retrieval powerful — whether you're browsing in your editor or an agent is querying via CLI, ask for a topic and get its full context in a single call.

Working with AI

IWE gives AI agents structured access to your notes through two interfaces: a CLI for scripting and shell-based workflows, and an MCP server for native connection with AI tools. Both expose the same operations — search, retrieve, create, refactor — so you can choose whichever fits your setup.

IWE pairs search with structure: built-in fuzzy and full-text search finds the entry point, and the graph turns a hit into usable context — parent context, children, cross-references, link-safe refactoring. It also composes cleanly with any external tooling you already use (ripgrep, full-text, vector): whatever finds the note, IWE supplies the context around it.

What the Engine Checks

Agent writes are checked, not trusted:

• Declared scope. 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 won't declare its blast radius is refused.
• Schemas. Frontmatter and document structure are validated against per-type document schemas — required fields, enums, ISO dates, 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.
• Graph hygiene. Mutations surface warnings for what they disturbed — dangling links, orphan pages — and iwe stats similarity flags near-duplicates.

Integration Server (MCP)

IWE includes a server (iwec) that lets AI tools like Claude Desktop, Cursor, and Windsurf work directly with your notes using the Model Context Protocol. The server watches your files for changes, so edits you make in your editor are reflected immediately.

Command-Line Tools

The CLI lets you (and AI agents) work with your notes from the terminal or in scripts.

Example: preparing context for an AI conversation

iwe find --fuzzy auth

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

iwe tree --key oauth

Core commands:

The full set — new, extract, inline, rename, delete, squash, stats, normalize, export and more — is in the CLI Reference.

More information: Working with AI · CLI Reference · MCP Server

Editor Integration

IWE gives your editor IDE-like features for markdown notes. It works with VS Code, Neovim, Zed, Helix, and any editor that supports the Language Server Protocol (LSP).

• Search — find notes by title or content
• Navigate — go to definition, find references (backlinks)
• Preview — hover over links to see content
• Auto-complete — link suggestions as you type
• Inlay hints — show parent references and link counts
• Extract — pull sections into new notes
• Inline — embed note content back into parent
• Rename — rename files with automatic link updates
• Format — normalize documents, update link titles
• Transform — pipe text through external commands
• Templates — create notes from templates (daily notes, etc.)
• Outline conversion — switch between headers and lists

More information: Editor Features

Quick Start

1. Install the CLI and LSP server:

   Using Homebrew (macOS/Linux):

   bash

   Copy

   brew install iwe-org/iwe/iwe
   

   Or using npm (macOS/Linux/Windows):

   Terminal

   Copy

   npm install -g @iwe-org/iwe
   

   Or using Cargo:

   bash

   Copy

   cargo install iwe iwes iwec
   

   Or from conda-forge (community-maintained — thanks, salim-b):

   bash

   Copy

   conda install -c conda-forge iwe
   

2. Initialize your workspace:

   bash

   Copy

   cd ~/notes
   iwe init
   

3. Pick your path:

   Set up your editor — VS Code · Neovim · Helix · Zed

   Connect your AI agent — point it at the MCP server. iwec serves the directory it runs in, so set the working directory to your notes:

   config.json

   Copy

   {
     "mcpServers": {
       "iwe": {
         "command": "iwec",
         "cwd": "~/notes"
       }
     }
   }
   

   No install needed — npx fetches the server on demand:

   config.json

   Copy

   {
     "mcpServers": {
       "iwe": {
         "command": "npx",
         "args": ["-y", "@iwe-org/mcp"],
         "cwd": "~/notes"
       }
     }
   }
   

   Give Claude Code memory — install the plugin, then run /iwe:init in the repository you want remembered (details):

   Code

   Copy

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

   Or hand the setup to the agent — paste this into Claude Code or any agent with shell access:

   text

   Copy

   Set up IWE for my notes: install it (brew install iwe-org/iwe/iwe,
   npm install -g @iwe-org/iwe, or cargo install iwe iwes iwec), run `iwe init`
   in my notes directory, then add the `iwec` MCP server with its working
   directory set to that folder.
   Docs: https://iwe.md/docs/agentic/
   

Documentation

• Getting Started — Installation and setup
• Usage Guide — Editor features and workflows
• CLI Reference — Command-line tools
• Working with AI — AI agent integration
• MCP Server — Native AI tool integration via Model Context Protocol
• OKF — Open Knowledge Format: scaffold, validate, and query conformant bundles
• Configuration — Settings and customization
• Examples — Example projects and case studies

Get Involved

IWE is open source and community-driven. Join the discussions, report issues, or contribute to the documentation.

Community: Twitter/X · Reddit · Discussions

Editor plugins: VS Code · Neovim · Zed

Workspace templates: marketing-workspace — campaign memory for a marketing agent · dev-workspace — project memory for a coding agent. Both ship as conformant OKF v0.2 bundles, validated in CI on every commit.

Agentic skills: iwe-org/skills — the Claude Code memory plugin and the skills for knowledge graph management, usable from any agent runtime. Contributors welcome.

Building on IWE: projects already embed IWE — as an agent-memory backend, as the graph layer of an LLM wiki engine, in research tooling. The practical integration surfaces today are the CLI and the MCP server; the liwe library is published but not yet API-stable, so pin your version if you build against it. A declared, stable integration surface is on the roadmap — if you're building on IWE, tell us what you depend on, so we know what not to break.

License

Apache License 2.0