wayfind

Coding and research agents forget between sessions. When one agent hands off to another, it loses the thread. Plans grow and nobody prunes them. And the person in charge cannot see the big picture without reading everything.

wayfind keeps all of this in one validated memory in your repository:

• the goal;

• what the goal needs;

• what you already have;

• the ideas and projects where the two meet;

• the decisions waiting on you;

• the lessons learned.

One memory, two readers. People and agents work on the same task through different interfaces, so wayfind compiles the one memory into each reader's form:

On a real 61-card research memory, the default briefing is about 3,100 characters (roughly 800 tokens), where reading the file itself costs about 11,000 tokens.

The page

wayfind open opens the live page for this memory. If it is already running, it is reused; if not, it starts in the background. Close the tab whenever you like and come back later. wayfind open --stop stops it.

Workstreams. One page holds every memory you have opened this way: a product and a few papers, say, each in its own repository with its own memory. A sidebar lists them. For each one it shows what agents changed since you last looked, what is waiting on you, how much is open, and who touched it last. Click one to switch. To add a workstream, run wayfind open in its project. Removing one from the sidebar only takes it off the list; its memory is not touched. The list is kept on this machine in ~/.wayfind, never inside a memory.

• Since you last looked, at the top: what Claude Code, Codex, or any other agent changed since your last visit, what is waiting on you, and the open work. Got it marks it read in this browser, and looking never writes to the memory. Your own edits are not listed as news.

• Map, for daily work. Pick a project to see its own map, with its open work one click away. A memory with one project opens straight on it. Each column shows a few cards and offers the rest, so the map stays readable as the memory grows.

• Overview, for the whole plan. It shows goals and the projects that reach them.

Click any card to open it. For live work, you can change the next step and the status there, add a task to a project, answer a question, or leave a note for the agents. Each change is validated and logged as owner, like any CLI write, and agents see it on their next read. When an agent writes, the page updates by itself, but it waits while you are typing.

Tidy up appears once finished work has sat untouched for two weeks. One click sets it aside (archived with a dated reason, never deleted; still in the drawer and the history) and, if anything needs judgment, asks the agents to tidy the plan. Agents run wayfind tidy at the end of a session too, so the map stays simple by itself, and the details are one question to an agent away.

More holds detailed readings of the same cards: a folding Roadmap, a Timeline of recorded activity (what happened, never a schedule), and groupings by Topic and by an optional recorded Area. The page uses everyday words: ideas are tasks, topics are needs, assets are resources, and decisions are questions. The memory's own names do not change.

Related MCP server: local-knowledge-suite

As a study planner

wayfind init --profile study --goal "..." starts a memory in study words: needs are knowledge points (not yet, shaky, solid), resources are notes and materials, tasks are review steps (read, derive, exercise, recall, explain, mock), and projects are tracks. The cards are the same; the page, the briefing, and the step types change. Two things then happen by themselves:

• A result schedules the re-do. wayfind review I3 wrong --note "...", or Right / Shaky / Wrong in the step's drawer, records the attempt as evidence and sets when the step comes back: wrong tomorrow, then D+3, then D+7; shaky in three days; a right on the D+7 re-do, or on a step never missed, closes it.

• Every knowledge point is checked on a cadence. wayfind check B2 shaky --note "...", or Solid / Shaky / Not yet in the point's drawer, records how well it is known now and when to check again: solid in 14 days, shaky in 3, not yet tomorrow. The review steps under it do the learning in between.

• The day fills itself. wayfind routine P1=50 P2=55 "Log mistakes=10" is the day's shape. wayfind today, and the top of the page, list the checks and re-dos that are due, then one step per slot. Agents populate the steps under each knowledge point and, once a point is solid, propose extensions below it; you record results.

wayfind export --out plan.json writes the plan (tracks, points, steps, routine, today) for a page outside wayfind, such as a progress widget in your notes. A card's url field is shown as a link, so a knowledge point can point at its note.

How it works

wayfind finds the way from where you are to where you want to go by searching from both ends:

• Backward from the goal: what does it need? These needs form a tree.

• Forward from what you have: results, tools, and data, and what could be built from them.

Ideas are proposed where the two meet, then grouped into projects.

wayfind frontier shows where the search stands:

• Unmet needs: needs that no idea addresses yet.

• To build: assets that are still being built.

• Unused: assets you have that nothing uses.

• Expand: ideas worth expanding, best score first.

• Contract: ideas to cut, for example ones that address only needs the world already covers, rejected ideas that are still live, or ideas parked too long.

• Blocked: decisions only you can settle, and what each one blocks.

Nothing is ever deleted:

• Set-aside work is archived; wrong or dominated work is pruned. Both need a reason.

• Every write is validated and logged.

• Corrections appear in every briefing, so no later agent repeats the mistake.

Install

wayfind needs Python 3.9 or newer and nothing else.

pip install git+https://github.com/tianyi-zhang-02/wayfind

Quick start

