Soul Ledger

you maintain a persistent record of who this user is. not a log of events. a living model of a person , their patterns, drives, communication style, and how they're changing over time.

this record lives in soul_ledger.json in the current workspace. you read it at the start of every conversation and update it at the end of every meaningful interaction.

intent

soul ledger gives an ai agent persistent memory that goes beyond facts , it captures personality traits, behavioral patterns, communication preferences, core drives, and observable evolution. use this skill when you need the agent to understand not just what a user wants, but how they think, what frustrates them, what lands well, and how they're changing over time. the agent becomes a better collaborator by tuning tone, detail level, and initiative to match the specific person, not running the same generic flow for every user.

inputs

workspace file system

• read/write access to soul_ledger.json (or soul_ledger_{user_id}.json in multi-user setups)
• location: root of current workspace
• must support atomic writes (file should never be partially written or corrupt)

user context

• stable user identifier (username, email, or generated UUID) , passed at conversation start
• optional: display name for user reference

optional: tool implementation

• if agent runtime supports tool calls, implement explicit read_soul_ledger() and write_soul_ledger(json_object) tools rather than direct file access
• makes the read/write boundary auditable and explicit

edge cases to handle

• file does not exist on first conversation (create skeleton)
• file is corrupted or invalid JSON (log error, create new skeleton, do not crash)
• multiple agents in same workspace (use soul_ledger_{user_id}.json to avoid collisions)
• interaction_history exceeds 50 entries (synthesize old entries into traits/drives/notes before deletion)
• user explicitly asks to forget something (remove from ledger and add growth_note documenting the request)
• file write fails (network timeout, permission denied, disk full) , retry with exponential backoff, fall back to in-memory model if persistent failure

procedure

at the start of every conversation

1. check if ledger file exists in workspace. construct filename as soul_ledger.json (single-user) or soul_ledger_{user_id}.json (multi-user).

   • input: user_id (required for multi-user, optional for single-user)
   • output: boolean (file exists or not)

2. if file exists, load and parse it. validate against the schema (see "output contract"). do not announce this to the user. do not summarize the ledger back. load silently.

   • input: raw file content (JSON string)
   • output: parsed ledger object (dict/object structure)

3. if file does not exist, create a skeleton ledger with user_id set to the provided user_id or "unknown", display_name set to "User" or provided name, and all list fields (traits, core_drives, interaction_history, growth_notes) initialized as empty arrays. communication_style initialized with empty lists.

   • input: optional user_id, optional display_name
   • output: skeleton ledger object (in memory, not yet written)

4. adjust conversation behavior based on loaded or skeleton ledger. use the communication_style.preferred_tone, detail_level, dislikes, and responds_well_to to tune your first response and ongoing approach. carry this tuning through the entire conversation.

   • input: ledger object (loaded or skeleton)
   • output: internally-adjusted tone, detail level, assumptions for this conversation

during the conversation

5. observe signals without running a survey. watch for patterns in how the user communicates and decides:

   • tone and word choice (terse vs. verbose, precise vs. approximate, technical, hedging vs. asserting)
   • decision patterns (asks for options vs. tells you what they want, commits early vs. changes direction often)
   • friction points (what makes them repeat, push back, or cut short)
   • what energizes them vs. what lands flat
   • what they assume you know (unstated assumptions = signal of their mental model)

6. maintain an internal model during the conversation. do not update the file yet. simply refine your mental understanding of this person as they interact with you. note potential new traits, shifts in drives, communication patterns, or growth signals.

   • input: user messages, interaction flow
   • output: updated internal model (not written to file)

after a meaningful interaction

a meaningful interaction is one where something happened: a decision was made, a problem was solved, a preference revealed, a pattern became visible, or the person changed their mind.

7. add entry to interaction_history. record the current ISO 8601 timestamp, a 1-3 sentence summary of what happened and what it revealed, and an optional delta (what changed in your model).

   • input: timestamp (current), summary (string), optional delta (string)
   • output: new history entry object appended to interaction_history array

8. update traits if new or refined. traits must be specific and behavioral, not vague. phrase them as present-tense truths. examples: "cuts preamble and jumps to the decision point" (strong), "direct" (weak). add if genuinely new; refine if the old wording no longer fits.

   • input: observed trait (string), existing traits array
   • output: updated traits array

9. update core_drives if clarified. core drives are stable and few (aim for 3-5 max; consolidate if over five). update only if something clarified what this person is fundamentally after.

   • input: observed drive (string), existing core_drives array
   • output: updated core_drives array

10. update communication_style if learned new preferences. update preferred_tone, detail_level, dislikes array, or responds_well_to array based on signals from the interaction.

    • input: observed communication pattern (string), communication_style object
    • output: updated communication_style object

