AutoGineer
Generated banner for IWE: a Markdown knowledge base you and your AI agent work on together
Generated logo for IWE: a Markdown knowledge base you and your AI agent work on together

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 stars

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
FolderRoleFiles
.githubagent-config4
docsdocs70
.githooksfolder1
cratesfolder381
npmfolder15

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

  1. 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
  2. Not scanned by AutoGineerAutoGineer could not scan everything it runs. https://www.npmjs.com/package/@iwe-org/mcp

  3. 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.

<br/> <p align="center"> <a href="https://www.youtube.com/watch?v=D58bPkOvbxE"> <img src="https://iwe.md/images/video-thumbnail.jpg" alt="Watch the IWE intro video on YouTube" width="600"> </a> </p> <br/>

Choose how you work

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

ToolHow you'll use it
iWe for MacWrite and browse in a native app, and connect your existing Claude/Codex agent.
Your own editorStay in Neovim, Helix, VS Code, or Zed, with note navigation, backlinks, and autocomplete.
CLISearch and manage your notes from the terminal or scripts.
Claude/CodexLet 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.

<a href="https://iwe.md/?ref=readme-shot"><img src="https://iwe.md/images/app/GH-screen-1.1.png" alt="iWe for Mac showing project plans and connected documents" width="820"></a>

<p> <a href="https://iwe.md/?ref=readme-shot"><img src="https://iwe.md/images/app/GH-screen-2.png" alt="Bug tracking with charts" width="32%"></a> <a href="https://iwe.md/?ref=readme-shot"><img src="https://iwe.md/images/app/GH-screen-3.png" alt="Technical documents with code" width="32%"></a> <a href="https://iwe.md/?ref=readme-shot"><img src="https://iwe.md/images/app/GH-screen-4.png" alt="Release documents" width="32%"></a> </p>

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

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/benchmark.md

Benchmark

How we measure IWE's performance, what the harness looks like, and the numbers we have today.

What we benchmark

The iwe CLI rebuilds the document graph on every invocation, then runs a query. Each invocation pays both costs in sequence, so we measure them separately:

  1. Load — walk the project directory, read every .md file, parse it, build the in-memory Graph (arena + indexes). Paid once per invocation. The LSP server (iwes) and MCP server (iwec) pay this cost only once at startup and reuse the graph for the lifetime of the session. The load bench measures this both without (plain) and with (indexed) the BM25 search index — see Search Ranking.

  2. Query — evaluate filters / structural anchors / projections against an already-loaded Graph. Paid per query inside an LSP session, or amortized in CLI commands that fan out (find, count, tree, retrieve, stats).

We don't benchmark iwes (the LSP server) end-to-end, the MCP server, or mutating subcommands (update, delete, extract, inline, etc.) — they write to disk and aren't in the hot read path.

Harness

We use criterion — the de facto Rust benchmarking framework. Two bench targets live under crates/iwe/benches/:

  • crates/iwe/benches/load.rs — Stage 1, load only.

  • crates/iwe/benches/query.rs — Stage 2, query only.

Both are wired in crates/iwe/Cargo.toml under [[bench]] harness = false. Shared test helpers (corpus generator, graph loader) live in crates/iwe/benches/common.rs.

