IWE: a Markdown knowledge base you and your AI agent work on together

Memory serverOfficial IWE project

Created by IWE

Published in iwe-org/iwe. Publisher page

1,821 GitHub starsUpdated 2026-11-11

What it is

Markdown knowledge graph — LSP for your editor, CLI + MCP memory for your AI agents

— the description by IWE

AutoGineer overview, from the brain’s own files

IWE provides a shared workspace for humans and AI agents to collaborate on project documentation, specs, and decision logs. By treating a folder of Markdown files as a structured knowledge graph, it allows agents to read, write, and organize information that persists across sessions. It functions as a memory server via the Model Context Protocol (MCP), enabling compatibility with various AI agents while remaining accessible to users through a native Mac app, CLI, or standard text editors like Neovim and VS Code.

How it works

Memory model: Not stated

AutoGineer overview, from the brain’s own files

IWE organizes notes as a collection of Markdown files within a project folder. It uses a CLI and an MCP server to expose these files to AI agents, allowing them to perform operations like searching, creating, and updating notes. The system supports features such as backlinks, link autocomplete, and graph visualization, ensuring that both the user and the AI agent interact with the same underlying document structure.

Folders
Folder	Role	Files
.github	agent-config	4
docs	docs	70
.githooks	folder	1
crates	folder	381
npm	folder	15

Requirements

Runtimes: Rust

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

This brain runs code automatically: 1 script. Review .githooks/pre-commit before opening the folder in Claude Code. No step below turns a hook on for you.
- .githooks/pre-commit: runs on git pre-commit
Not scanned by AutoGineerAutoGineer could not scan everything it runs. https://www.npmjs.com/package/@iwe-org/mcp
Created by IWE. Published in iwe-org/iwe. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

Connect an AI agent to your project notes using the MCP server.
Use the CLI to search, create, or reorganize notes from the terminal.
Write and browse notes in the native Mac app while an agent works alongside you.
Integrate note navigation and autocomplete into your preferred text editor.
Maintain a persistent record of project decisions and lessons learned that both you and your agent can access.

“Explore my IWE notes and summarize what's here.”: The agent reads the Markdown files in the designated folder and provides a summary of the project context, decisions, or documentation found.
“Save the decision we just made about the database schema.”: The agent creates or updates a Markdown note in the IWE folder containing the details of the decision for future reference.

Documentation by IWE

IWE: a Markdown knowledge base you and your AI agent work on together

English · 简体中文 · 한국어

Your notes are your agent’s memory. IWE is where you work on them together.

iwe.md · Download for Mac · Docs · Reddit

Image: Crates.io Image: License Image: Documentation

Too many AI conversations start from zero. You explain your project, your decisions, your reasoning — then find yourself explaining it all again next session. Your own notes live somewhere else, out of the agent's reach.

Or worse, the agent “remembers” something in its own internal memory, but you can't easily see what it saved or correct what it got wrong. And that memory doesn't travel with you to the other agents you work with.

IWE gives you and your AI agents one shared place to work, right inside your project: a folder of connected Markdown documents — specs, plans, decisions, and more. Keep your own ideas there, ask your agent to save what you learn together, and return to that context as your work grows. You can read, edit, and organize those documents yourself — and they stay yours.

Choose how you work

There are four ways to work with IWE. Mix and match them to fit your day:

Tool	How you'll use it
iWe for Mac	Write and browse in a native app, and connect your existing Claude/Codex agent.
Your own editor	Stay in Neovim, Helix, VS Code, or Zed, with note navigation, backlinks, and autocomplete.
CLI	Search and manage your notes from the terminal or scripts.
Claude/Codex	Let your agent read, write, and organize memory while you work through conversation.

All four work with the same Markdown documents. Draft a spec in your editor, develop it with Claude/Codex, browse it in the iWe app, or search it from the CLI. Use any combination you like; each tool also works independently.

Bring your own AI. Neither the IWE CLI nor the iWe Mac app includes an AI model. Both work on their own as tools for your notes. When you want AI help, use your existing Claude/Codex agent — in terminal or directly in the Mac app.

Plans · Charts · Technical documents · Releases — click a screenshot to see the iWe app in action on iwe.md.

Why IWE

Shared context. Your agent can use the same notes you write for yourself. Notes link to each other, and one note can belong to several topics, so you can follow an idea wherever it connects.
Memory you can read. Decisions and lessons saved by your agent are ordinary notes you can browse, correct, or delete.
Your notes stay yours. Everything is Markdown in a folder on your machine. Back it up, sync it, or keep it in git. You don't need an IWE cloud account to keep your notes; connecting an AI agent involves that agent's own setup and account requirements.