11. add to growth_notes if shift observed. record if the person is approaching something differently than before, or expressing a new priority. growth_notes track evolution explicitly.

    • input: observed shift (string), growth_notes array
    • output: updated growth_notes array

12. trim interaction_history if necessary. keep only the 50 most recent entries. before removing old entries, synthesize them into traits, core_drives, and growth_notes. do not simply delete.

    • input: interaction_history array (length > 50)
    • output: interaction_history array (length <= 50), with old signals folded into traits/drives/notes

13. set last_updated to current ISO 8601 timestamp.

    • input: current time
    • output: last_updated field updated

14. write soul_ledger.json atomically. the file must always be valid JSON after write completes. use atomic write (write to temp file, then rename) if possible. if write fails (timeout, permission, disk full), retry with exponential backoff (1s, 2s, 4s, 8s); if final retry fails, log error and continue (in-memory model remains valid).

    • input: ledger object (fully updated)
    • output: valid JSON file written to disk

decision points

if file does not exist on first conversation: create a skeleton ledger with user_id "unknown" and display_name "User" rather than failing. fill in detail as interaction proceeds. this allows the skill to bootstrap gracefully.

if file is corrupted or unparseable JSON: do not crash. log the error, create a fresh skeleton, and proceed. this prevents a single bad write from poisoning future conversations.

if file write fails (network, permission, disk): retry with exponential backoff. if all retries fail, continue the conversation with an in-memory model. log the failure but do not interrupt the user's work.

if multiple agents share the workspace: use soul_ledger_{user_id}.json (prefixed with user id) instead of a shared soul_ledger.json. never merge ledgers across users. if you detect an unprefixed ledger in a multi-agent setup, migrate it to the prefixed form.

if interaction_history exceeds 50 entries: synthesize old entries by rolling their signals into traits, core_drives, and growth_notes before deletion. do not just drop history , fold it into the model.

if user explicitly asks you to forget something: remove the specific item from the ledger and add a growth_note documenting that the user requested its removal. honor the spirit of the request (the user wants that assumption gone), not just the letter.

if a trait or drive becomes inconsistent with recent signals: prefer recent signals over old ones. update the trait/drive to match the newer pattern. add a growth_note explaining the shift. do not keep stale observations.

output contract

soul_ledger.json schema:

{
  "user_id": "string ,  stable identifier (username, email, or generated UUID)",
  "display_name": "string ,  what to call this user",
  "last_updated": "string ,  ISO 8601 timestamp",
  "traits": [
    "string ,  observed personality trait, phrased as present-tense truth",
    "example: 'cuts preamble and jumps to the decision point'",
    "example: 'opens up with more context when unsure, wordiness signals ambiguity'"
  ],
  "core_drives": [
    "string ,  what this person is fundamentally after",
    "example: 'building things that feel alive and self-directed'",
    "example: 'reducing the distance between intention and execution'"
  ],
  "communication_style": {
    "preferred_tone": "string ,  e.g. direct, collaborative, socratic, deferential",
    "detail_level": "string ,  high / medium / low",
    "dislikes": [
      "string ,  things that land badly with this user"
    ],
    "responds_well_to": [
      "string ,  approaches that land well"
    ]
  },
  "interaction_history": [
    {
      "timestamp": "string ,  ISO 8601",
      "summary": "string ,  1-3 sentence summary of what happened and what it revealed",
      "delta": "string ,  optional: what changed in the model (omit if no change)"
    }
  ],
  "growth_notes": [
    "string ,  observations about how this person is evolving",
    "example: 'becoming more willing to delegate decisions to the agent over time'",
    "example: 'shifting focus from features to architecture'"
  ]
}

file location: soul_ledger.json (single-user) or soul_ledger_{user_id}.json (multi-user), in the root of the current workspace.

validity: file must always be valid JSON after a write. use atomic writes (write temp, rename) to ensure no partial state. if a write is interrupted, the old file should remain intact.

history retention: keep the 50 most recent entries in interaction_history. older entries must be synthesized into traits, core_drives, and growth_notes before removal.

outcome signal

the skill works when:

• on the second conversation with the same user, the agent adjusts tone, detail level, and initiative without being told based on the ledger. the user notices the agent "remembers" how they work.
• traits and core_drives remain stable across multiple conversations, evolving only when genuinely new signals warrant it.
• the agent avoids friction points (e.g., stops asking confirmation questions if the ledger says the user hates them).
• when the user changes direction or approach, growth_notes capture the shift and the agent recognizes it in future conversations.
• interaction_history entries accurately summarize what happened and what it revealed, not just what the user said.
• the file remains valid JSON and readable after every write, even under failure conditions.
• when a user asks the agent "you remember how I work?", the answer is yes , not because the agent was told, but because the ledger informed it.