{
  "markdown": "# IWE - Memory system for you and your AI agents\n\n> Turn your thinking into queryable context\n\n[![Crates.io](https://img.shields.io/crates/v/iwe.svg)](https://crates.io/crates/iwe)\n[![Downloads](https://img.shields.io/crates/d/iwe.svg)](https://crates.io/crates/iwe)\n[![License](https://img.shields.io/crates/l/iwe.svg)](https://github.com/iwe-org/iwe/blob/master/LICENSE-APACHE)\n[![Build](https://github.com/iwe-org/iwe/workflows/Rust/badge.svg)](https://github.com/iwe-org/iwe/actions)\n[![Documentation](https://img.shields.io/badge/docs-iwe.md-blue)](https://iwe.md)\n[![Discussions](https://img.shields.io/github/discussions/iwe-org/iwe)](https://github.com/iwe-org/iwe/discussions)\n[![Twitter](https://img.shields.io/badge/Twitter-@iwe__md-blue?logo=x)](https://x.com/iwe_md)\n[![Reddit](https://img.shields.io/badge/Reddit-r%2Fiwe-orange?logo=reddit)](https://www.reddit.com/r/iwe/)\n\n[![Knowledge Graph](docs/docs-detailed.svg)](https://iwe.md)\n\nIWE 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.\n\nIWE 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](https://modelcontextprotocol.io).\n\n## What You Get\n\n- **Plain markdown, full ownership.** Your notes are `.md` files in a local directory. Read them, edit them, `git push` them. Nothing proprietary.\n- **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](https://iwe.md/docs/concepts/inclusion-links/))\n- **IDE features for your editor.** Real LSP integration with [VS Code](https://iwe.md/docs/editors/vscode/), [Neovim](https://iwe.md/docs/editors/neovim/), [Zed](https://iwe.md/docs/editors/zed/), and [Helix](https://iwe.md/docs/editors/helix/) — search, refactor, rename, autocomplete.\n- **Structured access for AI agents.** [CLI tools](https://iwe.md/docs/cli/) and an [MCP server](https://iwe.md/docs/agentic/mcp/) give agents parent context and structural navigation over the same notes you edit by hand — retrieval by structure, not similarity guessing.\n- **Memory for your coding agent.** The [IWE plugin for Claude Code](https://github.com/iwe-org/skills) 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.\n- **Speaks OKF.** An [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 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.\n- **Fast.** Built in Rust, [processes 20,000 files in under a second](docs/benchmark.md).\n\n### Install\n\nThe 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`.\n\n```\n/plugin marketplace add iwe-org/skills\n/plugin install iwe@iwe-org\n```\n\nThen, in the repository you want remembered:\n\n```\n/iwe:init\n```\n\nLet the memory skills run the CLI — they run `iwe` and nothing else:\n\n```json\n{ \"permissions\": { \"allow\": [\"Bash(iwe:*)\"] } }\n```\n\nWithout 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.\n\nThe 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`):\n\n```bash\nnpx skills add iwe-org/skills\n```\n\nNothing reaches memory unselected: `/iwe:distill` proposes, you select, and only then is anything written.\n\nMore information: [plugin repository](https://github.com/iwe-org/skills)\n\n## How It Works\n\nIWE treats your notes as a connected structure. You organize them with two types of links:\n\n- **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](https://iwe.md/docs/concepts/inclusion-links/).\n- **Cross-references** — regular inline links connect notes across topics, creating a web of relationships.\n- **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.\n- **Context from parents** — when you retrieve a note, IWE can include context from the notes above it in the hierarchy.\n\nThis 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.\n\n## Working with AI\n\nIWE 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.\n\nIWE 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.\n\n### What the Engine Checks\n\nAgent writes are checked, not trusted:\n\n- **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.\n- **Schemas.** Frontmatter and document structure are validated against per-type [document schemas](https://iwe.md/docs/concepts/document-schema/) — 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.\n- **Graph hygiene.** Mutations surface warnings for what they disturbed — dangling links, orphan pages — and `iwe stats similarity` flags near-duplicates.\n\n### Integration Server (MCP)\n\nIWE includes a server (`iwec`) that lets AI tools like Claude Desktop, Cursor, and Windsurf work directly with your notes using the [Model Context Protocol](https://modelcontextprotocol.io). The server watches your files for changes, so edits you make in your editor are reflected immediately.\n\n### Command-Line Tools\n\nThe CLI lets you (and AI agents) work with your notes from the terminal or in scripts.\n\n**Example: preparing context for an AI conversation**\n```bash\niwe find --fuzzy auth\n\niwe retrieve --key authentication --expand-includes 2\n\niwe tree --key oauth\n```\n\n**Core commands:**\n\n| Command | What it does |\n|---|---|\n| `find` | Search with fuzzy and full-text ranking, plus filters over frontmatter and graph edges |\n| `retrieve` | Get a document with its linked context in one call |\n| `tree` | Show the hierarchy from any starting point |\n| `update` | Guarded edits: frontmatter changes and targeted block operations |\n| `schema` | Infer the store's schemas, or validate documents against them |\n\nThe full set — `new`, `extract`, `inline`, `rename`, `delete`, `squash`, `stats`, `normalize`, `export` and more — is in the [CLI Reference](https://iwe.md/docs/cli/).\n\nMore information: [Working with AI](https://iwe.md/docs/agentic/) · [CLI Reference](https://iwe.md/docs/cli/) · [MCP Server](https://iwe.md/docs/agentic/mcp/)\n\n## Editor Integration\n\nIWE gives your editor IDE-like features for markdown notes. It works with [VS Code](https://iwe.md/docs/editors/vscode/), [Neovim](https://iwe.md/docs/editors/neovim/), [Zed](https://iwe.md/docs/editors/zed/), [Helix](https://iwe.md/docs/editors/helix/), and any editor that supports the Language Server Protocol (LSP).\n\n- **Search** — find notes by title or content\n- **Navigate** — go to definition, find references (backlinks)\n- **Preview** — hover over links to see content\n- **Auto-complete** — link suggestions as you type\n- **Inlay hints** — show parent references and link counts\n- **Extract** — pull sections into new notes\n- **Inline** — embed note content back into parent\n- **Rename** — rename files with automatic link updates\n- **Format** — normalize documents, update link titles\n- **Transform** — pipe text through external commands\n- **Templates** — create notes from templates (daily notes, etc.)\n- **Outline conversion** — switch between headers and lists\n\nMore information: [Editor Features](https://iwe.md/docs/getting-started/usage/)\n\n## Quick Start\n\n1. **Install** the CLI and LSP server:\n\n   Using Homebrew (macOS/Linux):\n   ```bash\n   brew install iwe-org/iwe/iwe\n   ```\n\n   Or using npm (macOS/Linux/Windows):\n   ```bash\n   npm install -g @iwe-org/iwe\n   ```\n\n   Or using Cargo:\n   ```bash\n   cargo install iwe iwes iwec\n   ```\n\n   Or from [conda-forge](https://anaconda.org/conda-forge/iwe) (community-maintained — thanks, [salim-b](https://github.com/salim-b)):\n   ```bash\n   conda install -c conda-forge iwe\n   ```\n\n2. **Initialize** your workspace:\n   ```bash\n   cd ~/notes\n   iwe init\n   ```\n\n3. **Pick your path:**\n\n   **Set up your editor** — [VS Code](https://iwe.md/docs/editors/vscode/) · [Neovim](https://iwe.md/docs/editors/neovim/) · [Helix](https://iwe.md/docs/editors/helix/) · [Zed](https://iwe.md/docs/editors/zed/)\n\n   **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:\n   ```json\n   {\n     \"mcpServers\": {\n       \"iwe\": {\n         \"command\": \"iwec\",\n         \"cwd\": \"~/notes\"\n       }\n     }\n   }\n   ```\n\n   No install needed — `npx` fetches the server on demand:\n   ```json\n   {\n     \"mcpServers\": {\n       \"iwe\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@iwe-org/mcp\"],\n         \"cwd\": \"~/notes\"\n       }\n     }\n   }\n   ```\n\n   **Give Claude Code memory** — install the plugin, then run `/iwe:init` in the repository you want remembered ([details](#memory-for-claude-code)):\n   ```\n   /plugin marketplace add iwe-org/skills\n   /plugin install iwe@iwe-org\n   ```\n\n   Or hand the setup to the agent — paste this into Claude Code or any agent with shell access:\n\n   ```text\n   Set up IWE for my notes: install it (brew install iwe-org/iwe/iwe,\n   npm install -g @iwe-org/iwe, or cargo install iwe iwes iwec), run `iwe init`\n   in my notes directory, then add the `iwec` MCP server with its working\n   directory set to that folder.\n   Docs: https://iwe.md/docs/agentic/\n   ```\n\n## Documentation\n\n- [Getting Started](https://iwe.md/docs/getting-started/installation/) — Installation and setup\n- [Usage Guide](https://iwe.md/docs/getting-started/usage/) — Editor features and workflows\n- [CLI Reference](https://iwe.md/docs/cli/) — Command-line tools\n- [Working with AI](https://iwe.md/docs/agentic/) — AI agent integration\n- [MCP Server](https://iwe.md/docs/agentic/mcp/) — Native AI tool integration via Model Context Protocol\n- [OKF](https://iwe.md/docs/agentic/okf/) — Open Knowledge Format: scaffold, validate, and query conformant bundles\n- [Configuration](https://iwe.md/docs/configuration/) — Settings and customization\n- [Examples](https://iwe.md/docs/examples/) — Example projects and case studies\n\n## Get Involved\n\nIWE is open source and community-driven. Join the [discussions](https://github.com/iwe-org/iwe/discussions), report [issues](https://github.com/iwe-org/iwe/issues), or contribute to the [documentation](docs/).\n\n**Community:** [Twitter/X](https://x.com/iwe_md) · [Reddit](https://www.reddit.com/r/iwe/) · [Discussions](https://github.com/iwe-org/iwe/discussions)\n\n**Editor plugins:** [VS Code](https://github.com/iwe-org/vscode-iwe) · [Neovim](https://github.com/iwe-org/iwe.nvim) · [Zed](https://github.com/iwe-org/zed-iwe)\n\n**Workspace templates:** [marketing-workspace](https://github.com/iwe-org/marketing-workspace) — campaign memory for a marketing agent · [dev-workspace](https://github.com/iwe-org/dev-workspace) — project memory for a coding agent. Both ship as conformant [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.2 bundles, validated in CI on every commit.\n\n**Agentic skills:** [iwe-org/skills](https://github.com/iwe-org/skills) — the Claude Code memory plugin and the skills for knowledge graph management, usable from any agent runtime. Contributors welcome.\n\n**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`](https://crates.io/crates/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](https://github.com/iwe-org/iwe/discussions/362) what you depend on, so we know what not to break.\n\n## License\n\n[Apache License 2.0](LICENSE-APACHE)\n",
  "bytes": 13860,
  "sha": "c0b78421f841562288d1d862f261cd0ee5937e364b8d6aab8e7b8d4ef4093bd7",
  "repo_slug": "iwe-org/iwe",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_iwe_org_iwe_abe4e8de/readme"
}