See it working on iwe.md →

iWe for Mac

If you'd like a dedicated space for your notes, use the native Mac app. Open a folder of notes and you get a fast, keyboard-friendly space to write and browse. You can also connect your existing Claude/Codex agent to work alongside you.

Works with your Claude/Codex agent. Connect the agent you already use, ask questions about your notes, and have it draft or reorganize them. Watch its edits appear in the document as it works.
Room to experiment. Each agent run is one undo step — try an idea, and roll it back if you don't like it.
Follow your ideas. Jump between related notes, search in a few keystrokes, and view Mermaid diagrams right in your documents. Your editor and other tools can keep working on the same files.

See iWe for Mac on iwe.md →

Open a notes folder and start with a note about something you're working on. Once Claude/Codex is connected, try asking it to summarize that note or help you develop an idea.

Your Own Editor

Keep writing in Neovim, Helix, VS Code, or Zed. IWE adds link autocomplete, backlinks, search, and safe renaming across your notes.

Follow the guide for your editor, open your notes folder, and try linking two notes with autocomplete. You can use IWE for your own writing without connecting an AI agent.

CLI

Prefer the terminal? Use IWE to search, create, and reorganize notes, or work it into your scripts. The CLI has no AI built in: these commands work on their own. Your existing Claude/Codex agent can use IWE's tools too.

Install with Homebrew, or choose another option from the installation guide:

brew install iwe-org/iwe/iwe

Then run these commands inside your notes folder:

iwe init
iwe find
iwe find --lexical "project decisions"

iwe find lists your notes; --lexical searches their content. Explore more in the CLI reference and workflow examples.

Claude/Codex

You can use IWE entirely through your agent. Ask Claude/Codex to save decisions, look up past work, and organize what you've learned. The agent works with your notes through IWE, and you can open those files yourself whenever you want.

IWE isn't tied to one AI. The same notes work with Claude Code, Claude Desktop, Codex, Gemini, Cursor, and any tool that supports the Model Context Protocol.

Give Claude/Codex a memory — for Claude Code, install the plugin, then run /iwe:init in any project you want remembered. For Codex, follow the agent connection steps below.

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

Then ask it to save a decision from your current work, and open the note it creates in your project.

Connect another agent — with Homebrew installed, install IWE:

brew install iwe-org/iwe/iwe

Run iwe init in your notes folder, then follow the agent connection guide to add the iwec MCP server with that folder as its working directory. For other installation options, see the installation guide.

Once connected, ask your agent: “Explore my IWE notes and summarize what's here.”

Or let the agent set itself up — paste this into any agent that can run commands:

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/

Learn More

Getting Started — install and set up
Working with AI — connect your agents
Usage Guide — everyday workflows
Examples — how people use IWE
CLI Reference and MCP Server — for the technically curious

Ready-made workspaces: dev-workspace — project memory for a coding agent · marketing-workspace — campaign memory for a marketing agent.

Get Involved

Trying IWE with your own notes? Tell us what felt useful and where you got stuck. Questions, rough edges, and examples of how you use it are all welcome in Discussions.

IWE is open source. You can also report a bug or help improve the documentation.

Community: Twitter/X · Reddit · Discussions

Building on IWE? The CLI and MCP server are the supported ways to integrate today. Tell us what you depend on so we know what not to break.

License

Apache License 2.0

docs/cli-create.md

IWE Create

Creates a document in one of two explicit modes.

Mode	Selected by	Who composes the document	Key
Content	default	you — `--content` is the whole file	required
Template	`--template` / `-t`	IWE — a named template renders your variables	derived from `key_template`, or explicit

The mode is never inferred from the shape of the input. --content and --template are mutually exclusive.

Usage

# Content mode -- the document is written exactly as passed
iwe create <KEY> --content '<DOCUMENT>'
cat doc.md | iwe create <KEY>

# Template mode
iwe create --template NAME --var title="..." [--var NAME=VALUE ...]
iwe create --template NAME --vars-yaml '<YAML mapping>'
iwe create --template NAME --vars-json '<JSON object>'
iwe create <KEY> --template NAME --set FIELD=VALUE [--set FIELD=VALUE ...]

Options