cd your-project
wayfind init --goal "Any agent can pick up this project where the last one left off" --agents AGENTS.md
wayfind add topic "Users can install it in one step" --status open summary="..."
wayfind add asset "A working CLI" --status have
wayfind add project "v1 release" --status active
wayfind add idea "Single-file installer" --status seed --parent P1 idea_type=tool addresses=B1 uses=F1
wayfind ask "Ship on PyPI or GitHub only?" --options "PyPI|GitHub only" --recommend PyPI --blocks I1
wayfind frontier
wayfind open                # the live page, in the background: answer the question there
wayfind context             # what an agent reads: the answer shows up as "decided"

With Claude Code

Install the plugin. It needs python3 but no pip install:

/plugin marketplace add tianyi-zhang-02/wayfind
/plugin install wayfind@wayfind

The plugin adds three things:

• a session-start hook that briefs Claude whenever the project has a memory;

• a wayfind skill with the model and the working loop;

• MCP tools: context, frontier, show, search, run.

If you have installed the CLI and prefer not to use the plugin, run wayfind setup claude instead. It writes the skill, the hook, and a block in CLAUDE.md.

With Codex

wayfind setup codex                     # skill in .agents/skills, hook in .codex/hooks.json, block in AGENTS.md
codex mcp add wayfind -- wayfind mcp    # optional: the same MCP tools

Codex asks you once, in /hooks, to review and trust the new hook.

With any other agent

Run wayfind agents --install AGENTS.md, or point any MCP client at wayfind mcp. Every command also has a --json form for scripts.

wayfind --dir path/to/.wayfind mcp binds the server to that one memory, whatever directory the client starts in, and a call cannot point it elsewhere. The context tool takes an optional scope to read one card and the work under it; a scoped read changes nothing and marks nothing as seen.

The model

Every card has a one-line summary and a rough design, and may also carry content, next (the next concrete action), and evidence (what has been observed so far).

Edges:

• parents builds the trees.

• addresses points from an idea or project to the needs it serves.

• uses points to assets.

• depends_on points to decisions.

Lifecycle is separate from status. A card is live, archived, or pruned, and any move out of live needs a reason.

Sources:

• Each source is registered once, with who checked it and how deeply (full text, partial, or abstract).

• Cards cite sources by key.

• arXiv IDs and doi: keys become links.

Custom vocabulary: you can change the idea types, score keys, and depth labels in meta.schema.

Commands

Set WAYFIND_ACTOR, or pass --actor, so the changelog records who changed what and each agent's briefing knows what it has already seen.

Files

.wayfind/
  cards/<id>.json   one file per card (change them with the CLI, not by hand)
  meta.json         title, method, and vocabulary
  sources.json      checked sources
  changelog.jsonl   one line per write: date, actor, action, and old and new values
  notes.jsonl       notes left on the live map
  seen.json         where each agent last looked, for "what changed since" (git-ignored)
  site/             index.html and OUTLINE.md from `wayfind build` (git-ignored)

Memories made before v0.3 keep a single wayfind.json. They still work; wayfind migrate converts them to one file per card.

Design choices

• Standard library only. Every write is validated, and each file is saved atomically. Only the cards that changed are rewritten.

• Several agents at once.

  • On one machine: every write (load, change, save, log) runs under a lock, so Claude and Codex queue up instead of overwriting each other. A test runs two processes writing at the same time and checks that nothing is lost.

  • Across git branches: edits to different cards merge cleanly, and the changelog and notes use git's union merge so that both sides' lines are kept. Two branches that add a card at the same time get the same id, and git reports it as a conflict rather than losing either card.

• Offline map. The page is a single HTML file that loads nothing from the network.

• Loopback only. The page's server (wayfind open or serve) listens on 127.0.0.1. It rejects requests with a foreign Host header, and it accepts notes, answers, and edits only from same-origin requests that carry a custom header. open keeps its list of workstreams and the page's port in ~/.wayfind (or $WAYFIND_HOME). The page serves only the memories on that list, and it names them by id, never by path.

• Short briefings. The briefing packs sections in priority order into a budget; no section may take more than 35% of it; anything left out is named, with the command that shows it. The session hook stays silent in projects without a memory.

• The owner decides. Agents record questions with ask; answers come from the owner, on the map or in chat.

Related work

wayfind is small and meant to sit alongside these, not replace them:

• Memory for language agents:

  • MemGPT pages memory in and out of a limited context.

  • Generative Agents store and retrieve a stream of memories.

  • Reflexion keeps verbal self-feedback between trials.

  • Voyager grows a library of skills with an automatic curriculum.

• Task tools for coding agents:

  • Beads keeps a dependency-aware task graph as agent memory.

  • Taskmaster turns a requirements document into tasks.

  • Backlog.md keeps tasks as Markdown, with a Kanban view.

What wayfind adds is the backward tree of needs, the forward tree of assets, and a frontier that says what to expand and what to cut.

This repository's own memory

.wayfind/ holds wayfind's own roadmap, including the ideas tried and set aside. Run wayfind context in a clone to see it.

License

MIT. The ghost is from GrafxKid's Sprite Pack 4, released under CC0 1.0.