{"_id":"@0xkobold/pi-persona","name":"@0xkobold/pi-persona","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0xkobold/pi-persona","version":"0.1.0","description":"Persona extension for pi agents — SOUL.md, IDENTITY.md, USER.md loading, scaffolding, and system prompt injection. Inspired by OpenClaw.","keywords":["pi-package","pi-extension","persona","soul","identity","agent"],"author":{"name":"0xKobold"},"license":"MIT","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./core":{"import":"./dist/core/index.js","types":"./dist/core/index.d.ts"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"bun test","prepublishOnly":"rm -rf dist && tsc"},"pi":{"extensions":["./dist/index.js"]},"peerDependencies":{"@mariozechner/pi-coding-agent":">=0.65.0","@sinclair/typebox":">=0.32.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+https://github.com/0xKobold/pi-persona.git"},"bugs":{"url":"https://github.com/0xKobold/pi-persona/issues"},"homepage":"https://github.com/0xKobold/pi-persona#readme","gitHead":"07fde3625dcb115a25c2f9792f8ba33bff4b47b3","_id":"@0xkobold/pi-persona@0.1.0","_nodeVersion":"25.1.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-F/lPgPfOOT4G1J/xoy4sy8RcGfS34HK5srz0PmNtboM6xQyW/PzD/UtBJ//tX3EmftCx/vQfohNBeNeD7LuKTw==","shasum":"9618b3a73f0eab5297f093bf7fbdf714a150fd52","tarball":"https://registry.npmjs.org/@0xkobold/pi-persona/-/pi-persona-0.1.0.tgz","fileCount":12,"unpackedSize":63286,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCQ0ThxOu9dd3zibX72J9kQHBiuqSia2uLVlKv5OEWvawIhAMI6lg7elyquHCNRANCQVjlsWIPMkTBfPh7q6fe9qRsP"}]},"_npmUser":{"name":"moikapy","email":"warrenckhan@gmail.com"},"directories":{},"maintainers":[{"name":"moikapy","email":"warrenckhan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-persona_0.1.0_1775700910205_0.5355695880343723"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-09T02:15:10.136Z","0.1.0":"2026-04-09T02:15:10.367Z","modified":"2026-04-09T02:15:10.583Z"},"maintainers":[{"name":"moikapy","email":"warrenckhan@gmail.com"}],"description":"Persona extension for pi agents — SOUL.md, IDENTITY.md, USER.md loading, scaffolding, and system prompt injection. Inspired by OpenClaw.","homepage":"https://github.com/0xKobold/pi-persona#readme","keywords":["pi-package","pi-extension","persona","soul","identity","agent"],"repository":{"type":"git","url":"git+https://github.com/0xKobold/pi-persona.git"},"author":{"name":"0xKobold"},"bugs":{"url":"https://github.com/0xKobold/pi-persona/issues"},"license":"MIT","readme":"# @0xkobold/pi-persona\n\nScope-aware persona management for [pi](https://pi.dev) agents.\n\n**Global persona = who the agent IS.** Project persona = situational augmentation.\n\nPart of the [0xKobold](https://github.com/0xKobold) ecosystem.\n\n## Installation\n\n### Bundled (recommended)\n\n```bash\npi install npm:@0xkobold/pi-kobold\n# pi-persona loaded as sub-extension automatically\n```\n\n### Standalone\n\n```bash\npi install npm:@0xkobold/pi-persona\n\n# Or in pi-config.ts\n{\n  extensions: [\n    'npm:@0xkobold/pi-persona'\n  ]\n}\n\n# Or temporary (testing)\npi -e npm:@0xkobold/pi-persona\n```\n\n## How It Works\n\n```\n~/.0xkobold/SOUL.md        ← The agent's core personality (always loaded)\n~/.0xkobold/IDENTITY.md    ← The agent's name, emoji, vibe (always loaded)\n~/.0xkobold/USER.md        ← The user's profile (always loaded)\n\n.0xkobold/SOUL.md          ← Project-specific augmentation (tagged scope: project)\n.0xkobold/IDENTITY.md       ← Project identity override (tagged scope: project)\n.0xkobold/USER.md           ← Project stakeholder info (tagged scope: project)\n```\n\nWhen both global AND project files exist for the same type:\n- **Both are loaded** (not replaced)\n- Global appears first (\"Core Persona\")\n- Project appears second (\"Project Augmentation\")\n- Project files with `scope: project` frontmatter get explicit annotation:\n  > \"This is a project-specific override. It augments your core persona for THIS project only.\"\n\n## Frontmatter: Tagging Project Scope\n\nProject files can have YAML frontmatter:\n\n```markdown\n---\nscope: project\n---\n# SOUL — Project Persona\n\nThis only applies when working in this project...\n```\n\nIf no frontmatter, scope is inferred from location:\n- `~/.0xkobold/` → `global`\n- `.0xkobold/` or `CWD/` → `project`\n\n## Files\n\n| File | Priority | Global Purpose | Project Purpose |\n|------|----------|---------------|-----------------|\n| **SOUL.md** | 20 | Agent personality, values, boundaries | Project-specific vibe/tone override |\n| **IDENTITY.md** | 30 | Name, emoji, creature, vibe | Project role (e.g., \"code reviewer\") |\n| **USER.md** | 40 | User profile, preferences, context | Project stakeholders, communication style |\n| **AGENTS.md** | 10 | Workspace rules, startup ritual | Project-specific rules, conventions |\n| **BOOTSTRAP.md** | 60 | First-run ritual (deleted after use) | — |\n| **MEMORY.md** | 70 | Long-term curated memories | Project-specific memory |\n| **TOOLS.md** | 50 | Tool notes and preferences | Project tool config |\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/persona-reload` | Reload persona files from disk |\n| `/persona-init` | Create global defaults in `~/.0xkobold/` if missing |\n| `/persona-init-project` | Create project-scoped files in `.0xkobold/` with `scope: project` |\n\n## Tool: `persona`\n\n| Action | Description |\n|--------|-------------|\n| `read` | Show current persona state (global + project) |\n| `update` | Write to a persona file (`scope`: \"global\" or \"project\") |\n| `identity` | Parse IDENTITY.md into structured metadata |\n| `init-project` | Scaffold project-scoped persona files with frontmatter |\n\n**Update example:**\n\n```\n# Update global SOUL.md\npersona({ action: \"update\", file: \"SOUL.md\", content: \"# My Soul\\n...\", scope: \"global\" })\n\n# Update project IDENTITY.md\npersona({ action: \"update\", file: \"IDENTITY.md\", content: \"---\\nscope: project\\n---\\n...\", scope: \"project\" })\n\n# Init project files\npersona({ action: \"init-project\" })\n```\n\n## System Prompt Injection\n\nThe extension injects into the system prompt at `before_agent_start`:\n\n```\n## Persona Context\n\nYour core persona is defined by SOUL.md. **Embody its persona and tone.**\nAvoid stiff, generic replies; follow its guidance unless higher-priority\ninstructions override it.\n\n### Core Persona (global)\n#### ~/.0xkobold/SOUL.md\n[content]\n\n### Project Augmentation (local)\nThe following files are project-specific. They augment your core persona\nfor THIS project only.\n\n#### .0xkobold/SOUL.md ⚡OVERRIDE *(explicitly scoped to this project)*\n[content]\n```\n\n## API Functions\n\nLibrary functions are importable for programmatic use:\n\n```typescript\nimport {\n  buildPersonaState,\n  formatPersonaForPrompt,\n  parseIdentityMarkdown,\n  identityHasValues,\n  scaffoldPersonaFiles,\n  scaffoldProjectPersonaFiles,\n  getDefaultTemplates,\n  FILENAMES,\n  type PersonaFile,\n  type PersonaState,\n  type AgentIdentity,\n  type ScaffoldResult,\n} from \"@0xkobold/pi-persona/core\";\n\n// Build persona state for a project directory\nconst state = buildPersonaState(\"/path/to/project\", getDefaultTemplates());\nconsole.log(state.identity?.name, state.hasSoul, state.overrides);\n\n// Format persona files for injection into a prompt\nconst prompt = formatPersonaForPrompt(state.files);\n\n// Parse an IDENTITY.md file\nconst identity = parseIdentityMarkdown(markdownContent);\nif (identityHasValues(identity)) {\n  console.log(identity.name, identity.emoji, identity.vibe);\n}\n\n// Scaffold default global persona files\nconst result = await scaffoldPersonaFiles();\n// result.created = [\"SOUL.md\", \"IDENTITY.md\", \"USER.md\"]\n// result.skipped = []\n// result.dir = \"/home/user/.0xkobold\"\n\n// Scaffold project-scoped files with frontmatter\nconst projResult = await scaffoldProjectPersonaFiles(\"/path/to/project\");\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts                 # Extension entry (hooks, tools, commands)\n└── core/\n    ├── identity-parser.ts   # Parse IDENTITY.md into structured data\n    ├── workspace-loader.ts  # Scope-aware file loading + frontmatter + prompt formatting\n    ├── scaffold.ts          # Default templates for global & project files\n    └── index.ts             # Barrel export\n```\n\n## Related Packages\n\n- [`@0xkobold/pi-kobold`](https://github.com/0xKobold/pi-kobold) — Meta-extension that bundles this and other sub-extensions\n- [`@0xkobold/pi-learn`](https://github.com/0xKobold/pi-learn) — Persistent memory & reasoning for pi agents\n- [`@0xkobold/pi-ollama`](https://github.com/0xKobold/pi-ollama) — Ollama integration for pi agents\n\n## Local Development\n\n```bash\ngit clone https://github.com/0xKobold/pi-persona\ncd pi-persona\nnpm install\nnpm run build\npi install ./\n```\n\n## License\n\nMIT © 0xKobold","readmeFilename":"README.md","_rev":"1-192403b04de6c51ab0721942383dd225"}