kimiko-agent/README.md

Isolated Pi instance

This directory is the user/config directory for an isolated Pi coding agent 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:

npm ci --prefix extensions/memory

Then start from this directory:

./launch

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

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

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

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

export PI_CODING_AGENT_DIR="$PWD"

Authenticate and configure

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

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

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

npm test --prefix extensions/memory

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