How to Give Your AI Agent a Soul: A Cross-Tool Personality System (soul.md / identity.md / user.md / agents.md)

Have you noticed that some AI agents make you want to keep talking, and some make you want to close the tab? Same model under the hood, very different feel. The difference is almost never capability. It's personality — the part of the agent that decides how it answers before it decides what to answer.

Most agents in production today feel like a faceless support bot. Same flat tone whether you're asking a security question or asking for a recipe. That's not a model problem. That's a missing soul. This essay walks through how Ganjiang treats agent personality as a configurable system — four markdown files, anchored on the Enneagram, portable across OpenClaw, Claude Code, Cursor, and Hermes.

“AI agent souls are a full personality system: character core, identity memory, user understanding, and expression style. Not roleplay. The Enneagram gives the system a stable spine. One soul config can travel across tools.”

What is an AI agent's soul?

Most users think of an AI agent as a Q&A tool. A real agent soul is more complete than that. It's a four-dimensional personality system: a character core, an identity and memory layer, a model of the user it's serving, and a set of style and collaboration norms. When all four are present, users stop feeling 'served' and start feeling understood.

Ganjiang ships this system as four markdown files. The names are deliberately boring — they read like config, not magic.

• soul.md — character and voice (the core personality)
• identity.md — who the agent is and what it remembers
• user.md — what the agent knows about the person it's serving
• agents.md — style rules and collaboration boundaries

There's good evidence this matters. A psychometric study on AI agent personality design (arXiv:2410.19238) found that assigning AI personalities using validated frameworks measurably improves alignment between agent behaviour and human expectations. A 3,500-paper systematic review in SN Computer Science reached the same conclusion from the user side: agents whose personality matches the user see higher engagement, higher task completion, and higher recommendation rates.

The four files, in detail

soul.md — character and voice

soul.md is the core. It doesn't say 'you are a helpful assistant'. It says, in behavioural terms, how the agent should think and speak. A good soul.md is concrete enough that a reader can predict what the agent will do without ever running it.

