---
slug: "pi-para"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/picassio/pi-para@main/README.md"
repo: "https://github.com/picassio/pi-para"
source_file: "README.md"
branch: "main"
---
# pi-para

A [pi](https://github.com/badlogic/pi-mono) extension that maintains a persistent, LLM-curated personal knowledge base structured by the [PARA method](https://fortelabs.com/blog/para/) — 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

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

POSIX one-liner:

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

Windows PowerShell:

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

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

```text
~/.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>`:

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

```text
~/.pi/para/config.jsonc
```

Credential refs use one of:

```text
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](https://github.com/picassio/pi-para/blob/HEAD/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

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

- [SETUP.md](https://github.com/picassio/pi-para/blob/HEAD/SETUP.md)
- [ARCHITECTURE.md](https://github.com/picassio/pi-para/blob/HEAD/ARCHITECTURE.md)
- [STRUCTURE.md](https://github.com/picassio/pi-para/blob/HEAD/STRUCTURE.md)
- [CONFIGURATION.md](https://github.com/picassio/pi-para/blob/HEAD/CONFIGURATION.md)

## License

MIT