<p align="center">
  <img src="docs/mascot.png" width="126" alt="wayfind's pixel ghost: a small round white ghost with rosy cheeks">
</p>

<h1 align="center">wayfind</h1>

<p align="center">
  <b>A plan your agents can read, and a memory they keep up to date.</b><br>
  <sub>Agents come and go; the memory stays, like a friendly ghost in the repository.</sub>
</p>

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:

| | Agents get | You get |
|---|---|---|
| **Start of a session** | a briefing within a character budget: corrections, open decisions, what changed since *this agent* last looked, active work | the **Map**: goal, needs, projects, what can be built, what exists |
| **One piece of work** | `context --scope P3`: that card and the work under it, the owner's steering that applies there, blockers, and what the packet leaves out | a project's own Map, with its **open work** one click away |
| **The whole plan** | `outline`: the hierarchy, folded, with counts | the **Overview**: goals and the projects that reach them |
| **What happened** | `digest` and `history`: one line per kind of change | **Since you last looked**, at the top of the page, and each card's full history in its drawer |
| **High-level choices** | `ask` a question with options, then wait | **Waiting on you** at the top; answer on the page with one click |
| **Writing back** | CLI or MCP; every write validated and logged with old and new values | answers, notes, next steps, statuses and new tasks from the page, written to the same memory |

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 on opening: your workstreams in the sidebar, what happened since you last looked, what waits on you, the open work, and the Map](docs/map.png)

## 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.

![A project's Map with its open work, and a task open for editing](docs/project.png)

![The Overview: goals and the projects that reach them](docs/plan.png)

## 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.

![A question for the owner, answered on the page](docs/decision.png)

## Install

wayfind needs Python 3.9 or newer and nothing else.

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

## Quick start

```bash
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:

```text
/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

```bash
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).

| kind | id | statuses | role |
|---|---|---|---|
| goal | `T.A` | selected, proposed, alternative | the end target |
| topic | `B1`, `B1.2` | open, partial, occupied | backward tree: what the goal needs; status says how much the world already covers |
| asset | `F1` | have, building | forward tree: what exists; with `uses`, what can be built from it |
| idea | `I1` | seed, exploring, adopted, parked, rejected | a candidate step, with an `idea_type` and 1–3 `scores`; `adopted` means done |
| project | `P1` | active, planned, idea, parked, done | a body of work; its ideas point to it with `parents` |
| decision | `D1` | pending, deferred, decided | what only the owner can settle |
| lesson | `K1` | correction, insight | a corrected belief or a hard-won insight |

**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

| | |
|---|---|
| `init`, `context`, `frontier`, `doctor` | start (`--profile study` for a study memory), brief (`--budget`, default 6000 characters), steer, tidy |
| `context --scope ID`, `outline` | read one card and the work under it; the roadmap as a folded outline (`--scope`, `--depth`) |
| `digest`, `history` | what changed (`--since last`, `7d`, or a date); one card's timeline |
| `ask`, `decide` | agents ask the owner with options; the owner's answer is recorded |
| `list`, `show`, `search`, `stats`, `log` | read (`--json` where useful); `list --parent ID` lists a card's children |
| `add`, `set`, `link`, `unlink` | write; `set` takes `key=value`, `key+=a,b`, `key-=a`, `key:=<json>`, `scores.impact=3` |
| `archive`, `prune`, `restore`, `merge` | lifecycle, always with a reason; `merge` rewires live edges |
| `source`, `cite` | register a checked source; attach it to a card |
| `notes`, `resolve` | read and close the notes you leave on the map |
| `review`, `check`, `today`, `routine`, `export` | study memories: a result on a step schedules its re-do; a check on a knowledge point schedules the next check; the day's steps; minutes per track; the plan as JSON |
| `tidy` | set aside finished work untouched for two weeks (archived with a dated reason, never deleted); list what needs an agent's judgment (`--check` lists only) |
| `open`, `serve`, `build` | open the live page with your other workstreams beside it, reusing a running one or starting it in the background (`--stop` stops it); serve one memory in the foreground; write `OUTLINE.md` and a static page |
| `mcp`, `hook`, `setup`, `agents` | agent integrations |
| `status`, `nodes`, `pull`, `conflicts`, `dashboard` | experimental: a read-only hub over several memories |

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

```text
.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](https://arxiv.org/abs/2310.08560) pages memory in and out of a
    limited context.
  - [Generative Agents](https://arxiv.org/abs/2304.03442) store and retrieve a
    stream of memories.
  - [Reflexion](https://arxiv.org/abs/2303.11366) keeps verbal self-feedback
    between trials.
  - [Voyager](https://arxiv.org/abs/2305.16291) grows a library of skills with
    an automatic curriculum.
- **Task tools for coding agents:**
  - [Beads](https://github.com/gastownhall/beads) keeps a dependency-aware task
    graph as agent memory.
  - [Taskmaster](https://github.com/eyaltoledano/claude-task-master) turns a
    requirements document into tasks.
  - [Backlog.md](https://github.com/MrLesk/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](https://grafxkid.itch.io/sprite-pack-4), released
under CC0 1.0.