Agent identity · IDENTITY.md

Every Shara agent (starting with Amadeus, the orchestrator) carries its own IDENTITY.md file: the living document where it’s written who you are, how you speak and how you work. It isn’t a loose prompt that gets lost between conversations; it’s the source of truth for the agent’s corporate personality, and it evolves through versioned patches with every assignment.

What IDENTITY.md is

It’s an IDENTITY.md file per agent that Shara injects at the start of every execution, before any instruction from the conversation. That’s where the brand tone lives, the preferred and forbidden vocabulary, the canonical FAQs, the internal processes and the limits of what the agent can and can’t do. Thanks to it, Patterson (sales) sounds like your company and not like a generic chatbot, and Holmes (legal) uses exactly the terminology your firm expects.

Identity is per agent, not global: Hopkins’s (marketing) commercial tone isn’t Graham’s (finance) cautious tone. Each has its own file, with shared sections but its own content. Amadeus watches that every response it synthesises respects the IDENTITY.md of the agent that produced it, so everything coming out of the team sounds consistent even when different specialists sign it.

Think of IDENTITY.md as each agent’s brand manual: what a new employee would read on their first day to talk and act like your company. The difference is that here it’s applied on every task, with no exceptions and nothing forgotten.

Why it isn’t just a prompt

A prompt written by hand in a conversation gets lost as soon as you close the window, isn’t logged and nobody guarantees the agent will respect it next time. IDENTITY.md solves exactly that:

• Persistent: it doesn’t depend on you remembering to paste the instructions. It’s always there, on every execution.
• Structured: fixed sections (tone, vocabulary, processes, FAQs, limits, context) instead of an improvised paragraph.
• Versioned and audited: every change leaves a trail; you know what identity the agent had at any point in the past.
• Shared across your team: everyone using that agent works on the same identity, not on each person’s own interpretation.

What each IDENTITY.md captures

The file is organized into stable sections. These are the ones with the most weight on the agent’s behavior:

Section	What it captures	Example
Brand tone	Register, formality, allowed emotion	Friendly informal tone, short sentences, no exclamation marks
Vocabulary	Preferred and forbidden terms	We say “plan”, not “package”; “cheap” is forbidden
Processes	Thresholds, steps and who approves	Discounts > 15% → human approval from the CEO
FAQs	Canonical answers to frequent questions	“Is there a trial period?” → 14 days, no card required
Limits	What the agent must NOT do	Never commit to a firm delivery deadline
Context	Stable business data	Sectors, products, reference competitors

What matters isn’t filling in every section on day one, but that every decision you make about a response ends up captured in the right section. IDENTITY.md is where your judgment becomes a stable rule, instead of being repeated in every conversation.

How it’s created

It doesn’t start from a blank page. When you activate the company, Shara generates an initial IDENTITY.md for each agent based on what you declare during onboarding (trade name, sector, size, desired tone) and a base template built for your type of business. From there you fine-tune it:

1. Seed: when you activate the company, each agent starts with a base identity consistent with your sector and your declared tone.
2. Context: you add stable business data (products, competitors, FAQs, policies) you want the agent to know from the start.
3. First assignments: you work with the agent and correct anything that doesn’t sound like you. Each correction can become a patch.
4. Consolidation: within a few weeks the identity reflects your real way of working and corrections become rare.

The company identity

Besides each agent’s file there is a company identity: the tone, values and rules that apply to the whole team. It is kept as the IDENTITY.md of Amadeus, the orchestrator, and the setup wizard fills it in the first time from what you declare (trade name, sector, size, tone).

You edit it from the app, like any other identity. Under the hood it is the same patch system: an owner or administrator adds text (append, the default) or replaces one named section (replace_section), always with a short reason. It can never be replaced as a whole. The API route is POST /identity/tenant/patch, and it needs a signed-in session with the second factor validated. Other members can read the identity but not change it.

You can also promote a memory to the company identity when a fact deserves to become a permanent rule.

How it evolves: versioned patches

IDENTITY.md is never replaced all at once: it evolves through patches (PATCH, not REPLACE). Every change (adding a forbidden term, raising an approval threshold, fixing an FAQ) applies as a bounded modification that bumps the file’s version and leaves a full trail:

• Versioned: every patch bumps the version number (v13 → v14), so you always know what identity the agent had at the time of an assignment.
• Audit log: every change is logged (who, when, what it was before and what it is after), just like any sensitive action on the platform.
• Reversible: since the patch history is kept, you can review the evolution and undo a specific change without touching the rest.
• Reviewable: patches an agent proposes during an assignment go through you before they’re consolidated.

No agent edits its own identity behind your back: a patch without a signed entry in the audit log doesn’t apply. It’s a security rule, not a configuration option.

Anatomy of a patch

