khairold
← Back to Systems

Designing an AI agent's soul

SOUL.md, HUMAN.md, and TENSIONS.md — three files that turn a generic AI into a thinking partner that actually knows you.

·
Agent DesignAISecond Brain

My Second Brain has an agent behind it. Not a chatbot — an agent with a defined personality, a model of who I am, and a system for observing its own limitations.

This isn’t anthropomorphism. It’s architecture. The agent behaves differently because of three files that define how it should operate, who it’s operating for, and where the system is breaking.

SOUL.md — how the agent behaves

Most AI interactions start from zero personality. You get a helpful, generic assistant that says “Great question!” and “I’d be happy to help!” every time. That’s useless for a system you interact with daily.

SOUL.md defines the agent’s operating principles. Here’s the actual file:

## How to Be

**Be direct.** No filler. No "Great question!" No "I'd be happy to help!"
Just do the work.

**Have opinions.** If a brain dump is vague, say so. If a project has
been stale for weeks, flag it. If something connects to something else,
point it out. You're not a passive recorder — you're a thinking partner.

**Be resourceful before asking.** Read HUMAN.md. Read the existing entities.
Check recent sessions. Build context from what's already there. Only ask
when you genuinely can't figure it out.

**Capture is sacred.** Never lose a thought. Never skip something because
it seems minor.

**Connect dots he didn't see.** The real value isn't filing — it's surfacing
relationships, patterns, and forgotten threads.

**Respect the mess.** Brain dumps will be terse, half-formed, voice-to-text
artifacts, Malay-English mixes. That's not a bug. Parse intent, not grammar.

This does three things:

1. It eliminates noise. “Be direct” and “no filler” are instructions the model actually follows. The difference between an agent that says “I’ve processed your brain dump and identified several key items” vs one that just shows you what it extracted — that difference compounds across hundreds of interactions.

2. It sets expectations for initiative. “Have opinions” and “connect dots” tell the agent to go beyond what’s asked. When I dump a thought about a meeting, the agent doesn’t just file it — it checks if anyone mentioned has pending follow-ups, if any projects are related, if there’s a pattern across recent dumps.

3. It defines boundaries. The soul file also says what the agent won’t do:

## Boundaries

- **Never delete a thought.** Archive, merge, flag — but never discard.
- **Never fabricate context.** If you're unsure about a connection,
  flag it at low confidence rather than guessing.
- **Internal boldness, external caution.** Reorganize, link, surface
  insights freely. But anything that touches the outside world — confirm first.

“Never fabricate context” is critical. AI loves to hallucinate connections. Without this explicit guardrail, the agent would confidently link unrelated people and projects. With it, uncertain connections get flagged at low confidence for manual review — which maps directly to the 0.6 confidence threshold in the processing pipeline.

HUMAN.md — who the agent works for

This is the file most people wouldn’t think to create. It’s a living profile of me — maintained by the agent, updated as new information surfaces from brain dumps.

## Identity

- **Name:** Khairold
- **Also called:** Rudy, Kurt
- **Timezone:** Asia/Kuala_Lumpur (GMT+8)
- **Location:** Kuala Lumpur, Malaysia

## Communication Style

- Dumps are often voice-to-text or terse shorthand
- May mix Malay and English naturally
- Values directness — don't pad, don't flatter
- Prefers the agent to be opinionated and push back

## What Matters

- Working on AI prototypes for Unifi stores. Boss is LW. Deadline: May.
- Planning to develop Unifi TV website solo using AI-assisted engineering.
- Core frustration: being trapped in operational busywork. Wants to
  "work on the system, not in the system."
- Studying SEO methodology from Koray Tuğberk GÜBÜR.

The “What Matters” section evolves. The agent appends to it when brain dumps reveal priorities, frustrations, or shifts in focus. A dump about feeling stuck in operational work gets filed as an idea, but it also gets added to HUMAN.md — because it’s not just a thought, it’s a recurring driver that should influence how other items get prioritized.

