# pi-weave
**Your notes. Your agent's notes. One searchable knowledge workspace.**
I've been chasing the right note-taking workflow for years. Notion, OneNote, Obsidian, and plenty of others.
With pi-weave, I've made one that finally answers the way I want to work today — especially now that AI agents are part of that work.
The idea is simple:
**You and your agent should share the same knowledge.**
Talk naturally and let your thoughts become structured notes. Write notes yourself. Let your agent capture decisions, discoveries, and
useful context. Bring important knowledge forward from previous sessions.
Then find it again — by searching the workspace yourself, or simply asking your agent.
Everything is local. Everything is readable. Your notes are ordinary files, not knowledge trapped inside another chat.
## Think out loud
Dictation is one of my favorite ways to use AI.
Instead of stopping to organize every thought while I'm having it, I can just talk:
> Start a note about pi-weave positioning. I'm going to think out loud.
pi-weave keeps what I actually said while Pi continuously turns it into a useful, structured note.
The raw thought stays yours. The organization is handled for you.
And it doesn't end with human notes.
## Your knowledge + your agent's knowledge
pi-weave gives humans and agents one workspace.
A note you dictate, something you write manually, a useful discovery made by an agent, or knowledge recovered from an earlier session can
all live together.
pi-weave keeps track of where knowledge came from, while making the whole workspace searchable by both you and your agent.
**The conversation can end. The knowledge doesn't have to.**
## Built on Pi
pi-weave is built as an extension for [Pi](https://github.com/earendil-works/pi).
I've grown to love Pi precisely because it is such a lightweight agent harness. It gives the model tools and context without trying to
become the product itself, and its extensibility makes projects like pi-weave possible.
Install pi-weave:
```bash
pi install npm:pi-weave
```
Other install sources:
```bash
pi install git:github.com/EranYonai/pi-weave
pi install /path/to/pi-weave
```
Requires Node **20.13 or newer**.
Then just talk to Pi.
## Start taking notes
Talk to Pi normally:
```text
You: Start a note called Authentication migration.
You: We probably want OIDC next quarter, but existing JWT clients need
a compatibility window.
You: Add that the gateway team owns the migration plan.
You: What open questions are in this note?
```
For live narration or interview notes, tell Pi that you are dictating:
```text
You: Start a note for this interview. I’m going to narrate; keep my words
verbatim and organize the note as we go.
```
For each chunk, Pi:
1. appends your words unchanged to the note’s `## Raw` tail;
2. refreshes the structured summary above it;
3. leaves the raw record untouched.
This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation
remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
Useful requests include:
| Say this | What happens |
|---|---|
| “Start a note about…” | Creates a Markdown note in the vault |
| “Add this to the … note” | Finds the existing note and appends to it |
| “Clean up” or “finalize this note” | Reorganizes the readable body and preserves the raw tail |
| “What did we decide about…?” | Searches the vault, then reads the relevant notes |
| “Remember that…” | Stores durable knowledge for a future session |
| “Fix the broken links” | Audits and repairs stale `[[wiki-links]]` deterministically |
## Keeping the vault connected
A wiki-link resolves to nothing when it is written as a bare title — `[[Quarterly Roadmap]]` when the note lives at `planning/roadmap-2026`
— or when it points at a note that was never written. Pi repairs those in one deterministic pass instead of rereading the vault and
guessing.
```text
You: Check the links in my notes.
You: Fix the ones you're sure about.
```
A target resolves by exact slug, then unique basename, then unique title — each rule requiring **exactly one** candidate. Ambiguous links
are reported with their candidates and never guessed; links to notes that were never written are listed, never invented. Repairs preserve
the alias, so the visible text does not change, and never touch the `## Raw` tail or code fences.
Renaming or moving a note rewrites its inbound links automatically, so its backlinks stay intact.
## `/weave-view`
```bash
/weave-view # open the browser workspace
/weave-view --no-open # start it and print the URL
/weave-view tui # terminal UI for SSH or browser-free use
```
The browser workspace has four connected views:
- **Tree** — notes, folders, and repository structure, with text and provenance filters.
- **Note** — rendered Markdown with clickable `[[wikilinks]]`, link previews, tags, authorship, click-to-edit, and an action to open the
source in `$EDITOR`.
- **Graph** — a navigable map of notes, links, mentions, modules, and repository relationships. Selecting something updates every view.
- **Context** — links, backlinks, tags, and code mentions for the current selection.
Search with `⌘K` / `Ctrl K`. Press `?` for all shortcuts. The workspace updates as notes change on disk, so a note written by Pi appears
without a reload. It follows the system theme by default and can be switched between light and dark.
**Click the note text to edit it** — the prose swaps for its Markdown source; `⌘S` / `Ctrl S` saves, `Esc` or **Done** closes. Selecting
text to copy and clicking a `[[wikilink]]` do what they always did; neither opens the editor. A save rewrites the body and nothing
else — unknown front-matter fields, key order, and the append-only `## Raw` tail of a dictated note all survive untouched, so a note edited
here and a note edited in Obsidian stay byte-compatible. Editing with `$EDITOR`, Obsidian, or the `weave_note` tool works as before; the
last writer wins, and the workspace picks up outside changes within a couple of seconds.
`/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
## Remember past pi sessions
```bash
/weave-scan sessions # pi history (default)
/weave-scan sessions /path/to/history # explicit history root
```
This opt-in scan treats a supplied file—or every bounded text file under a supplied directory—as opaque session material for the active
model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. That makes it usable with Claude Code, opencode, Codex, or
exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable technical
takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
## Repository knowledge
Inside a Git repository, pi-weave detects whether `/.okf/` is missing, fresh, or stale.
```bash
/weave-scan # fast structural index
/weave-scan deep # also summarize changed files with the active model
```
The light index covers languages, packages, modules, entry points, and Git state. A deep scan adds short per-file summaries and only
revisits files whose content changed.
The repository index is a cache, not a source of truth. Delete `.okf`, scan again, and nothing important is lost. pi-weave excludes it
locally from Git by default.
## Commands and tools
Most people only need natural language and `/weave-view`.
| Surface | Name | Purpose |
|---|---|---|
| Command | `/weave-view` | Open the browser or terminal workspace |
| Command | `/weave` | Show vault and repository status |
| Command | `/weave-scan` | Build or refresh the repository index |
| Command | `/weave-scan deep` | Add incremental model-written file summaries |
| Command | `/weave-scan sessions [path]` | Turn changed session-history files into durable memory notes |
| Command | `/weave-scan-cancel` | Stop a deep or session scan |
| Tool | `weave_note` | List, read, add, append, finalize, and search notes |
| Tool | `weave_repo` | Check, scan, and summarize the repository index |
The included `weave-notepad` and `weave-explore` skills teach Pi when and how to use these tools.
## Files, privacy, and portability
Personal notes are ordinary Markdown files:
```text
~/.okf/
└── notes/
├── authentication-migration.md
└── release-plan.md
```
A note has small YAML front matter followed by Markdown:
````markdown
---
title: Authentication migration
created: 2026-08-22T09:00:00.000Z
updated: 2026-08-22T09:30:00.000Z
tags: [auth, security]
source: human
---
## Summary
Move toward OIDC while keeping a JWT compatibility window.
---
## Raw
```
We probably want OIDC next quarter…
```
````
Set `PI_WEAVE_VAULT` to use a different vault location.
Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to
whichever model you configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi
session.
The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no pi-specific imports.
## Development
```bash
npm install
npm run check
```
Useful individual commands:
```bash
npm run typecheck
npm test
npm run coverage
npm run build:web
```
Coverage must remain at or above **95%** for lines, branches, functions, and statements. If browser source changes, rebuild and commit
`src/web/client/dist/app.js`.
Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do not commit directly to `main`.
## More detail
- [Design](docs/design.md) — product and architecture
- [Notepad skill](skills/weave-notepad/SKILL.md) — capture, narration, and provenance behavior
- [Link repair reference](skills/weave-notepad/references/link-repair.md) — how stale links resolve, and what repair will not do
- [Historical browser workspace notes](docs/weave-workspace.md) — superseded implementation record
- [Repository exploration skill](skills/weave-explore/SKILL.md) — how Pi uses the index
## License
[MIT](LICENSE)