shog-lab-pi-toolkit

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-mind

**Give your coding agent a memory that survives across sessions — inspectable as plain markdown in your repo.**

> v0.15.1 · 345 tests passing · dogfooded on this repo · MIT

A monorepo of capability packages for [pi](https://github.com/earendil-works/pi) (the coding-agent runtime). pi-mind turns any repo into a persistent, inspectable knowledge store: the agent writes memories as markdown files with YAML frontmatter, retrieves them by relevance, and never changes future behavior without explicit user approval; memory writes happen as visible explicit tool calls.

## What you get

- **Persistent, inspectable memory.** Knowledge is just `.pi-mind/knowledge/*.md` files with frontmatter. `git diff` shows what your agent remembered. No opaque vector store you can't read.
- **Hybrid retrieval.** FTS5 keyword search + vector similarity (Ollama `nomic-embed-text`) + a SQLite-backed knowledge graph (entities and triples), merged per turn. The agent only sees what's relevant to the current task.
- **Passive by design.** No background curator, no autonomous LLM loops writing on your behalf. Every `remember_this` and `observe` is an explicit tool call in a visible turn. Memory-audit flags issues; humans fix them.
- **Ask-first skill authoring.** Agent proposes new skills with `create_skill`; you approve before the file is written. Skills change future behavior, so the agent proposes and you decide.
- **No required daemon.** Pure Node + SQLite. Ollama is optional for vector search; FTS5 keyword search works without it. No cron jobs required (an optional cron snippet is documented for scheduled audit).

## 30-second demo

```text
# Session 1
$ cd ~/my-repo && pi
pi> remember this: I prefer ripgrep over grep for code search
pi> /exit

# Session 2 (any day, same repo checkout — the agent reads from .pi-mind/)
$ cd ~/my-repo && pi
pi> what search tool do I prefer?
→ "ripgrep — see .pi-mind/knowledge/<date>-…md"
```

The "memory" is the same `.md` file you can `cat`, `grep`, and commit. No magic, no cloud lock-in.

## Quickstart

```bash
# 1. Install the pi runtime (one-time, global). GitHub: github.com/earendil-works/pi.
npm i -g @earendil-works/pi-coding-agent

# 2. Add memory + ask-first skills to your repo (project-local pi package)
cd ~/my-repo
pi install -l npm:@shog-lab/pi-memory
```

`pi install -l` records the package in `.pi/settings.json`; pi installs/loads it on startup without modifying your repo `package.json`. The memory directories under `.pi-mind/` are created lazily on first launch/write.

Node package-manager install is still supported for repos that prefer explicit dev dependencies:

```bash
npm i -D @shog-lab/pi-memory
```

With npm, `postinstall` wires `.pi/` and `.pi-mind/` automatically. With pnpm, lifecycle scripts may be blocked; run the package init explicitly:

```bash
pnpm add -D @shog-lab/pi-memory
INIT_CWD="$PWD" pnpm exec pi-mind-init
```

Current note: `@shog-lab/pi-memory@0.14.x` still uses `better-sqlite3` for SQLite/FTS5/KG indexing. pnpm may require approving/rebuilding that native dependency (`pnpm approve-builds` then `pnpm rebuild better-sqlite3`) until the SQLite backend migrates to Node's built-in `node:sqlite`.

Fallback if `pnpm exec` cannot resolve the bin:

```bash
INIT_CWD="$PWD" node node_modules/@shog-lab/pi-memory/bin/init.js
```

Verify the loop:

```bash
# Launch pi, ask it to remember something, exit
pi
> remember this: I prefer ripgrep over grep
> /exit

# Relaunch and ask it back — same answer, no re-prompting
pi
> what search tool do I prefer?
```

## What's in this monorepo

**Main package — install this for the headline features:**

- [`@shog-lab/pi-memory`](https://github.com/shog-lab/pi-mind/tree/HEAD/packages/memory/) — persistent memory (FTS5 + vector + KG) and ask-first skill authoring. The one most users want.

**Optional add-ons (compose with core, install only what you need):**

- [`@shog-lab/pi-toolkit`](https://github.com/shog-lab/pi-mind/tree/HEAD/packages/toolkit/) — drop-in LLM tools: web search and MCP server bridge.
- [`@shog-lab/pi-subagent`](https://github.com/shog-lab/pi-mind/tree/HEAD/packages/subagent/) — spawn focused child pi for scoped subtasks with a clean context.
- [`@shog-lab/pi-bus`](https://github.com/shog-lab/pi-mind/tree/HEAD/packages/bus/) — inter-pi messaging and cron triggers: open multiple `pi` windows on the same repo, they auto-join a shared bus.

**Internal (don't install directly):**

- [`@shog-lab/pi-utils`](https://github.com/shog-lab/pi-mind/tree/HEAD/packages/utils/) — shared helpers (process spawn, git-aware path resolution) depended on by the other packages.

Each package has its own README with install + usage details. All publish under the `@shog-lab` scope.

## Develop

```bash
git clone https://github.com/shog-lab/pi-mind.git
cd pi-mind
npm install   # installs all workspaces + postinstall → .pi/ symlinks
npm run build
npm test
```

The monorepo dogfoods itself: running `pi` here loads memory + toolkit + bus + subagent on the codebase that built them.

## Design

See [AGENTS.md](https://github.com/shog-lab/pi-mind/blob/HEAD/AGENTS.md#design-principles) for the human-in-the-loop autonomy principles that govern this monorepo (memory is passive; behavior changes propose-before-they-act; the trigger chain for any state mutation must originate with a user message).

## History

Older autonomous-loop (`pi-goals`) and browser-runtime (`packages/chrome`) packages were removed. Package READMEs and git history carry the migration details.

## License

MIT

pi-mind

Give your coding agent a memory that survives across sessions — inspectable as plain markdown in your repo.

v0.15.1 · 345 tests passing · dogfooded on this repo · MIT

A monorepo of capability packages for pi (the coding-agent runtime). pi-mind turns any repo into a persistent, inspectable knowledge store: the agent writes memories as markdown files with YAML frontmatter, retrieves them by relevance, and never changes future behavior without explicit user approval; memory writes happen as visible explicit tool calls.

What you get

Persistent, inspectable memory. Knowledge is just .pi-mind/knowledge/*.md files with frontmatter. git diff shows what your agent remembered. No opaque vector store you can't read.
Hybrid retrieval. FTS5 keyword search + vector similarity (Ollama nomic-embed-text) + a SQLite-backed knowledge graph (entities and triples), merged per turn. The agent only sees what's relevant to the current task.
Passive by design. No background curator, no autonomous LLM loops writing on your behalf. Every remember_this and observe is an explicit tool call in a visible turn. Memory-audit flags issues; humans fix them.
Ask-first skill authoring. Agent proposes new skills with create_skill; you approve before the file is written. Skills change future behavior, so the agent proposes and you decide.
No required daemon. Pure Node + SQLite. Ollama is optional for vector search; FTS5 keyword search works without it. No cron jobs required (an optional cron snippet is documented for scheduled audit).

30-second demo

# Session 1
$ cd ~/my-repo && pi
pi> remember this: I prefer ripgrep over grep for code search
pi> /exit

# Session 2 (any day, same repo checkout — the agent reads from .pi-mind/)
$ cd ~/my-repo && pi
pi> what search tool do I prefer?
→ "ripgrep — see .pi-mind/knowledge/<date>-…md"

The "memory" is the same .md file you can cat, grep, and commit. No magic, no cloud lock-in.

Quickstart

# 1. Install the pi runtime (one-time, global). GitHub: github.com/earendil-works/pi.
npm i -g @earendil-works/pi-coding-agent

# 2. Add memory + ask-first skills to your repo (project-local pi package)
cd ~/my-repo
pi install -l npm:@shog-lab/pi-memory

pi install -l records the package in .pi/settings.json; pi installs/loads it on startup without modifying your repo package.json. The memory directories under .pi-mind/ are created lazily on first launch/write.

Node package-manager install is still supported for repos that prefer explicit dev dependencies:

npm i -D @shog-lab/pi-memory

With npm, postinstall wires .pi/ and .pi-mind/ automatically. With pnpm, lifecycle scripts may be blocked; run the package init explicitly:

pnpm add -D @shog-lab/pi-memory
INIT_CWD="$PWD" pnpm exec pi-mind-init

Current note: @shog-lab/pi-memory@0.14.x still uses better-sqlite3 for SQLite/FTS5/KG indexing. pnpm may require approving/rebuilding that native dependency (pnpm approve-builds then pnpm rebuild better-sqlite3) until the SQLite backend migrates to Node's built-in node:sqlite.

Fallback if pnpm exec cannot resolve the bin:

INIT_CWD="$PWD" node node_modules/@shog-lab/pi-memory/bin/init.js

Verify the loop:

# Launch pi, ask it to remember something, exit
pi
> remember this: I prefer ripgrep over grep
> /exit

# Relaunch and ask it back — same answer, no re-prompting
pi
> what search tool do I prefer?

What's in this monorepo

Main package — install this for the headline features:

@shog-lab/pi-memory — persistent memory (FTS5 + vector + KG) and ask-first skill authoring. The one most users want.

Optional add-ons (compose with core, install only what you need):

@shog-lab/pi-toolkit — drop-in LLM tools: web search and MCP server bridge.
@shog-lab/pi-subagent — spawn focused child pi for scoped subtasks with a clean context.
@shog-lab/pi-bus — inter-pi messaging and cron triggers: open multiple pi windows on the same repo, they auto-join a shared bus.

Internal (don't install directly):

@shog-lab/pi-utils — shared helpers (process spawn, git-aware path resolution) depended on by the other packages.

Each package has its own README with install + usage details. All publish under the @shog-lab scope.

Develop

git clone https://github.com/shog-lab/pi-mind.git
cd pi-mind
npm install   # installs all workspaces + postinstall → .pi/ symlinks
npm run build
npm test

The monorepo dogfoods itself: running pi here loads memory + toolkit + bus + subagent on the codebase that built them.

Design

See AGENTS.md for the human-in-the-loop autonomy principles that govern this monorepo (memory is passive; behavior changes propose-before-they-act; the trigger chain for any state mutation must originate with a user message).

History

Older autonomous-loop (pi-goals) and browser-runtime (packages/chrome) packages were removed. Package READMEs and git history carry the migration details.

License

MIT