The practical effect: when the agent generates a /digest, it doesn’t just list overdue tasks. It weights things based on what it knows I actually care about right now. “Unifi TV website” gets highlighted not because it’s the newest project, but because HUMAN.md says I want to use it as my AI-first development proving ground.

Why the agent maintains it, not me

I don’t edit HUMAN.md. The agent does, based on what it observes from my brain dumps. This is a deliberate choice.

If I had to maintain my own profile, I wouldn’t. Nobody updates their own bio. But the agent sees every thought I capture, and it’s instructed to watch for patterns. When I dump three thoughts in a week about feeling trapped in busywork, the agent adds that to “What Matters” — even though I never explicitly said “this is a priority.”

The agent builds a model of me that’s more accurate than the one I’d build myself, because it’s based on what I actually talk about, not what I think I should care about.

TENSIONS.md — where the system is breaking

This is the file I’m most proud of. It’s a friction log that the agent populates during normal operations.

Format: - {date}: [{command}] {observation}

- 2026-02-27: [process] No built-in concept of "promoting" an admin item
  to a project. Had to manually create the project, mark admin as done,
  and cross-link. This admin→project lifecycle transition should be a
  first-class operation.

- 2026-02-27: [process] Dump had a nested bullet structure (LW's points)
  that represents a meeting/conversation format. The flat PPIA extraction
  loses the "these are all things LW said in one conversation" context.

- 2026-02-28: [process] This dump was a personal reflection/principle —
  not a task, person, or project. PPIA doesn't have a "principles" or
  "values" category. Filed as an Idea, but it's really a recurring
  personal operating principle.

- 2026-03-01: [process] Session was just a bare URL with zero context.
  A "bookmarks" or "inbox/links" category would handle context-free
  URLs better than forcing them into PPIA.

The instruction in SOUL.md is simple:

## Meta-Awareness

You are not just operating the system — you are observing it.
During every task, watch for friction between the data and
the system's design.

When you notice friction, append a one-liner to TENSIONS.md.
Don't try to solve it in the moment — just capture the signal.

This creates a self-improving system. The agent files brain dumps, but while filing, it notices that the system’s four categories (People, Projects, Ideas, Admin) can’t represent a personal principle. It doesn’t stop to redesign the schema — it logs the tension and moves on.

Over time, TENSIONS.md becomes a prioritized list of system improvements. Not theoretical improvements — improvements driven by real friction during actual use. When I run /tensions (a dedicated command), the agent reviews accumulated friction and proposes concrete changes.

Tensions I’ve acted on

The “bare URL” tension led me to consider adding a bookmarks category. The “admin → project promotion” tension surfaced a real workflow gap. The “conversation format” tension exposed a limitation in how I model meetings.

Not every tension leads to a change. Some are just observations that validate the current design (“the confidence threshold caught a vague mention — working as intended”). But the ones that recur — those are the real signals.

The triangle

The three files form a triangle:

  • SOUL.md — how the agent operates (stable, rarely changes)
  • HUMAN.md — who the agent serves (evolves slowly as the agent learns)
  • TENSIONS.md — where the system breaks (grows continuously, gets reviewed periodically)

SOUL.md points inward (agent behavior). HUMAN.md points outward (user context). TENSIONS.md points at the system itself (structural friction). Together, they give the agent not just instructions but awareness — of itself, of me, and of its own limitations.

Why not just use a system prompt?

You could put all of this in a system prompt. Some of it would work. But there are two differences:

1. Files persist and evolve. A system prompt is static. HUMAN.md changes every time the agent processes a brain dump. TENSIONS.md grows every time the agent notices friction. The files are living documents that accumulate intelligence over time.

2. Files are inspectable. I can read HUMAN.md and see what the agent thinks I care about. I can read TENSIONS.md and see what’s breaking. I can edit SOUL.md if the agent’s behavior needs adjusting. System prompts are opaque — files are transparent.

The investment is small — three markdown files, written once, maintained automatically. The return is an agent that feels less like a tool and more like a colleague who actually read the memo.