zhangxiangliang/easymem/easy-llm-wiki

easymem

The project can have a wiki: markdown pages an agent wrote after reading the sources, so nobody has to read them again. Search it with npx easymem.

The wiki is compiled knowledge, not a log. Every page is a subject someone would look up by name, and every page says which source files it came from.

Search before you grep

npx easymem search "how are refunds handled"

A miss costs a second. A hit saves you reading the files.

Search is BM25 over every page, and then it walks one hop along [[wikilinks]]. That second part is the reason to use it: a page that never contains your words still comes back, if a matching page links to it. Asking about refunds returns the refund policy and the payment code it depends on, even though the code never says "refund".

npx easymem search "checkout" --limit 5 --hop 2

Raise --hop to 2 for the context around an answer rather than the answer itself. Drop it to 0 when you know the exact term and want direct hits only.

If the wiki is empty, search returns nothing and list returns []. Say so and offer to build it — see Building it below.

Reading a result

Search does not return the source files a page came from. Open the page for those:

npx easymem read wiki/concepts/checkout-flow.md   # prints the page, sources in the frontmatter
npx easymem list                                  # every page with its sources
npx easymem graph                                 # hubs to start from, orphans to fix

When the wiki disagrees with the code

The code wins. A page is one agent's reading of the source on one day, and the source has moved since. When a page and the file it cites disagree, believe the file, say so, and fix the page.

To find those pages before they mislead someone:

npx easymem lint

• outdated — the source changed content since the page was written. Re-read

and reconcile. This is compared by hash, so it is a real edit, not a reformat.

• staleSources — the source is gone. The page may describe nothing.
• danglingLinks — a [[link]] with no page. A typo, or a page worth writing.
• orphans — nothing links here. Usually a missing link elsewhere.
• missingSources / untracked — the page cannot be checked, or nothing is

watching what it came from.

• missingLinks — it names another page in prose without linking it. Adding the

link is what makes that page reachable by search.

• reviewForContradiction — pages built from the same source. **Candidates, not

findings.** Read both before changing either: two pages can describe one file from different angles without disagreeing, and rewriting a page that was never wrong costs more than leaving the pair alone.

Start with summary — it counts each category, so you can tell at a glance whether there is anything worth reading.

Write when you learn something durable

Durable means: still true next month, and expensive to work out again. An architecture, a data flow, a gotcha, the reason an obvious approach does not work. Not today's bug and not today's diff.

Read the rules first — they are not in this file:

npx easymem guide

That prints the page format, the type list, the linking convention and the update protocol. They are what keep the wiki searchable instead of turning it into a pile of notes. This file says when to reach for the wiki; guide says how to write in it.

npx easymem write --type concept --title "Checkout Flow" \
  --description "Why money moves at shipment, not at checkout." \
  --sources docs/checkout.md,src/payment.ts \
  --body-file /tmp/page.md

--body-file is usually easier than --body — a page is multi-line markdown and quoting it inline goes wrong. Piping the body in works too.

Building it

npx easymem pending src/**/*.ts docs/*.md

It answers with to_ingest (new or changed), skipped (already done and unchanged — do not read these again).

deleted stays empty unless you pass --complete with the full source list. It means "recorded before and not in the list you gave me", which for a partial list is just "not mentioned" — acting on that would delete pages for files that are still there.

Read each path in to_ingest, then write once per subject worth its own page. One source file often makes several pages.

Finish with:

npx easymem reindex --ingested src/a.ts,docs/b.md

Search results do not change until you do this. A page you just wrote is invisible to search until the reindex runs.

Judgement, not rules

• A gap is a result. If the wiki did not answer the question and you had to

read the sources, that is worth a page. Write it before you move on.

• Merge, do not clobber. write on an existing type and title overwrites

it, with nothing to stop you — not even a page a human hand-edited. read it first and fold your new understanding in, or you silently delete what the last pass learned.

• A wiki this small is not worth it. If the project is twenty tidy files,

say so — grep is faster and a wiki is overhead. It earns its keep when the sources are large, scattered, or expensive to read.

Where the pages go

.easymem/wiki/, next to the code. Plain markdown: commit it, read it, edit it by hand. .easymem/.state/ is a cache and belongs in .gitignore. Point somewhere else with --dir <path> or EASYMEM_DIR.

If you would rather connect it over MCP

Every subcommand here is the same tool the MCP server exposes. Running as a server keeps the index warm between calls, which is worth it for a long session over a large wiki; npx rebuilds it each time, about 200 ms for a thousand pages. To connect it, tell the user to add this to .mcp.json and restart:

{
  "mcpServers": {
    "easymem": { "command": "npx", "args": ["-y", "easymem"] }
  }
}

Then call the tools wiki_search, wiki_read, wiki_write and the rest directly instead of shelling out.

Do not

• Do not re-read files pending reported as skipped.
• Do not translate. Keep the language the source is written in.
• Do not write anything the source does not say. No page is better than a

confident wrong one, because the next reader will trust it.