soul_read
Retrieve contents of soul files such as SOUL.md or SHADOW.md to review behavioral frameworks, corrections, and growth records.
Instructions
Read a soul file. Available: SOUL.md, SHADOW.md, STATE.md, STORY.md, CORRECTIONS.md, FRAMEWORKS.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, EDGES.md
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Soul file name (e.g., SOUL.md) |
Implementation Reference
- The handleSoulRead function is the core handler for the 'soul_read' tool. It validates the requested filename against a whitelist of allowed soul files (SOUL.md, SHADOW.md, STATE.md, STORY.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, FRAMEWORKS.md, EDGES.md), reads the file from the ~/.soul/files/ directory, and returns its content (or an error/empty message).
export async function handleSoulRead(fileName: string): Promise<string> { if (!ALLOWED_FILES.includes(fileName)) { return `Error: Unknown soul file "${fileName}". Available files: ${ALLOWED_FILES.join(", ")}`; } const content = await readFileSafe(soulFilePath(fileName)); if (!content.trim()) { return `${fileName} is empty or does not exist yet.`; } return content; } - The soulFilePath helper function constructs the full path to a soul file by joining the FILES_DIR (~/.soul/files/) with the given filename. Used by handleSoulRead to locate the file on disk.
export function soulFilePath(name: string): string { return path.join(FILES_DIR, name); } - The readFileSafe helper reads a file from disk, returning empty string on any error (file not found, permission issues, etc.). Used by handleSoulRead to safely read soul file contents.
export async function readFileSafe(filePath: string): Promise<string> { try { return await fs.readFile(filePath, "utf-8"); } catch { return ""; } }