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.

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, Carnegie (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: Kotler’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.

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.

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

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.

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.

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.

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

# Parche propuesto: Carnegie · identity v14 -> v15
# Motivo: el CEO rechazo un descuento del 18% ofrecido sin aprobacion

  # Procesos
  descuentos:
-   umbral_aprobacion_humana: 15%
+   umbral_aprobacion_humana: 12%   # baja el liston: mas casos requieren visto bueno

# Autor: propuesto por Carnegie, aceptado por adrian@tuempresa.com
# Auditoria: aud_9Kx2mP (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.

Here’s an excerpt from Carnegie’s (sales) IDENTITY.md. It’s Markdown with a metadata header: readable by a human and by the agent.

---
agente: Carnegie            # Ventas
identity_version: v14        # se incrementa con cada parche
tier_preferido: Sonata       # escala a Symphony en propuestas
---

# Tono de marca
- Cercano pero profesional; tuteo, nunca coloquial.
- Frases cortas. Cero jerga tecnica con el cliente final.

# Vocabulario
- Decimos "plan", no "paquete".
- Decimos "acompanamiento", no "soporte".
- Prohibido: "barato", "lider indiscutible del mercado".

# Procesos
descuentos:
  umbral_aprobacion_humana: 15%   # por encima -> aprueba el CEO
seguimiento:
  primer_toque: "+2 dias"
  segundo_toque: "+7 dias"

# FAQ
- P: Ofreceis prueba gratis?
  R: 14 dias sin tarjeta. Deriva a onboarding@tuempresa.com.

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.

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.

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 Kotler drafted too formally → the agent proposes a patch that adjusts the register in the Brand tone section.
• You reject a discount Carnegie offered on its own → a bump to the Processes section threshold is proposed, to require human approval.
• You answer a question Carlzon (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.

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.

Every agent you hire comes with IDENTITY.md built in, starting from the First plan (€129/month). It isn’t an extra or a separate module: it’s the base every agent works on across every plan, up to Concerto Local (€999/month), 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.