README
¶
memex
Manage Agent Skills across harnesses — Claude Code, Codex, pi — with symlinks from one git-versioned library.
Install · Usage · Configuration · Contributing
Named after Vannevar Bush's memex, the original vision of linked knowledge.
Skills live in one place (~/.memex/skills by default) and are linked as
directory symlinks into the global skills directory of each harness. memex
only ever creates and removes symlinks that point into the library; it never
touches real directories or links it doesn't own.
Install
Requires Go 1.26+:
go install github.com/kocieusz/memex@latest
The binary lands in $(go env GOPATH)/bin (usually ~/go/bin) — make sure
that's on your PATH.
Usage
Start a library by scaffolding a skill, pulling some from a repo, or adopting one you already have:
memex touch my-skill # scaffold skills/my-skill/SKILL.md
memex clone anthropics/skills # pick skills from a repo, copy them into the library
memex adopt ~/.agents/skills/some-skill # move a real skill dir into the library, symlink back
Then run memex to pick a harness target (claude, codex, pi, agents) and get
an interactive checklist — space toggles a skill, enter applies:
Target: ~/.claude/skills Source: ~/.memex/skills (2 skills)
▸ [x] scoped-commits linked
[ ] weighted-decision available
↑/↓ move · space toggle · a all · n none · / filter · enter apply · q quit
After applying (or backing out with q), you return to the picker, so
several harnesses can be updated in one session.
Inspect without the TUI:
memex ls # your library, with each skill's origin repo
memex ls --target claude # linked/available/broken skills in a target
memex ls -a --target claude # also native dirs and foreign links
memex ls --target claude --json
Keep things healthy:
memex doctor --fix # remove broken links, report missing SKILL.md
clone shallow-clones the repo, finds every directory holding a SKILL.md,
and opens a checklist to pick the ones to copy; each row shows the skill's
path inside the repo, and i reveals its description. It also takes full
clone URLs and GitHub /tree/<branch>[/dir] links; --branch picks a branch
explicitly (needed for branch names containing /).
memex records where each copied skill came from — repo, path, and a content
hash — in .origins.toml next to the skills. Re-running memex clone on the
same repo shows unchanged skills as up to date and changed ones as
selectable updates, with a warning when you've edited your copy locally
(updating overwrites it). Skills that came from anywhere else can't be
selected; that includes skills copied before memex tracked origins — re-add
them once to start tracking.
Configuration
The library defaults to ~/.memex/skills. To keep it somewhere else — say, in
your dotfiles repo — point memex at it in ~/.memex/config.toml:
library = "~/.dotfiles/skills"
Precedence, highest first: the --source flag, the MEMEX_SOURCE environment
variable, the config file, the default.
Contributing
memex doesn't accept external pull requests — read CONTRIBUTING.md before opening one. Bug reports and ideas are very welcome as issues.
Documentation
¶
Overview ¶
memex links Agent Skills from a git-versioned library (~/.memex/skills by default) into harness skills directories via symlinks.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
config
Package config loads the memex config file, a small TOML file at ~/.memex/config.toml — alongside the default library, ~/.memex/skills.
|
Package config loads the memex config file, a small TOML file at ~/.memex/config.toml — alongside the default library, ~/.memex/skills. |
|
library
Package library scans and manages the skill library: the source-of-truth directory (~/.memex/skills by default) whose immediate subdirectories containing a SKILL.md are linkable skills.
|
Package library scans and manages the skill library: the source-of-truth directory (~/.memex/skills by default) whose immediate subdirectories containing a SKILL.md are linkable skills. |
|
origin
Package origin records where library skills were cloned from — the repo, the path inside it, and a content hash of the skill as copied — so a later clone of the same repo can offer updates instead of refusing duplicates.
|
Package origin records where library skills were cloned from — the repo, the path inside it, and a content hash of the skill as copied — so a later clone of the same repo can offer updates instead of refusing duplicates. |
|
remote
Package remote fetches skills from a git repository: parse a repo reference, shallow-clone it, discover the skills inside, and copy the selected ones into the library.
|
Package remote fetches skills from a git repository: parse a repo reference, shallow-clone it, discover the skills inside, and copy the selected ones into the library. |
|
target
Package target scans harness skills directories, classifies their entries, and performs the only mutations memex is allowed: creating symlinks into the library and removing symlinks that point into the library.
|
Package target scans harness skills directories, classifies their entries, and performs the only mutations memex is allowed: creating symlinks into the library and removing symlinks that point into the library. |
|
tui
Package tui implements the interactive screens: the skill checklist for one target directory, and the target picker.
|
Package tui implements the interactive screens: the skill checklist for one target directory, and the target picker. |