IWE Knowledge Graph & Agent Memory
Turn local Markdown into a queryable knowledge graph and inspectable memory for AI agents.
- Source repo
- iwe-org/iwe
- Stars
- ★ 1.8k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · Claude.ai
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A researcher with a large Markdown corpus who wants queries over topic hierarchy, frontmatter, and cross-references without surrendering ownership of local files.
- Not a fit if
- Teams wanting built-in AI: IWE ships none and needs a separate Claude, Codex, or Gemini client.
- Collections organized mainly by folders: the graph depends on IWE's inclusion-link convention.
- Developers embedding the library: the published liwe crate is not API-stable.
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
IWE is a local-first, Rust-based knowledge system that turns a directory of Markdown files into a graph of inclusion links, cross-references, and multi-parent relationships. It provides the iwe CLI, the iwec MCP server, and an LSP implementation so people and AI agents can operate on the same files. Agents can search, retrieve, create, and refactor notes with parent, child, and linked context, while the resulting knowledge remains ordinary Markdown that can be reviewed and versioned with Git. Mutations can declare their expected scope and be checked against document schemas, dangling links, and orphan pages. IWE contains no built-in AI and needs no cloud database; its deployment boundary is the selected local notes directory, although editor, MCP-client, and automatic session-memory support vary by runtime.
IWE reads local .md files, treating a link on its own line as an inclusion edge and ordinary inline links as cross-references. iwe find performs fuzzy and full-text ranked searches with filters over frontmatter and graph edges; iwe retrieve returns a document with linked context; and iwe tree displays the hierarchy from a selected node. iwe update applies guarded frontmatter and targeted block edits, while iwe schema infers or validates document schemas; the CLI also includes commands such as new, extract, inline, rename, delete, normalize, and export. The iwec server exposes search, retrieval, creation, and refactoring through MCP and watches the underlying files for changes. Its LSP supplies navigation, references, hover previews, link completion, rename, formatting, and templates to editors including VS Code, Neovim, Zed, and Helix. A separate IWE plugin for Claude Code can capture established session knowledge into an IWE workspace inside the repository, producing reviewable Markdown diffs.
- A researcher with a large Markdown corpus who wants queries over topic hierarchy, frontmatter, and cross-references without surrendering ownership of local files.
- A VS Code, Neovim, Zed, or Helix user who wants IDE-style link completion, backlinks, renaming, and structural refactoring for a personal knowledge base.
- A software team that wants coding-agent memory stored as reviewable, version-controlled Markdown inside each repository.
- A Claude Desktop, Cursor, or Windsurf user who wants an MCP connection for searching, reading, creating, and refactoring local notes.
- A team maintaining OKF bundles that needs
iwe init --okf, mechanical validation withiwe schema validate, and queries over YAML frontmatter. - A personal knowledge-management user with thousands of notes who needs graph navigation and structured retrieval without migrating the collection into a proprietary database.
How do you install or deploy this agent?
Choose one supported installation route: on macOS or Linux run brew install iwe-org/iwe/iwe; on macOS, Linux, or Windows run npm install -g @iwe-org/iwe; with Rust run cargo install iwe iwes iwec; or use the community-maintained conda-forge package with conda install -c conda-forge iwe. Enter the notes directory and run iwe init. Automatic Claude Code memory requires IWE CLI 0.20.0 or newer on PATH; then run /plugin marketplace add iwe-org/skills, /plugin install iwe@iwe-org, and /iwe:init in the repository to be remembered. Codex, Cursor, and OpenCode users can install the /init, /distill, /reflect, and /graph project skills with npx skills add iwe-org/skills; those runtimes invoke the skills manually.
How do you use this agent?
Initialize a workspace with cd ~/notes followed by iwe init. A basic retrieval flow is iwe find --fuzzy auth, then iwe retrieve --key authentication --expand-includes 2 for the note and surrounding hierarchy, or iwe tree --key oauth to inspect its subtree. For an MCP client, configure {"mcpServers":{"iwe":{"command":"iwec","cwd":"~/notes"}}}; alternatively use {"mcpServers":{"iwe":{"command":"npx","args":["-y","@iwe-org/mcp"],"cwd":"~/notes"}}} to fetch the server on demand. The server operates on its working directory, so cwd must point to the intended notes collection. After installing the Claude Code plugin, run /iwe:init in the repository that should retain memory; its background capture invokes only iwe, so permission can be limited to Bash(iwe:*). Hooks exit silently when MEMORY.md is absent or the CLI is not installed.
What are this agent's strengths and limitations?
- Notes remain plain local Markdown rather than records in a cloud or proprietary store, making them directly editable, reviewable, and suitable for Git versioning.
- The CLI, MCP server, and LSP operate on one graph, avoiding separate knowledge stores for humans and agents.
- Retrieval can expand a search hit into parent context, children, and cross-references instead of returning an isolated matching passage.
- Writes can use
expectguards to declare their blast radius; MCP makes those guards mandatory and rejects schema-invalid changes. - Multi-parent relationships let one note belong to several topics without duplicating its contents.
- OKF scaffolding, validation, and frontmatter queries are included.
- IWE has no built-in AI, so users must separately provide Claude, Codex, Gemini, or another compatible client.
- Automatic session capture is specific to the Claude Code plugin; Codex, Cursor, and OpenCode receive manually invoked skills instead.
- The Claude Code plugin requires IWE CLI 0.20.0 or newer and shell permission for
iwecommands. - An MCP client must set the server working directory correctly or it will serve the wrong notes collection.
- The published
liweRust library is not API-stable, creating upgrade risk for applications that embed it directly. - The graph depends on IWE's inclusion-link convention, so an existing collection organized mainly by folders may require link restructuring.
How does this agent compare with similar options?
Unlike moving notes into an actual database, IWE keeps them as local Markdown while adding database-style queries through links and YAML frontmatter. Unlike a conventional folder tree, one note can sit under multiple topics. Compared with retrieval that guesses context from vector similarity alone, IWE emphasizes explicit parent-child and cross-reference structure. It can also complement ripgrep, full-text, or vector search: an external tool finds the note, and IWE supplies its surrounding graph context.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| IWE Knowledge Graph & Agent Memory This agent | 73 · Some gaps | CLIFree | ★ 1.8k | today | Rust | Codex · Claude Code · Claude.ai |
| Rowboat | 43 · Major gaps | Desktop appFree + model costs | ★ 18k | 3d ago | TypeScript | Codex · Claude Code |
| SwarmVault | 67 · Some gaps | CLIFree + model costs | ★ 723 | 3mo ago | TypeScript | Codex · Claude Code |
| Memmy — Personal AI Agent & Local Memory Hub | 42 · Major gaps | Desktop appFreemium | ★ 2.1k | today | TypeScript | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence clearly describes local Markdown storage, an MCP server bounded by its working directory, an optional Bash(iwe:*) permission allowlist, and mandatory MCP mutation guards validated before any write. Deductions apply because no per-change user-confirmation mechanism, dedicated protection for sensitive notes or credentials, dependency audit, or vulnerability-response policy is shown. Git provides a recoverability path and failed validation aborts a write, but no built-in rollback command is documented. The author, organization, license, and community channels provide attribution, while the publisher's enterprise identity remains unknown rather than adverse.
The README presents a largely coherent model across the CLI, LSP, MCP server, plugin, and local files, and the Cargo workspace contains corresponding components. Multiple installation routes and an explicit Rust version support ordinary availability, although operation still depends on registries, npx, Homebrew, editors, and MCP clients. The materials state that guard and schema failures identify offending blocks or violations, but they do not provide a comprehensive error catalog, recovery guidance, or troubleshooting section, so full marks are not justified.
The intended users and scenarios are well differentiated across note queries, editor workflows, agent memory, OKF, and scripting. Capability boundaries are unusually explicit: IWE contains no AI, the CLI and MCP server are the current integration surfaces, automatic capture is specific to Claude Code, and the liwe API is not stable. Working-directory scope, MEMORY.md, initialization, and manual invocation constrain triggering, but MCP tool-level trigger rules and precise selection conditions for every mutation are not supplied. Coverage across macOS, Linux, Windows, several editors, and multiple installers is strong.
The README has clear sections for capabilities, operation, AI integration, editors, quick start, documentation, contribution, and licensing, with substantial installation and configuration examples. Naming is mostly consistent, but the distinct roles of iwe, iwes, and iwec are not all explained in the supplied text, and liwe is explicitly API-unstable. Examples are plentiful but there is no actual FAQ; some limitations are disclosed, though no consolidated limitations inventory is present. Apache-2.0 is consistent across README, Cargo, and the generated Homebrew formula. Version metadata and automated release machinery are visible, but no changelog content is supplied. Maintenance channels and an author are identified, while organizational responsibility and publisher identity are not independently verified.
Outputs remain readable, reviewable, Git-manageable Markdown, while structured retrieval, contextual expansion, link-aware refactoring, and schema validation offer directly usable results. Parent and child graph context, cross-references, and guarded structural edits provide clear marginal value beyond plain text search. The local, database-free design and several installation choices reduce lock-in, but initialization, editor or MCP configuration, schema management, and external runtime dependencies impose costs. The performance figure is only asserted because the referenced benchmark body is not included, preventing a full cost-benefit score.
Many claims map to concrete commands, configuration samples, workspace components, or documentation references, and Cargo plus release workflows corroborate versioning, licensing, component names, and distribution. Deductions apply because implementation files, a lockfile, tests, benchmark contents, and linked documentation bodies are absent, leaving mutation safety, performance, and the complete feature surface only partially traceable. The prose distinguishes local-storage facts, current stable integration surfaces, community-maintained distribution, and roadmap items, but some promotional claims about speed and adoption lack independent support in the supplied files.
- Before allowing agent writes to important notes, use version control, review diffs, and tightly scope the MCP working directory; the materials show neither per-write confirmation nor a dedicated rollback facility.
- Local storage is not equivalent to sensitive-data protection; the supplied files do not document encryption, access control, log redaction, or credential-handling policies.
- Installation and release depend on external registries, GitHub Actions, and third-party actions; no lockfile, dependency audit, or vulnerability-handling evidence is included.
- The liwe library API is explicitly unstable, so embedded integrations should pin versions and expect compatibility changes.
- Performance and some safety behavior are README claims only; this static assessment did not execute or independently verify them.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
iwe-v0.28.0 v0.28.0
Release notes excerpt
Sorting is now locale-aware: titles and other text fields order the way a person would expect, so note 2 comes before Note 10, accented letters sit next to their plain forms, and case no longer splits a list. The language follows workspace.locale in .iwe/config.toml and falls back to the system locale. When you need the old byte order or a specific language, --sort field:asc:binary or a locale tag such as sv-SE picks the collation per sort key, in both the CLI and query documents. iwe Added …View on GitHub ↗ -
iwe-v0.27.0 v0.27.0
Release notes excerpt
Wiki links now stay accurate as your notes change: backlinks, references and inlay hints in the editor follow [[Name]] links to notes you create, move or delete without having to touch the linking note. Renaming a note is also much less noisy — [[Name]] links are kept as written when they still resolve, otherwise the shortest working name is used, and links that would accidentally start pointing at the renamed note are fixed up. iwe Changed …View on GitHub ↗ -
iwe-v0.26.1 v0.26.1
Release notes excerpt
Queries no longer crash or hang when a document links to a missing page or to a non-markdown file such as an image or a YAML file. find, count and the MCP iwe_query tool now only return real documents for these links. Thanks @Bear-03 for reporting this. iwe Fixed - find and count no longer crash or list non-documents when a document links to a missing document or to a non-markdown file; --referenced-by and --included-by only return existing documents iwec Fixed …View on GitHub ↗
FAQ
Does IWE require a paid model or cloud service?
Can an agent modify the entire knowledge base without limits?
expect guards declaring the permitted number of affected documents and blocks. A mismatch aborts the complete update, and schema-invalid writes are rejected; mutations can also surface dangling-link and orphan-page warnings.Can I use IWE without an MCP client?
iwe CLI directly, while editor users can access navigation, completion, and refactoring through LSP. MCP is one integration path rather than a requirement for every workflow.Will Claude Code memory activate in every repository?
/iwe:init in the repository that should be remembered. Without MEMORY.md, or when the CLI is unavailable, the hooks exit silently.Is the Rust library a stable embedding interface?
liwe crate is published but is not yet API-stable. The documented practical integration surfaces are currently the CLI and MCP server; applications using the library should pin its version.