Flag	Description	Mode
`<KEY>`	Document key. Required in content mode; optional in template mode.	both
`-c, --content <STR>`	The complete document, written verbatim. `-` reads it from stdin.	content
`-t, --template <NAME>`	Compose from the named template. The name is always required.	template
`--vars-yaml <YAML>`	YAML mapping of template variables, values keeping their types.	template
`--vars-json <JSON>`	JSON object of template variables, values keeping their types.	template
`--var <NAME=VALUE>`	Set a single template variable to a verbatim string. Repeatable; overrides the bulk forms.	template
`--set <FIELD=VALUE>`	Set a single frontmatter field, written above the rendered document. Repeatable.	template
`-i, --if-exists <MODE>`	`fail` / `skip`, plus `suffix` / `override` in template mode.	both
`--strict`	Validate against the configured document schema before writing.	both
`-e, --edit`	Open the created file in `$EDITOR`.	both

On success the absolute path of the created file is printed. --if-exists skip on an existing document prints nothing and exits successfully.

Content mode

--content is the complete document: the YAML frontmatter block first (when there is one), then the markdown, normally starting with the title heading. The bytes are written to disk as given — nothing is added, nothing is moved.

iwe create people/ada --content '---
type: person
tags: [pioneer]
---

# Ada Lovelace

First English computer programmer.'

---
type: person
tags: [pioneer]
---

# Ada Lovelace

First English computer programmer.

Piped input works with or without --content -:

cat draft.md | iwe create projects/overview
cat draft.md | iwe create projects/overview --content -

--content - is an explicit request for stdin and is honoured at a terminal too — type the document and finish with Ctrl-D. Bare piped input is only read when stdin is not a terminal.

Because the key is explicit it is the document's identity, so --if-exists accepts only fail (default) and skip. There is no suffix — returning a different key than the one you asked for would be wrong — and no override; replacing an existing document is iwe update's job.

--var, --vars-yaml, --vars-json and --set all require --template — passing one without it is an argument error. In content mode the document you pass is already composed and already carries its own frontmatter, so there is nothing for them to do.

Template mode

--template NAME composes the document from a template in .iwe/config.toml. The name is always required — nothing about template mode is implicit: --var, --vars-yaml, --vars-json and --set all require --template, and --template in turn requires a name. (workspace.default_template applies to iwe new only.)

# The stock template shipped in every configuration
iwe create --template default --var title="Standup notes"

# Named template, explicit key
iwe create meetings/2026-07-28 -t meeting --var title="Sync"

Variables

--var NAME=VALUE sets one variable and the VALUE is used verbatim, as a string — never parsed. Markdown, punctuation and quotes all reach the template exactly as typed.

iwe create -t meeting --var title=Sync --var body='## Notes'

Typed values — booleans, numbers, lists, nested maps — come from the bulk forms instead: --vars-yaml '<YAML mapping>' or --vars-json '<JSON object>', at most one per command.

iwe create -t meeting --vars-yaml 'title: Sync
attendees: [ada, alan]
draft: false'

iwe create -t meeting --vars-json '{"title": "Sync", "attendees": ["ada", "alan"], "draft": false}'

Those two produce identical documents: draft is a boolean for {% if draft %}, attendees a list for {% for %}.

The bulk mapping is applied first and every --var overrides it, wherever the flags sit on the command line — --var title=A --vars-yaml 'title: B' still yields A. Among --var flags alone the last one for a name wins. Values are replaced wholesale; there is no deep merge.

Because --var values are strings, --var draft=false is the string "false", which {% if draft %} reads as true. Write draft: false in --vars-yaml when you mean the boolean. Shell quoting is stripped before IWE sees the argument, so a value-typing rule on --var could only ever guess; strings-only removes the guess.

body is the prose slot by convention. {{content}} is a legacy alias for {{body}} in templates — content names the same variable, and setting both is an error.
Template mode never reads stdin — piped input belongs to content mode. Every variable arrives through a flag; a variable no flag sets renders as empty.
slug, today, now and id are computed by IWE and cannot be set as variables, in any of the three forms.
The key derivation and {{slug}} read the title variable. title and body are ordinary variables by convention, not privileged parameters — a template that uses neither simply ignores them.
--vars-yaml '' and --vars-json '' are errors; --vars-yaml '{}' is a valid no-op. A --var argument without = that looks like a mapping points you at --vars-yaml.
A null variable value (body: null, body: ~, or a bare body:) is rejected — the template would render it as the text none. Pass '' for an empty value.

Passing multiline prose

--var values are verbatim, so a quoted multiline argument works as-is. In a --vars-yaml mapping, use a block scalar:

iwe create -t note --vars-yaml 'title: Release
body: |
  ## Notes

  Shipped.'

Frontmatter