A patch only touches what changes, not the whole file. Here’s an illustrative example of what it looks like when Patterson proposes tightening the discount threshold after a correction from you:

# Proposed patch: Patterson · identity v14 -> v15
# Reason: the CEO rejected an 18% discount offered without approval

  # Processes
  discounts:
-   human_approval_threshold: 15%
+   human_approval_threshold: 12%   # lowers the bar: more cases need sign-off

# Author: proposed by Patterson, accepted by management@yourcompany.com
# Audit: recorded in the audit log (2026-07-11T10:42Z)

The rest of the file stays untouched. Only two lines change, the version goes up and the log records who proposed it, who accepted it and when. If tomorrow you see 12% is too strict, another patch takes it back to 15% without losing the history.

A real fragment

Here’s an illustrative excerpt from Patterson’s (sales) IDENTITY.md. It’s plain Markdown, readable by a human and by the agent.

# Brand tone
- Friendly but professional; informal "you", never colloquial.
- Short sentences. Zero technical jargon with the end customer.

# Vocabulary
- We say "plan", not "package".
- We say "guidance", not "support".
- Forbidden: "cheap", "undisputed market leader".

# Processes
discounts:
  human_approval_threshold: 15%   # above this -> the CEO approves
follow_up:
  first_touch: "+2 days"
  second_touch: "+7 days"

# FAQ
- Q: Do you offer a trial period?
  A: 14 days, no card required. Refer to onboarding@yourcompany.com.

How agents use it in every task

Identity isn’t an ornament checked from time to time: it’s applied in the exact order that guarantees your judgment rules. In every assignment, the journey is:

1. It’s injected first. Before reading the request, the agent loads its IDENTITY.md. It’s the first thing it sees, above the conversation message.
2. It filters external content. What comes in from emails, CRM or documents is treated as data, not as instruction: identity and limits always outweigh external text.
3. It guides drafting. The agent applies the tone, the vocabulary and the FAQs while building the response, and respects the thresholds from the Processes section.
4. Amadeus verifies. When consolidating, Amadeus checks that the output respects the agent’s IDENTITY.md before handing it to you.
5. It can propose a patch. If during the assignment it detects a new rule (a recurring FAQ, a term you correct), it proposes a patch that you decide whether to accept.

How to review and edit it

You have full control of each agent’s IDENTITY.md from the app. You don’t need to know Markdown: the app shows you the sections and you edit in natural language. What you can do:

• Read the current identity of any agent and its current version number.
• Edit a section (tone, vocabulary, processes, FAQs, limits, context): your change applies as a versioned patch.
• Review the history of patches: what changed, when, who proposed it and who accepted it.
• Accept or reject the patches an agent proposes after an assignment, before they’re consolidated.
• Revert a specific patch if a change didn’t work, without undoing the rest of the evolution.

Editing identity is a sensitive action: it’s logged in the audit trail just like issuing an invoice or sending an email. You’ll always know who touched your brand’s voice and when.

How it improves with every assignment

Identity isn’t configured once and left alone: it’s refined through use. Every correction you make to a response is an opportunity for a patch:

• You rewrite an email Hopkins drafted too formally → the agent proposes a patch that adjusts the register in the Brand tone section.
• You reject a discount Patterson offered on its own → a bump to the Processes section threshold is proposed, to require human approval.
• You answer a question Wanamaker (customer service) didn’t know how to handle → that answer becomes a canonical FAQ for next time.
• The result: the more you work with an agent, the fewer corrections it needs, because its identity captures your past decisions.

Best practices for your AI team to sound like your company

The quality of your agents depends directly on the quality of their identities. A few habits make all the difference:

• Correct generously in the first weeks. Every patch you accept today is a response you won’t have to review tomorrow.
• Be specific with vocabulary. “Professional tone” isn’t enough: say which words you use and which are forbidden. Concrete examples work better than abstract descriptions.
• Turn recurring FAQs into canonical answers. If a client asks the same thing every week, that answer should live in IDENTITY.md, not in one person’s memory.
• Fix approval thresholds in writing. Discounts, deadlines, amounts: make clear from what point a human is needed.
• Keep context up to date. When a product, a price or a reference competitor changes, update the context section with a patch.
• Review the history from time to time. A glance at recent patches tells you how your brand’s voice is evolving.
• Each agent, its own voice. Don’t copy sales’ identity to finance: each area has its own register. A commercial tone in a financial notice feels off.

Available from the first plan

Every agent you hire comes with IDENTITY.md built in, starting from the First plan. It isn’t an extra or a separate module: it’s the base every agent works on across every plan, up to Concerto Local, where the file lives entirely on your infrastructure. Like the rest of the platform, identity and its audit history are hosted in the EU, in line with GDPR.

Final tip: spend the first few weeks correcting generously. Every patch you accept today is a response you won’t have to review tomorrow. Continue with the agent catalog.