Skip to content
memex

Guides

Getting started

memex is used mostly by agents. Set it up once in the repo, and every agent that reads AGENTS.md reads intent before code. You read the same Markdown yourself, in the repo.

Install and init

One command in the repo you want to index. It installs the binary if needed, then runs memex init.

$ npx @aswemaythink/memex init

Or install from a checkout of the repo, then run memex init:

$ git clone https://github.com/aswemaythink/memex && cd memex
$ cargo install --path . --locked

memex init is safe to repeat: it never overwrites files in .memex/, and it reports each action.

project
$ memex init
created .memex/.gitignore
created .memex/config.json
created .memex/collections/.gitkeep
created AGENTS.md
updated CLAUDE.md
… then the atlas, as memex info prints it

What init wires up

  • A block in AGENTS.md, between markers, that tells any agent to read intent before code and names the verbs to do it with.
  • An existing CLAUDE.md gets an @AGENTS.md line, so Claude Code reads the same block.
  • .memex/, the log store and the place for collection files.

On Claude Code, the optional plugin adds the memex skill and a start hook that prints memex info at the top of every session.

/plugin marketplace add aswemaythink/memex
/plugin install memex@memex

What agents do from then on

  • Read intent before code. memex info for where things are, then memex search and memex show to find the few files worth opening.
  • Log what they find. memex log <stream> records a finding and hands back a one-line ref.
  • Audit after changing code. Update the header or README the change invalidated, then run memex audit <paths> and fix what it lists.

Each verb has a page in the reference.

With an orchestrator

Workers log their full report with --agent and return one line, report: <ref>. The orchestrator reads a ref only when it needs the detail, and finds messages addressed to it with memex search to:<id>.

# a worker ends its run
$ memex log impl --agent worker-2 --to orchestrator <<'EOF' … EOF
impl:20261013-214107-show-walks-hub-readmes
# and returns one line:  report: impl:20261013-214107-show-walks-hub-readmes

# the orchestrator
$ memex search to:orchestrator
$ memex show impl:20261013-214107-show-walks-hub-readmes

More in Hand-off and messages.

What you still do

Write and keep the READMEs and headers: they are the intent agents read. Review what agents distill into them, since a log is only a record of one run.

Why this works: The intent layer and trails.

Next: Patterns · Reference · Concepts