--set FIELD=VALUE sets one frontmatter field, written above the rendered document. This is metadata prepended to the render, as distinct from the variable flags, which feed the render. Unlike --var, --set values are parsed as YAML — variables are render text, frontmatter is data.

There is deliberately no bulk frontmatter flag. Per-field flags (--set, --var) are the CLI's way of naming one thing; bulk structured input only comes in the format-named forms (--vars-yaml, --vars-json), and frontmatter has no such pair — iwe update --set doesn't either. A whole mapping is repeated --set.

iwe create people/ada --template default \
  --var title="Ada Lovelace" \
  --set type=person \
  --set tags='[pioneer]' \
  --set status=draft

---
type: person
tags:
- pioneer
status: draft
---

# Ada Lovelace

--set is repeatable, its VALUE is parsed as YAML, and the last --set for a field wins. YAML typing means --set version=1.10 stores the number 1.1 and --set note=~ stores null; quote to force a string, --set version='"1.10"'.
Fields are applied in command-line order. A new field is appended; a repeated field is replaced in place, keeping its position. Values are replaced wholesale — there is no deep merge.
When the template already emits its own frontmatter, passing --set is an error. Drop the flag, or drop the frontmatter from the template.

Mode boundaries

Variable values are trusted as passed — template mode does not inspect them. One check keeps composition honest: --set against a template that emits its own frontmatter is rejected, since the document would carry two frontmatter blocks.

If you already hold the complete document — frontmatter, title heading and all — pass it to --content and skip composition entirely.

Keys

Without a <KEY> the key comes from the template's key_template. With a <KEY> that derivation is skipped and the title still fills the document body.

--if-exists defaults to suffix for a derived key (quick capture appends -1, -2, …) and to fail for an explicit key, since an explicit key asserts an identity.

Template variables

Variable	Value
`{{title}}`	The `title` variable
`{{body}}`	The `body` variable. `{{content}}` is a legacy alias
`{{slug}}`	URL-safe form of the `title` variable
`{{today}}`	Current date — `workspace.date_format` for the key, `markdown.date_format` for the document
`{{now}}`	Current date and time — `workspace.time_format` / `markdown.time_format`, each falling back to the matching `date_format`
`{{id}}`	Random 8-character alphanumeric ID

Any other name passed with --var, --vars-yaml or --vars-json is available under that name.

Configuration

Templates are defined in .iwe/config.toml:

[templates.default]
key_template = "{{slug}}"
document_template = "# {{title}}\n\n{{body}}"

[templates.journal]
key_template = "journal/{{today}}"
document_template = "# {{today}}\n\n{{body}}"

Examples

# Write a document you already have
iwe create projects/overview --content "$(cat overview.md)"

# Idempotent create for scripts and agents
cat note.md | iwe create notes/inbox --if-exists skip

# Quick capture through the stock template
iwe create --template default --var title="Random idea"

# Named template with structured variables
iwe create -t meeting --vars-json '{"title": "Sync", "attendees": ["ada", "alan"]}'

# Reject the write when it breaks the document schema
iwe create docs/one --content "$(cat one.md)" --strict

Advantages

Shared context allows agents to access and build upon the same notes written by the user. evidence: README.md
Memory is stored as human-readable Markdown files that can be easily browsed, corrected, or deleted. evidence: README.md
Data remains under user control in local folders, avoiding dependency on proprietary cloud storage. evidence: README.md

Limitations

Requires manual setup of the MCP server or CLI tools to enable agent connectivity. evidence: README.md
The system does not include an AI model, requiring the user to bring their own agent. evidence: README.md

Security

Risk level: Low risk

This brain runs

Git hooks (1)

.githooks/pre-commit (pre-commit): runs on git pre-commit

Low risk: scripts-present (.githooks/pre-commit)

Attribution and licence

Created by

IWE

Publisher

IWE (Official IWE project)

Source

iwe-org/iwe · commit b733afe

Licence

Apache License 2.0 (files served here)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-12

AutoGineer is not affiliated with or endorsed by IWE.

Install from source

414 of its files are not served here, so there is no ZIP. iwe-org/iwe at b733afe

What it is

How it works

Requirements

Set it up

Usage

Documentation by IWE

IWE: a Markdown knowledge base you and your AI agent work on together

Choose how you work

Why IWE

iWe for Mac

Your Own Editor

CLI

Claude/Codex

Learn More

Get Involved

License

IWE Create

Usage

Options

Content mode

Template mode

Variables

Passing multiline prose

Frontmatter

Mode boundaries

Keys

Template variables

Configuration

Examples

See also

Advantages

Limitations

Security

This brain runs

Attribution and licence

Install from source