The Problem

Technical teams need AI agents to navigate structured knowledge without duplicating notes or losing context. Markdown files grow organically; without a system, AI agents retrieve isolated snippets, miss hierarchical relationships, and cannot reliably update or trace references across a knowledge base. Existing tools either lock data into proprietary formats or require manual link management that doesn't scale.

What This Does

IWE is a Markdown-based knowledge graph that organizes notes hierarchically while avoiding duplication. It uses inclusion links to create parent-child relationships (polyhierarchy), so the same note can appear under multiple parents without copying content. Context inheritance enriches any note with details from all its parents. The CLI provides retrieval, update, and refactoring tools; the LSP integration gives editors search, go-to-definition, backlinks, rename refactoring, and code actions (extract/inline notes). The repository contains three crates: liwe (core graph and parsing), iwe (CLI), and iwes (language server protocol layer).

Code health findings from static analysis: 38 issues across 9 high, 29 medium severity. High cognitive load from deep nesting in crates/iwe/src/export/graph_data.rs, crates/iwe/src/retrieve.rs, and crates/iwes/src/router/server/actions/attach.rs (max indentation depth 8). Duplicated code blocks repeated 190 times across 46 files, particularly in export and retrieve modules. Six oversized files exceed 1,300 lines (crates/iwe/tests/retrieve_test.rs, crates/iwe/src/main.rs, crates/iwes/tests/fixture.rs), making changes ripple widely. The full analysis appears in the MEASURED FINDINGS block.

How It Is Wired

Execution starts at main in crates/iwe/src/main.rs:442, which reaches 231 functions and is the sole entry point called by nothing else in the repo. The internal call graph contains 3,066 resolved call edges. The most-called functions are path (187 call sites), uri (95), write (78), and with (60). A traced path from main reaches the filesystem via OpenOptions::new().create(true) in approximately 3 hops. Key hubs: crates/liwe/src/graph.rs (84 functions, called from 32 other files, calls into 12) defines the document graph, parser, and lines; crates/liwe/src/graph/graph_node.rs (82 functions) defines node IDs, metadata, and child relationships; crates/liwe/src/model.rs (18 functions, called from 37 files) handles fmt, parent, source, path, and combine operations. Entry points include delete_command (crates/iwe/src/main.rs:1027, reaches 114 functions), export_command (crates/iwe/src/main.rs:959, reaches 118 functions), and find_command (crates/iwe/src/main.rs:561, reaches 113 functions). The code touches 10 external-command functions and 1 file-read/write function outside itself.

How To Use It

Setup:

cargo build --release  # or `cargo install iwe` from the root

Build requires Rust and the Cargo workspace at the repo root. No Dockerfile or Makefile targets are needed for basic CLI use.

Configuration: No environment variables or secret keys are required for core functionality. Configuration lives in Cargo.toml files per crate and in per-note Markdown front matter. The .github/workflows/ directory contains CI configs that reference HOMEBREW_TAP_TOKEN; this secret must not be committed or exposed in fork-triggered workflows.

Running it:

iwe init            # initialize a new knowledge graph
iwe find <query>    # search notes by title or content
iwe retrieve <id>   # retrieve a node with full context (children, parents, related)
iwe export          # export graph data (DOT format)
iwe new <note>      # create a new note with template

All CLI commands are defined in crates/iwe/src/main.rs. The LSP server runs via crates/iwes/src/main.rs and integrates with VS Code, Neovim, Zed, and Helix.

Real-World Use

An AI agent assisting a developer can retrieve a note on "authentication" and receive the target Markdown plus all parent sections, child notes, and backlinks in a single query. The agent can then invoke iwe retrieve <id> to get full context, make edits via code actions (extract section into new note, inline content back into parent), and rename the file with automatic link updates—all without leaving the editor. Cross-links ensure the same conceptual note appears in multiple project contexts without duplication.

Code Health & Issues

  • [CRITICAL] Keep secrets out of workflows a fork can trigger - .github/workflows/homebrew.yaml exports HOMEBREW_TAP_TOKEN at publish/cloud scope; a pull request becomes credential exfiltration risk. Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on required reviewers.
  • [HIGH] Pin third-party GitHub Actions to commit SHAs - .github/workflows uses dtolnay/rust-toolchain@stable, release-plz/action@v0.5, taiki-e/setup-cross-toolchain-action@v1, taiki-e/upload-rust-binary-action@v1. Tags can move; pin to 40-character commit SHAs and let Dependabot bump them.
  • [HIGH] Open a pull request instead of pushing to the default branch - .github/workflows/homebrew.yaml uses git push; automated commits land on the deploying branch with no tests having run against the result. Push to a bot branch and open a pull request, or restrict push to tag refs.
  • [MEDIUM] Declare least-privilege permissions for GITHUB_TOKEN - 2 workflows declare no permissions, 1 references secrets. Add permissions: contents: read at the top of each workflow and widen per job only where needed.
  • [MEDIUM] Gate pull requests on a dependency vulnerability scan - no dependency scan in CI. Add dependency-review-action on pull_request or osv-scanner on push and a schedule.
  • [MEDIUM] Set persist-credentials: false on checkout - rust.yml checkout keeps the token, then dependencies are installed. The token stays in .git/config for every later step. Add with: persist-credentials: false and pass an explicit token only to the step that pushes.
  • [LOW] Set timeout-minutes on workflow jobs - 4 workflows declare no job timeout. A wedged step runs to the six-hour platform default. Add realistic timeout-minutes to each job.

The Bottom Line

IWE delivers a functional, local-first Markdown knowledge graph with solid LSP editor integration and CLI tools that AI agents can use immediately. The graph structure (inclusion links, polyhierarchy, context inheritance) is the strongest differentiator—it solves the note-duplication problem better than tagging or flat linking. However, the codebase carries significant cognitive load: deep nesting, widespread duplication, and six files over 1,300 lines make changes risky and ripples widely. The CI hygiene issues (secret exposure, unpinned action versions, missing dependency scans) are fixable but require attention before the project is safe for open contribution. Teams that need a self-hosted, AI-agent-readable knowledge graph with editor integration will find IWE practical today; organizations requiring zero-maintenance CI or open contribution without secret-risk should budget remediation time.