Per-bench config: sample_size(10) for both stages (criterion's minimum), measurement_time(30s) for load and measurement_time(7.5s) for query. Trades narrower confidence intervals for shorter wall-clock — full runs land at ~5 minutes per stage.

Corpus

Synthetic, deterministic, generated into a TempDir at bench setup. The generator (crates/iwe/benches/common.rs::generate_corpus) uses StdRng::seed_from_u64(42) so the corpus is byte-identical across runs.

Per doc (doc-NNNNN.md):

---
title: "Doc 00001"
type: post
category: <one of alpha | beta | gamma | delta>
status: <one of draft | published | scheduled>
created: 2026-01-01
---

[Doc 00742](doc-00742)

[Doc 00193](doc-00193)

[Doc 00518](doc-00518)

## Section 1

Some paragraph text mentioning [Doc 00077](doc-00077) in passing. Lorem ipsum dolor sit amet.

... (3 paragraphs per section, 2 sections per doc)
ElementCountPurpose
Frontmatter fields5exercise Filter::Field queries
Inclusion links (own line)3 per docinclusion edges for descendants/ancestors traversal
Headers (##)2 per docsection structure for parser
Paragraphs6 per docparser load
Inline links6 per docreference edges for referenced_by / references

Plus one hub.md with n_docs / 10 inclusion links — anchor for included_by_d1 and included_by_unbounded benches.

Sizes used: 5_000, 10_000, 20_000 for both stages. Total file counts on disk (each ~700 bytes): 5_001 / 10_001 / 20_001.

Running

# Both stages
cargo bench -p iwe

# One stage at a time
cargo bench -p iwe --bench load
cargo bench -p iwe --bench query

# Filter to specific benches (substring match)
cargo bench -p iwe --bench load  -- 'load/indexed/10000'
cargo bench -p iwe --bench query -- 'query/filter/included_by_unbounded'
cargo bench -p iwe -- '/20000$'                # all 20k variants (plain + indexed)

# Quick mode (~10 samples, no statistical inference — for iteration)
cargo bench -p iwe -- --quick

# Save / compare baselines
cargo bench -p iwe -- --save-baseline before
# ... make changes ...
cargo bench -p iwe -- --baseline before

Criterion writes HTML reports + JSON to target/criterion/. Open target/criterion/report/index.html for the overview.

Reading criterion output

Each bench prints:

load/indexed/10000  time:  [low_95%  median  high_95%]
                 change: [low% median% high%]  (p = 0.NN < 0.05)
                 Performance has improved.

The three numbers are a 95% confidence interval for per-iteration time, derived from criterion's bootstrap of the 10 samples it took. Tight intervals (low ≈ high, e.g. ±1%) mean the measurement is stable. Wide intervals (±20%+) mean noise — re-run the affected benches in isolation:

cargo bench -p iwe --bench load -- '/20000$'

The change: line compares to the previous run criterion has saved to disk (or to a named baseline if --baseline NAME was passed).

Outliers like Found 2 outliers among 10 measurements (high severe) flag samples that fell far outside the typical distribution — usually system noise (GC pause, disk hiccup). They don't invalidate the run but suggest re-running for a clean signal.

Numbers

All times are per-iteration on an Apple M3 Pro laptop. Stage 2 (query) was measured in May 2026; Stage 1 (load) was re-measured in July 2026 when the BM25 search index landed.

Stage 1 — load

The load bench runs two variants per corpus size: plain builds the graph without the search index; indexed builds it with BM25 full-text indexing enabled — what iwe find and the LSP / MCP servers use.

BenchTime
load/plain/5000144 ms
load/indexed/5000204 ms
load/plain/10000329 ms
load/indexed/10000435 ms
load/plain/20000705 ms
load/indexed/20000958 ms

Search index overhead. Building the BM25 index adds roughly a third to a cold load, scaling linearly at ~12 µs per document:

Corpusplainindexedaddedoverhead
5,000144 ms204 ms+60 ms+42%
10,000329 ms435 ms+106 ms+32%
20,000705 ms958 ms+253 ms+36%

The cost is dominated by tokenization and Snowball stemming: the default tokenizer normalizes, lowercases, splits on unicode word boundaries, drops stop words, and stems every remaining token — and stemming is CPU-bound. Corpus extraction (walking each document to plain text) and embedding both run in parallel across documents above a 128-document threshold; only the final scorer population is serial, because it writes a shared inverted index. The CLI pays this once per find run; the LSP and MCP servers pay it once at startup, then only the per-edit cost of re-indexing a single changed document. See Search Ranking for the indexing logic.

Stage 2 — query
Benchn=5kn=10kn=20k
query/filter/field_eq2.7 ms5.7 ms12.1 ms
query/filter/compound_and3.0 ms6.3 ms12.9 ms
query/filter/in_many_keys1.4 ms2.9 ms5.9 ms
query/filter/included_by_d1410 µs920 µs2.3 ms
query/filter/included_by_unbounded9.2 ms21 ms48 ms
query/filter/referenced_by121 µs251 µs499 µs
query/filter/roots3.3 ms13.3 ms60 ms
query/op/find_full1.8 ms4.7 ms15.0 ms
query/op/count2.2 ms5.8 ms17.6 ms
query/op/retrieve_backlinks1.7 ms3.5 ms7.4 ms
query/op/stats_all5.5 ms13.0 ms30.4 ms

Notable scaling:

  • query/filter/included_by_unbounded is the slowest filter case — at n=20k the hub reaches ~94% of the corpus through 4-7 hops.

  • query/filter/roots is super-linear in n. The --roots implementation at crates/iwe/src/main.rs:1260 calls graph.get_inclusion_edges_to(k).is_empty() for every key, and that lookup is linear in total inclusion edges.

  • query/op/retrieve_backlinks is super-linear for the same reason (inbound reference walk uses the same index).

Iteration counts

Criterion runs each bench (measurement_time / per_iter) times, organized into 10 samples for the bootstrap. Concrete iteration counts from the current load run:

Benchper-iteriters/sampletotal iters
load/plain/5000144 ms22220
load/indexed/5000204 ms16165
load/plain/10000329 ms11110
load/indexed/10000435 ms11110
load/plain/20000705 ms555
load/indexed/20000958 ms555

At n=20 k the bench runs ~55 iterations per measurement — solid signal. For tighter intervals at scale bump sample_size(20) and measurement_time(60s), accepting roughly 2× wall-clock.

Profiling

For finding bottlenecks in the load path, xctrace (Apple's Instruments CLI) works without sudo and produces a trace viewable interactively in Instruments.app:

# Build the bench binary with debug symbols
CARGO_PROFILE_BENCH_DEBUG=true cargo bench -p iwe --bench load --no-run

# Find the binary path (hash will differ)
ls target/release/deps/load-*

# Record a 20-second profile of one bench
xctrace record --template "Time Profiler" \
  --output /tmp/load.trace \
  --launch -- target/release/deps/load-XXXXX \
  --profile-time 20 'load/indexed/20000'

# Open in Instruments
open /tmp/load.trace

The bench binary's --profile-time SECONDS BENCH_NAME flag (provided by criterion) runs the iter closure in a tight loop without statistical analysis, so you get clean profiling samples.

For flamegraph SVG output, cargo flamegraph works but needs sudo because dtrace is restricted by SIP on macOS:

# cache sudo credentials, then:
sudo cargo flamegraph --bench load -- --profile-time 20 'load/indexed/20000'

Out of scope

  • iwes (LSP server) — separate harness; not currently benched.

  • iwec MCP server — separate harness; not currently benched.

  • Mutating CLI subcommands — not on the hot read path.

  • Real-world corpus runs against ../marketing/ (102 files) — covered by the synthetic generator, which produces realistic frontmatter shapes.

  • iwe binary as a subprocess — would re-pay the load on every invocation, defeating the load/query split.

485 files · 414 not served here

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

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