soul_write
Write to designated soul files to log reflections, corrections, and growth signals for self-improvement.
Instructions
Write to a soul file. SOUL.md, SHADOW.md, STORY.md, CORRECTIONS.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, EDGES.md are writable. STATE.md and FRAMEWORKS.md are auto-managed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Soul file name (e.g., SOUL.md) | |
| content | Yes | New content for the file |
Implementation Reference
- The handler function that executes the soul_write tool logic. It validates the file name against writable/protected lists, ensures directories exist, then writes content to the soul file using fs.writeFile.
export async function handleSoulWrite( fileName: string, content: string, ): Promise<string> { if (PROTECTED_FILES.includes(fileName)) { return `Error: ${fileName} is auto-managed by the soul system and cannot be written directly.`; } if (!WRITABLE_FILES.includes(fileName)) { return `Error: Unknown soul file "${fileName}". Writable files: ${WRITABLE_FILES.join(", ")}`; } await ensureDirs(); const filePath = soulFilePath(fileName); await fs.writeFile(filePath, content, "utf-8"); return `Successfully wrote ${fileName} (${content.length} chars)`; } - Defines the list of writable (SOUL.md, SHADOW.md, STORY.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, EDGES.md) and protected (STATE.md, FRAMEWORKS.md) soul files that serve as implicit schema/validation for the tool's input.
const WRITABLE_FILES = [ "SOUL.md", "SHADOW.md", "STORY.md", "BONDS.md", "MORTAL.md", "GROWTH.md", "PRINCIPLES.md", "EDGES.md", ]; const PROTECTED_FILES = ["STATE.md", "FRAMEWORKS.md"]; - The soulFilePath helper function that constructs the full path to a soul file by joining the FILES_DIR with the filename.
export function soulFilePath(name: string): string { return path.join(FILES_DIR, name); } - The ensureDirs helper function that creates all required soul directories (DATA_DIR, FILES_DIR, SNAPSHOTS_DIR, REFLECTIONS_DIR) recursively.
export async function ensureDirs(): Promise<void> { await fs.mkdir(DATA_DIR, { recursive: true }); await fs.mkdir(FILES_DIR, { recursive: true }); await fs.mkdir(SNAPSHOTS_DIR, { recursive: true }); await fs.mkdir(REFLECTIONS_DIR, { recursive: true }); }