pi-para

PARA Knowledge Base Extension for pi — persistent, LLM-curated personal wiki

Packages

Package details

extensionskill

Install pi-para from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-para
Package
pi-para
Version
0.7.0
Published
Jul 19, 2026
Downloads
1,277/mo · 1,256/wk
Author
picassio
License
MIT
Types
extension, skill
Size
1.2 MB
Dependencies
4 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-para

A pi extension that maintains a persistent, LLM-curated personal knowledge base structured by the PARA method — Projects, Areas, Resources, Archives.

pi-para runs as a normal Pi extension: no required daemon, no systemd, and no global QMD CLI. Search/indexing uses the embedded QMD SDK, and background capture/maintenance is coordinated by an in-process scheduler while Pi is open.

Install

pi install npm:pi-para
# or, for npm/npx setup flows:
npx pi-para@latest setup

POSIX one-liner:

curl -fsSL https://raw.githubusercontent.com/picassio/pi-para/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/picassio/pi-para/main/scripts/install.ps1 | iex

Restart Pi after installing or changing extension registration.

Then run diagnostics:

npx -y pi-para@latest doctor

The pi-para command is only on your PATH after a global install (npm install -g pi-para). After pi install npm:pi-para or an npx setup, invoke the CLI with npx -y pi-para@latest <command> instead.

What pi-para creates

Default user files:

~/.pi/para/config.jsonc       # canonical pi-para config
~/.pi/para/secrets.json       # optional local secrets, chmod 0600
~/.pi/wiki/                   # PARA markdown wiki
~/.pi/wiki/.pi-para.sqlite    # scheduler queue/history/leases
~/.pi/wiki/.qmd.sqlite        # QMD SDK search index

Legacy files such as ~/.pi/wiki/config.json and ~/.config/qmd/index.yml are still read for migration/compatibility.

Core commands

Pi slash commands

Command Description
/wiki Wiki status, current scope, page counts, recent log
/wiki-search <query> Search the wiki
/wiki-ingest <url-or-path-or-text> Ingest a source into raw/ and synthesize pages
/wiki-capture [topic] Queue/capture current session knowledge
/wiki-scope [scope] Show or override current project scope
/wiki-lint [--report-only] Run wiki health checks
/wiki-summarize [target] Summarize a page/category/all
/wiki-settings Interactive settings for config/providers/scheduler
/wiki-scheduler [status|queue|history|capture-history] Scheduler/capture observability
/wiki-migrate Batch-migrate pages to current schema
/wiki-project <name> <goal> Create/archive project pages

CLI

Run these as pi-para <command> (global install) or npx -y pi-para@latest <command>:

pi-para setup [--yes] [--dry-run] [--local PATH]
pi-para doctor [--fix] [--json] [--test-capture-model]
pi-para tasks [--status queued|running|done|failed]
pi-para tasks show <id>
pi-para tasks history [--task NAME] [--limit N]
pi-para tasks retry [--task NAME]
pi-para status [--json]
pi-para capture-recent --hours 24
pi-para providers
pi-para providers set-secret <name> <value>
pi-para providers remove-secret <name>

The pi-para-daemon binary name is retained only to print migration guidance; its legacy commands were removed in 0.7.

Tools available to agents

Tool Description
wiki_ingest Ingest URL/file/text into the wiki
wiki_query Search with scope/category/freshness context
wiki_edit Atomic exact oldText → newText page edits
wiki_write Create/append/replace pages, or legacy edit mode
wiki_read Read a page with freshness indicator
wiki_move Move a page between PARA categories
wiki_lint Run health checks and optional autofix
wiki_migrate Batch-migrate pages to current schema
wiki_summarize Summarize pages/categories/all

Prefer wiki_edit for surgical updates to existing pages.

Configuration

Use /wiki-settings or edit:

~/.pi/para/config.jsonc

Credential refs use one of:

pi-auth:<provider>   # Persisted Pi auth, e.g. ~/.pi/agent/auth.json
secret:<name>        # ~/.pi/para/secrets.json
none                 # local/no-auth provider

Setup does not require or write API-key environment variables.

See CONFIGURATION.md for the full schema.

Search and QMD

QMD is used as an embedded SDK through qmd-engine; users do not need to install a global qmd CLI.

  • BM25 keyword search works immediately.
  • Embedding/rerank can be configured in /wiki-settings or ~/.pi/para/config.jsonc.
  • Legacy ~/.config/qmd/index.yml is only a compatibility fallback.

Background capture and maintenance

When Pi is running, pi-para starts an in-process scheduler. It handles:

  • queued session capture,
  • startup catch-up from .completed-sessions,
  • index/search maintenance,
  • queue/history/lease tracking in .pi-para.sqlite.

No background OS service is required. If Pi is closed, queued work resumes on the next Pi session.

Obsidian compatibility

The wiki is plain markdown with YAML frontmatter and [[wikilinks]]. You can open ~/.pi/wiki/ as an Obsidian vault.

Development

git clone https://github.com/picassio/pi-para.git
cd pi-para
npm install
npm run check
npm test
npm run test:coverage
npm run build
npm run smoke:install

# Local setup into Pi settings
node ./dist/cli.js setup --local .

More docs:

License

MIT