@0xkobold/pi-persona

Scope-aware persona management for pi agents.

Global persona = who the agent IS. Project persona = situational augmentation.

Part of the 0xKobold ecosystem.

Installation

Bundled (recommended)

pi install npm:@0xkobold/pi-kobold
# pi-persona loaded as sub-extension automatically

Standalone

pi install npm:@0xkobold/pi-persona

# Or in pi-config.ts
{
  extensions: [
    'npm:@0xkobold/pi-persona'
  ]
}

# Or temporary (testing)
pi -e npm:@0xkobold/pi-persona

How It Works

~/.0xkobold/SOUL.md        ← The agent's core personality (always loaded)
~/.0xkobold/IDENTITY.md    ← The agent's name, emoji, vibe (always loaded)
~/.0xkobold/USER.md        ← The user's profile (always loaded)

.0xkobold/SOUL.md          ← Project-specific augmentation (tagged scope: project)
.0xkobold/IDENTITY.md       ← Project identity override (tagged scope: project)
.0xkobold/USER.md           ← Project stakeholder info (tagged scope: project)

When both global AND project files exist for the same type:

• Both are loaded (not replaced)
• Global appears first ("Core Persona")
• Project appears second ("Project Augmentation")
• Project files with scope: project frontmatter get explicit annotation:

  "This is a project-specific override. It augments your core persona for THIS project only."

Frontmatter: Tagging Project Scope

Project files can have YAML frontmatter:

---
scope: project
---
# SOUL — Project Persona

This only applies when working in this project...

If no frontmatter, scope is inferred from location:

• ~/.0xkobold/ → global
• .0xkobold/ or CWD/ → project

Files

| File | Priority | Global Purpose | Project Purpose | |------|----------|---------------|-----------------| | SOUL.md | 20 | Agent personality, values, boundaries | Project-specific vibe/tone override | | IDENTITY.md | 30 | Name, emoji, creature, vibe | Project role (e.g., "code reviewer") | | USER.md | 40 | User profile, preferences, context | Project stakeholders, communication style | | AGENTS.md | 10 | Workspace rules, startup ritual | Project-specific rules, conventions | | BOOTSTRAP.md | 60 | First-run ritual (deleted after use) | — | | MEMORY.md | 70 | Long-term curated memories | Project-specific memory | | TOOLS.md | 50 | Tool notes and preferences | Project tool config |

Commands

| Command | Description | |---------|-------------| | /persona-reload | Reload persona files from disk | | /persona-init | Create global defaults in ~/.0xkobold/ if missing | | /persona-init-project | Create project-scoped files in .0xkobold/ with scope: project |

Tool: persona

| Action | Description | |--------|-------------| | read | Show current persona state (global + project) | | update | Write to a persona file (scope: "global" or "project") | | identity | Parse IDENTITY.md into structured metadata | | init-project | Scaffold project-scoped persona files with frontmatter |

Update example:

# Update global SOUL.md
persona({ action: "update", file: "SOUL.md", content: "# My Soul\n...", scope: "global" })

# Update project IDENTITY.md
persona({ action: "update", file: "IDENTITY.md", content: "---\nscope: project\n---\n...", scope: "project" })

# Init project files
persona({ action: "init-project" })

System Prompt Injection

The extension injects into the system prompt at before_agent_start:

## Persona Context

Your core persona is defined by SOUL.md. **Embody its persona and tone.**
Avoid stiff, generic replies; follow its guidance unless higher-priority
instructions override it.

### Core Persona (global)
#### ~/.0xkobold/SOUL.md
[content]

### Project Augmentation (local)
The following files are project-specific. They augment your core persona
for THIS project only.

#### .0xkobold/SOUL.md ⚡OVERRIDE *(explicitly scoped to this project)*
[content]

API Functions

Library functions are importable for programmatic use:

import {
  buildPersonaState,
  formatPersonaForPrompt,
  parseIdentityMarkdown,
  identityHasValues,
  scaffoldPersonaFiles,
  scaffoldProjectPersonaFiles,
  getDefaultTemplates,
  FILENAMES,
  type PersonaFile,
  type PersonaState,
  type AgentIdentity,
  type ScaffoldResult,
} from "@0xkobold/pi-persona/core";

// Build persona state for a project directory
const state = buildPersonaState("/path/to/project", getDefaultTemplates());
console.log(state.identity?.name, state.hasSoul, state.overrides);

// Format persona files for injection into a prompt
const prompt = formatPersonaForPrompt(state.files);

// Parse an IDENTITY.md file
const identity = parseIdentityMarkdown(markdownContent);
if (identityHasValues(identity)) {
  console.log(identity.name, identity.emoji, identity.vibe);
}

// Scaffold default global persona files
const result = await scaffoldPersonaFiles();
// result.created = ["SOUL.md", "IDENTITY.md", "USER.md"]
// result.skipped = []
// result.dir = "/home/user/.0xkobold"

// Scaffold project-scoped files with frontmatter
const projResult = await scaffoldProjectPersonaFiles("/path/to/project");

Architecture

src/
├── index.ts                 # Extension entry (hooks, tools, commands)
└── core/
    ├── identity-parser.ts   # Parse IDENTITY.md into structured data
    ├── workspace-loader.ts  # Scope-aware file loading + frontmatter + prompt formatting
    ├── scaffold.ts          # Default templates for global & project files
    └── index.ts             # Barrel export

Related Packages

• @0xkobold/pi-kobold — Meta-extension that bundles this and other sub-extensions
• @0xkobold/pi-learn — Persistent memory & reasoning for pi agents
• @0xkobold/pi-ollama — Ollama integration for pi agents

Local Development

git clone https://github.com/0xKobold/pi-persona
cd pi-persona
npm install
npm run build
pi install ./

License

MIT © 0xKobold