pi-weave

A local knowledge workspace you can talk to.

pi-weave is an extension for pi. Ask Pi to take notes while you think out loud, keep your exact words alongside a useful summary, and explore everything in /weave-view.

It also understands the repository you are working in. Personal notes live in a Markdown vault; repository knowledge lives in a disposable .okf index. Both are plain files that humans and agents can read.

Core capabilities

• Conversational note-taking. Create and update notes through natural-language requests such as “start a note”, “add this”, or “remember that”.
• Verbatim narration with structured summaries. During dictation, Pi preserves each spoken passage in an append-only ## Raw section while maintaining an organized summary above it.
• Knowledge retrieval. Pi searches existing notes when answering questions about previous decisions, people, projects, or meetings.
• Unified visual workspace. /weave-view presents notes, links, repository structure, and provenance in a live browser interface.
• Repository exploration. A lightweight, git-aware index gives Pi a structural overview of the current codebase before it reads files.

Nothing is captured silently. pi-weave creates or extends a personal note only when you ask it to.

Install

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.

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

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

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-cancel	Stop a deep 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 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
• Historical browser workspace notes — superseded implementation record
• Repository exploration skill — how Pi uses the index

License

MIT