memex

memex is a CLI tool that records the reasoning behind AI-assisted development as a versioned graph of decision nodes, modeled on Architecture Decision Records (ADRs).

Like an ADR, each node captures the why behind a change: the decision made, the alternative rejected, and the questions left open. Unlike an ADR, memex operates at the granularity of a single unit of work rather than only major architectural choices, and nodes form a directed graph so that each new piece of work inherits the context of its ancestor chain. Nodes are designed to be drafted by the agent performing the work and reviewed by a human.

memex is itself developed with AI assistance, and contributions in any working style are welcome, with or without AI tooling. Every pull request is reviewed for correctness and is expected to follow the development workflow documented in AGENTS.md.

---

Installation

From crates.io

The crate is published as memex-cli (the memex name is held by an unrelated crate); the installed binary is memex.

cargo install memex-cli

Prebuilt binaries

Download the archive for your platform from the latest GitHub release and extract the memex binary onto your PATH. Each archive ships with a .sha256 checksum file for verification.

From source

cargo build --release
cp target/release/memex /usr/local/bin/

Or run directly from the project root:

cargo run -- <command>

---

Quick Start

# Initialize a graph in your project
memex init

# Create a node for a new feature
memex node create --parent <root-id> --goal "Add user authentication" --tag auth

# During implementation, record decisions and artifacts incrementally
memex node edit --decision "Used JWT over session cookies for statelessness"
memex node edit --artifact "src/auth/mod.rs"
memex node edit --open-thread "Rate limiting not yet implemented"
memex node edit --rejected $'description = "Session-based auth"\nreason = "Requires sticky sessions, complicates horizontal scaling"'

# Mark the node as done
memex node resolve

# Later: generate a context payload to continue in a new conversation
memex context --format markdown

# View the full conversation history as a tree
memex graph view

---

Commands

Node IDs can be shortened to any unambiguous prefix (e.g. abc12345 → abc1).

memex init

Initialize a .memex/ directory in the current project.

memex node create

Create a new conversation node.

Flag	Description
--parent <id>	Parent node ID
--goal "..."	One-line goal for this node
--git-ref <ref>	Git branch or tag to associate
--tag <tag>	Tag the node (repeatable)

memex node edit [id]

Without flags, opens $EDITOR with a TOML template for bulk editing. With additive flags, updates individual fields without opening an editor:

Flag	Effect
--goal "..."	Overwrite the goal
--decision "..."	Append a decision (repeatable)
--artifact "..."	Append a key artifact (repeatable)
--open-thread "..."	Append an open thread (repeatable)
--rejected '...'	Append a rejected approach as inline TOML (repeatable)
--summary "..."	Replace the entire summary from TOML (mutually exclusive with the flags above)

The --rejected flag expects inline TOML with description and reason fields:

memex node edit --rejected $'description = "Alternative approach"\nreason = "Why it was rejected"'

memex node auto [id]

Apply agent-authored draft additions from a JSON payload on stdin. Designed for the case where an LLM agent has the conversation transcript and can draft node updates for the human to review, so curation becomes a side effect of doing the work rather than a separate task.

Flag	Effect
--from-stdin	Required. Read the JSON payload from stdin.
--dry-run	Print the diff against the target node without writing (default).
--apply	Write the merged additions to the node. Mutually exclusive with --dry-run.

The payload is a JSON object; every field is optional, so an agent can send only what it has for a given turn:

{
  "decisions": ["Use SQLite for v2 storage"],
  "rejected_approaches": [
    {"description": "Postgres", "reason": "Too heavyweight for a single-user CLI"}
  ],
  "open_threads": ["Audit fts5 stability"],
  "key_artifacts": ["src/db.rs"]
}

Re-running the same payload is a no-op. Free-text entries dedupe on normalized text (trim, collapse whitespace, lowercase, strip trailing .!?); artifacts dedupe on exact path. goal is not part of the payload; scope changes go through explicit memex node edit --goal.

# Preview (default):
cat payload.json | memex node auto --from-stdin