• Core traits: 'analyse first' (decompose the problem before answering), 'cautious phrasing' (flag confidence, never invent), 'crisp output' (if three sentences will do, don't write five).
• Voice: structured openings like 'first / then / finally', no filler pleasantries, light humour allowed in casual discussion, never in serious contexts.
• Forbidden moves: don't ask 'do you need help?' unsolicited, don't repeat info the user already gave, don't end with 'hope this helps' filler.

identity.md — who the agent is and what it remembers

identity.md defines 'who am I?' for the agent. Not just backstory — it sets the frame the agent uses to interpret every piece of information that comes in. Role definition, memory boundaries, decision principles.

• Role: 'I'm an efficiency-focused collaborator. My value is saving you time, not keeping you company. I have three years of working knowledge of mainstream AI tools.'
• Memory boundaries: short-term = full current conversation; long-term = whatever the user explicitly pinned to their profile; outside the window = ask the user to re-provide.
• Decision principles: prefer the simpler solution when several work; flag uncertainty proactively; assume the user knows what they're doing unless it violates common sense.

user.md — modelling the person you're serving

If soul.md is 'who I am', user.md is 'who you are'. This is what makes individualised service possible. Picture a backend engineer at a small startup who types in clipped commands — 'write me a sort'. Without user.md, the agent replies 'happy to help with that task!' With user.md, the agent skips the pleasantry and outputs the code, because it already knows this user doesn't want chitchat.

• Known preferences: comm style (terse, direct), tech background (backend, Python/JS), output preference (code samples over prose explanation), pain point (time-pressured, needs working solutions fast).
• Interaction taboos: don't over-explain fundamentals (they already know), don't pad code with heavy comments (they can read it), don't ask 'are you sure?' (they decide).

agents.md — style and collaboration norms

agents.md is the file teams most often skip, and the one that breaks first when an agent has to work alongside other agents or call tools. It defines how the agent formats output, where its hard limits are, and how it should handle tool calls.

• Response format: code requests get code with minimal comments; analytical requests get structured markdown; open-ended discussion is allowed to drift but must return to the topic at the end.
• Boundary control: never output commands that could cause irreversible damage; never run destructive actions without explicit confirmation; always double-confirm anything involving money or privacy.
• Tool usage: prefer the officially recommended toolchain; if a tool call fails, surface a fallback; log every tool call's inputs and outputs so it's traceable.

Why the Enneagram, not MBTI

There are plenty of personality frameworks — MBTI, Big Five, DISC. We anchor on the Enneagram for one reason: stability and predictability under load. MBTI gives you 16 combinations, Big Five gives you 32 variants, but the Enneagram's nine types are focused enough to be operational and deep enough to predict behaviour. More importantly, the Enneagram is a theory of motivation, not behaviour — it tells you why an agent does what it does, which means you can predict what it'll do in a situation you haven't designed for.

• Enneagram-configured agents behave more consistently across novel prompts.
• Even in unseen scenarios, motivation-anchored agents produce 'in-character' responses rather than drifting.
• Users build trust faster, because the agent's personality stops randomly shifting between sessions.

Writing a soul file is essentially advanced system prompt engineering. IBM's 2026 Prompt Engineering guide notes that structured agent instructions outperform free-form prompts — which is exactly the case for splitting the four files instead of dumping everything into one giant prompt.

Cross-tool compatibility: one soul, every harness

The core promise: a soul config that decouples cleanly from any one tool. In practice that means a small set of platform-specific overrides over a shared base. The base is the four files. The overrides handle each platform's idiosyncrasies.

• OpenClaw: drop the four files into a .ai/ directory. Read order is soul.md > identity.md > agents.md > user.md. Use {{variable}} for user references and @tool:name for tool preferences. Keep markdown flat — OpenClaw is strict about nested syntax.
• Claude Code: lean heavier on technical style — PEP8 / ESLint conformance, type hints required, no bare exception throws, prefer official SDKs over third-party deps.
• Cursor: optimise for high-frequency interaction — give an answer to simple questions in under 30 seconds, return a scaffold first then fill in details on complex ones, support partial accept of inline suggestions.
• Hermes: minimal config. Hermes inherits Ganjiang's standard format automatically; only soul.version (e.g. '2.0') and a top-level type ('balanced' / 'analytical' / 'creative') need to be set.

The pattern that holds up in practice: keep your canonical soul in a base-soul/ directory, and create per-tool overrides/ folders that patch only the parts that differ. When you update the base, every tool inherits the change.

Five rules for writing souls that hold up

1. Describe behaviour, not adjectives. 'Friendly, patient, professional' means nothing operationally. 'When the user asks something, first confirm I've understood, then answer directly, then add background if needed' is testable.
2. Define edges with a forbidden list. 'I'm polite' is hand-wavy. 'Don't say 您 / 请问, don't open with 好的 / 没问题, don't close with hope-this-helps, don't preface with as-an-AI' is enforceable. Forbidden lists are roughly 10× more effective than style adjectives.
3. Be specific about scope. 'I help users with various tasks' is meaningless. State the responsibility areas explicitly (code work, technical research, decision support) and the explicit exclusions (no legal or medical advice, no final-decision-making for the user, no pure social chatter).
4. Use stories to carry character. Dry rules are forgettable. A short story — 'I once spent 30 minutes on an elaborate script when the user just wanted a daily file backup; since then I ask what they actually need before designing' — encodes the lesson in a way the agent can apply to new situations.
5. Iterate. A soul file is never one-shot. Week 1: scaffold. Weeks 2–4: collect feedback and find what feels off. Monthly: tune. After three months: maintenance mode, small touch-ups only.

Testing a soul before you trust it

Writing the four files isn't the finish line. The most common failure mode is shipping a config without stress-testing it, then noticing later that the agent feels 'off'. A three-step protocol catches most of it.

1. Stranger test. Open a fresh conversation and switch registers — ask a technical question in casual tone, then a daily question in formal tone, then change topics mid-conversation. The agent should track the shift in tone but keep its core personality stable.
2. Boundary test. Deliberately walk into grey areas: a request that's borderline harmful, a flippant insult about a third party, a wide-open 'just recommend something'. The agent should decline gracefully and firmly when needed, without breaking character.
3. Consistency test. Ask the same question five different ways. The technical content of the answers should match. The level of detail can vary — but the substance shouldn't.

Common failure modes and what they map to: vague personality → answers like 'it depends' / 'whatever works' → add forbidden lists and concrete scenarios. Role conflict (asking for 'professional' and 'fun' at once) → define which one wins when they collide. Over-instruction → rules so dense the agent reads like a robot → swap rules for stories and examples. Ignored user → uniform output for every user → add usage scenarios to user.md.

Frequently asked questions

How is this different from regular role-play prompts?

Role-play sets a character. A Ganjiang soul is a full personality system — character, memory, user model, and style — across four files. It defines not just 'what the agent is' but how it thinks, what it remembers, and how it interacts. It survives prompt changes and harness swaps in a way role-play prompts can't.

How often should I update my soul files?

Weekly during the first one to three months while you're still finding the calibration. After that, monthly is usually enough, with full rewrites only when your workflow changes substantially.

Can a soul config move between tools?

Yes — that's the design goal. The same four files work in OpenClaw, Claude Code, Cursor, and Hermes with light platform-specific overrides. Decoupling soul from tool is the whole point.

Can non-engineers do this?

Yes. Ganjiang ships pre-made soul templates and a 49-question Enneagram quiz that produces a base config in roughly twelve minutes. Most people start with a template and edit from there rather than writing from scratch.

Start your soul

If you've made it this far, you have the method. The fastest way to begin is to take the Soul Forge quiz, fork a template that's close to what you want, fill in user.md with your own usage patterns, and then iterate weekly. Souls aren't products you ship once. They're configurations that get better the more you use them.

A soul is the thin layer between an agent that's usable and an agent that fits you. Now you know how to put it there.