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.

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:

pi install npm:pi-weave

Other install sources:

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:

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:

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.

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

/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, 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.

The browser is read-only. Edit with $EDITOR, Obsidian, or the weave_note tool; unknown front-matter fields remain preserved.

/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

/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 <repo>/.okf/ is missing, fresh, or stale.

/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:

~/.okf/
└── notes/
    ├── authentication-migration.md
    └── release-plan.md

A note has small YAML front matter followed by 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
<!-- NEVER edit below this line. Verbatim user input preserved here. -->

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

npm install
npm run check

Useful individual commands:

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 before contributing. Work on a feature branch; do not commit directly to main.

More detail

• Design — product and architecture
• Notepad skill — capture, narration, and provenance behavior
• Link repair reference — how stale links resolve, and what repair will not do
• Historical browser workspace notes — superseded implementation record
• Repository exploration skill — how Pi uses the index

License

MIT