# Write:
cat payload.json | memex node auto --from-stdin --apply

memex node show [id]

Display a node's full summary.

memex node list

List all nodes with IDs, parent IDs, status, git ref, and goal.

memex node resolve [id] / abandon [id] / reopen [id]

Transition a node's status between Active, Resolved, and Abandoned.

resolve and abandon prompt for confirmation when run in an interactive terminal:

Resolve node abc12345 "Add user authentication"? [y/N]

Flag	Description
--force / -y	Skip the confirmation prompt (for scripts and CI)

Non-interactive contexts (pipes, CI) skip the prompt automatically.

memex context [id]

Generate a context payload. Walks the ancestor chain and formats it for pasting into a new conversation.

Flag	Description
--depth <N>	Number of ancestors to include (default: 2)
--format <fmt>	Output format: markdown (default), xml, plain

memex graph view

ASCII tree of the full conversation graph. Shows status icons and marks the active node.

memex search <query>

Full-text search across all node summaries, including goals, decisions, artifacts, open threads, rejected approaches, and tags.

memex pr-context --file <path> [--file <path> ...]

Render a markdown payload listing every node whose key_artifacts exact-match one of the given files. Sorted most-recent-first. Designed to be piped into a PR comment so reviewers see what was tried, rejected, or left open in earlier work on these files.

Flag	Description
--file <path>	Repo-relative path to consider. Repeatable.
--marker <html>	HTML marker comment used by automation to find and update an existing comment idempotently. Defaults to <!-- memex-pr-context -->.
--limit <N>	Cap on the number of nodes rendered (most recent first). Default 5. Pass 0 for no cap. When the cap triggers, a one-line footer reports how many older matches were omitted.

Output is written to stdout. The first line is always the marker, so callers can locate prior comments without re-parsing the body.

---

GitHub Action

.github/workflows/memex-pr-context.yml ships with the repo and surfaces relevant memex node context as a PR comment on every push. To use it in another project, copy the workflow file and replace the build step with cargo install --locked memex-cli. The workflow:

1. Computes changed files via git diff --name-only origin/<base>...HEAD.
2. Pipes them to memex pr-context.
3. Looks for an existing PR comment whose body starts with the marker, then updates it in place or creates a new one.

Pull request titles containing [skip memex] skip the comment.

---

Workflow

The pattern for using memex alongside any project:

1. Branch: git checkout -b <type>/<name>
2. Create a node: memex node create --parent <parent-id> --goal "what you're working on"
3. Implement. As you work, record decisions and artifacts incrementally:

   memex node edit --decision "Chose X over Y because ..."
   memex node edit --artifact "src/new_module.rs"
   

4. Resolve: run memex node resolve when the work is complete.
5. Commit: stage source changes and .memex/ files together.
6. Next session: memex context generates a formatted ancestor summary to paste into a new conversation, so future sessions pick up where the last left off.

---

Node Summary Format

When editing a node with $EDITOR (memex node edit with no flags), a TOML template is opened:

goal = "What this conversation was working toward"

decisions = [
  "Specific decision made",
]

[[rejected_approaches]]
description = "Approach considered"
reason = "Why it was not used"

open_threads = [
  "Unresolved question or follow-up",
]

key_artifacts = [
  "src/relevant_file.rs",
]

You can also build this incrementally using the additive flags on memex node edit; see Commands above.

---

Configuration

memex init creates .memex/config.toml at the project root.

[git]
auto_prompt_on_branch = true
annotate_on_commit = false

[storage]
track_in_git = true
transcript_storage = "none"

[ui]
editor = ""      # defaults to $EDITOR

---

Storage

Path	Committed	Notes
.memex/config.toml	Yes	Shared project settings
.memex/nodes/*.json	Yes	Full conversation node history; each node's parent_ids is the source of truth for the DAG
.memex/state.json	No	Local session state (active node)

.memex/
  config.toml       # committed - shared settings
  nodes/
    <uuid>.json     # committed - one file per node
  state.json        # gitignored - local session state