# Isolated Pi instance

This directory is the user/config directory for an isolated [Pi coding agent](https://pi.dev) instance. The `launch` script sets `PI_CODING_AGENT_DIR` to this directory before invoking the installed `pi` executable.

## Start Pi

Install the memory extension's pinned YAML parser after cloning:

```bash
npm ci --prefix extensions/memory
```

Then start from this directory:

```bash
./launch
```

The launcher is relocatable and can be called while working in another project:

```bash
/path/to/kimiko-agent/launch
```

Pi keeps that project's working directory while storing this instance's credentials, settings, sessions, packages, and global resources here. The launcher also passes `--no-builtin-tools`, so Pi starts without the built-in `read`, `bash`, `edit`, or `write` tools while retaining tools registered by extensions.

To use the environment variable directly instead:

```bash
export PI_CODING_AGENT_DIR="$(pwd -P)"
pi
```

To make the setting directory-local with `direnv`, create an untracked `.envrc` containing:

```bash
export PI_CODING_AGENT_DIR="$PWD"
```

## Authenticate and configure

```text
/login       Manage credentials; writes auth.json here
/settings    Change common settings
/model       Select a model
```

Or use provider API-key environment variables before starting Pi. `auth.json`, trust decisions, sessions, generated model metadata, and installed package contents are intentionally ignored by Git.

## Layout

- `settings.json` — instance-wide Pi settings
- `models.json` — custom providers/models
- `keybindings.json` — keybinding overrides
- `extensions/` — global extensions for this instance, including deterministic OKF memory tools
- `skills/` — global skills for this instance, including progressively disclosed memory guidance
- `memory/` — the human-readable OKF long-term-memory bundle
- `prompts/` — global prompt templates for this instance
- `themes/` — global themes for this instance
- `sessions/` — generated conversation history
- `npm/`, `git/` — Pi-managed package installations
- `auth.json` — generated credentials (secret; never commit)
- `trust.json` — generated project trust decisions

Install a package into only this instance by using the launcher:

```bash
./launch install npm:<package>
./launch list
```

## Long-term memory

Kimiko stores durable memory as an OKF v0.1 bundle in `memory/`. It is ignored by Git by default because it may contain personal data; remove that ignore rule only after choosing an explicit private backup/versioning policy. Each user turn resets detailed memory tools. Explicit memory language reveals them for that turn so the model can see the capability; otherwise `memory_search` progressively enables them. Conservative metadata hints may be added to that turn's system prompt, but are never written to session history and disappear on the next turn. Existing concepts cannot be updated or forgotten until they have been returned by search and read in the same turn. The extension owns frontmatter, timestamps, path validation, generated indexes, logs, locking, atomic writes, verification, repair, and one retry. The model supplies only semantic content.

```text
/memory-path             Show the bundle location
/memory-check            Validate without changing concepts
/memory-check --repair   Repair structure and regenerate indexes
```

Run the deterministic store tests with:

```bash
npm test --prefix extensions/memory
```

See [`docs/memory-design.md`](docs/memory-design.md) for scope, tradeoffs, and staged production improvements.

## Isolation boundary

`PI_CODING_AGENT_DIR` isolates Pi's user config, credentials, sessions, model config, and managed packages from `~/.pi/agent`. It is not an OS sandbox. Pi can still use inherited environment variables and shell/user configuration, and—when trusted—load project-local `.pi` resources. Pi also discovers the cross-agent global skill location `~/.agents/skills`; use `--no-skills` when you need to suppress all automatic skill discovery for a run.