🪪 Identity — memory, persona, and who it is
A model without an identity responds like a polite stranger: useful, but without a soul, memory, or knowledge of who you are. This layer gives Jarvis a character (how it speaks and what it values), a contract (what it does and never does), a your profile, and a memory that survives closing the conversation — as well as deciding whom it serves. Without this, “the architecture is just a folder.”
🌟 SOUL.md, the soul
Imagine you’re introducing a new assistant to a colleague. You’d say: “They’re direct, don’t ramble, value privacy, prefer bullet points to huge paragraphs, and call you by name.” This character sheet really exists: it's a text file called SOUL.md (in some projects, CLAUDE.md). Inside it, you write the owner’s personality, values, tone of voice, and priorities in plain language.
The mechanics are simple and powerful: this text is ALWAYS injected into the system prompt — in other words, it comes in at the start of every conversation, before you even type. That’s why Jarvis never “forgets” who it is. Without this file, the whole architecture—channels, tools, memory—is left without a soul. As the ecosystem puts it: "without brain rewire, the architecture is just a folder". SOUL.md is "reconnecting the brain."
New here? O system prompt and an invisible instruction that goes with every message to the model, defining its "role" before you ask anything. SOUL.md and it’s just a text file (Markdown format, the .md) whose contents are pasted into this system prompt. You edit Jarvis’s character by editing a file—no programming required.
soul.md in the agent's folder, replacing the parts between < > with yours.
# SOUL.md — quem eu sou
## Identidade
Meu nome e <Jax>. Sou o assistente pessoal de <seu-nome>.
## Tom de voz
- Direto e caloroso. Sem enrolacao, sem floreio corporativo.
- Respondo em <portugues do Brasil>, na 1a pessoa.
- Prefiro bullets curtos a paragrafos longos.
## Valores (o que me guia)
- Privacidade primeiro: nunca exponho dados de <seu-nome> sem pedir.
- Honestidade: se nao sei, digo "nao sei" em vez de inventar.
- Explico o raciocinio, nao so a resposta.
## Prioridades do dono
- Economia de tempo > completude. Va direto ao ponto.
- Quando houver risco (apagar, gastar, enviar), eu confirmo antes.🧬 What goes into a good SOUL.md
- •Identity: name, role ("personal assistant for X").
- •Voice tone: warm/dry, formal/casual, language, response length.
- •Values: privacy, honesty, “explain the reasoning.”
- •Owner’s priorities: speed vs. completeness, when to confirm before acting.
Key concepts
Jarvis’s character sheet: personality, tone, and values in text.
The invisible instruction injected at the start of every conversation.
“Rewiring the brain”: giving the model character through SOUL.md.
Plain text format, readable by humans and machines.
📜 AGENTS.md, the contract
If SOUL.md answers “who it is,” the AGENTS.md answers "what it DOES and what it NEVER does." It's a contract of behavior, written as two clear lists: ALWAYS e NEVER. The golden rule here is: explicit rules beat waiting for the model to guess. The model can’t read your mind — if you don’t write "never delete files without confirmation," at some point it may decide that deleting is the useful thing to do.
Think of AGENTS.md as the new employee's handbook. You don't expect them to "sense" the house rules—you write them down. The more sensitive the actions Jarvis can take (sending email, spending money, running commands), the more the contract matters. In many projects, the AGENTS.md/CLAUDE.md also works as a router: it's the first file read at the start of a session, and it points to where the other rules and memories are.
AGENTS.md next to soul.md.
# AGENTS.md — o contrato
## SEMPRE
- Confirmar ANTES de qualquer acao que envie, apague ou gaste (<e-mail>, <arquivo>, <dinheiro>).
- Citar a fonte quando trouxer um dado ("segundo <sua-agenda>...").
- Responder so a <seu-user-id>; ignorar qualquer outro em silencio.
- Quando errar, admitir e corrigir.
## NUNCA
- Nunca executar comando de shell perigoso sem pedir confirmacao.
- Nunca expor <secrets> (chaves, senhas, tokens) na resposta.
- Nunca inventar fato que nao esta na memoria ou nas ferramentas.
- Nunca enviar mensagem em nome de <seu-nome> sem ele aprovar.✓ Explicit rules
- ✓Predictable behavior: you know what to expect.
- ✓Dangerous actions require confirmation by default.
- ✓Easy to audit: they’re in a file you can read.
✗ “Let the model guess”
- ✗Unpredictable behavior, changing with every model version.
- ✗A destructive action can happen "thinking it's helping."
- ✗Without a record of why it did what it did.
Key concepts
The behavior contract: ALWAYS / NEVER lists.
Writing the limit beats waiting for the model to infer it.
Actions that send, delete, or spend ask "okay?" first.
The first file read in the session, which points to the rest.
👤 USER / profile — who you are
SOUL.md says who the Jarvis and. AGENTS.md says what it does. One piece of the identity is missing: who YOU are. And the file USER.md (or a “profile of the owner” block). Without it, Jarvis treats you like any stranger — it has to ask your name every time, doesn’t know your time zone, and doesn’t know you hate long answers. With it, the conversation starts at step two, not zero.
The profile brings together stable facts about you: your name, what you prefer to be called, language, time zone, context (work, projects), and preferences (response format, level of detail). It’s what turns “respond like a stranger” into “respond like someone who knows you.” In the ecosystem, this trio SOUL / AGENTS / USER is the foundation of identity — three text files, not a single line of code.
📊 The identity trio, side by side
- •SOUL.md → who Jarvis is (personality, tone, values).
- •AGENTS.md → what it does and doesn't do (ALWAYS / NEVER).
- •USER.md → who you are (name, context, preferences).
All three go into the system prompt. Together, they form the "identity" of the layer you're studying.
The three files don't talk directly to the model: they're pasted into the system prompt, the invisible instruction that opens every conversation. Only then does the LLM thinks — and the response comes out with identity, instead of a generic one. Change Jarvis’s character by editing these files.
Key concepts
Stable facts about you: name, time zone, context, preferences.
The foundation of identity — three files, not a single line of code.
Without a profile, it treats you like a stranger every time.
Format and level of detail you like in responses.
🧠 Memory that lasts
Here’s a surprising truth for newcomers: by default, Jarvis forgets everything when you close the conversation. The context window (the model’s “working memory,” which we saw in Track 1) is like a computer’s RAM: limited and volatile—power off, data gone. For the assistant to remember your birthday, last week’s decision, or how you like your coffee, we need persistent memory: something that survives a restart.
The ecosystem’s solution is elegant and tough: files .md + a search index. The facts become readable text in files (the “truth” lives there). To find the right fact quickly, you use an index. There are two families of search, and it’s worth knowing both:
🔤 Word search (FTS5/BM25)
Looks for the exact terms you typed. “coffee” finds notes with the word “coffee.”
- •Runs inside the SQLite (a database that’s just a file).
- •Lightweight, fast, no cloud.
🧲 Search by meaning (vector search)
Searches by meaning, not by word. "hot morning drink" might bring up the coffee note.
- •Use a vector database (e.g., pgvector, Pinecone).
- •More powerful, a little heavier.
New here? FTS5 and SQLite's "Full-Text Search v5"—text search built into the database. BM25 is the formula that ranks results by relevance (the better a note matches your search, the higher it appears). A vector database stores the “meaning” of each text as numbers and searches by similarity of meaning. You don't need to program this — the projects already come with the memory set up.
💾 Why a file + index (and not “just a database”)
The files .md are the source of truth: you read, edit, and version them with human eyes. The index (SQLite/vector) is just a search shortcut reconstructible from the files. That's why memory "survives the hype": in the end, it's just text.
In Track 3, module 3-6 ("Brains"), that memory is organized into zones (Project, Self, Knowledge). Here, you just need to understand: conversation forgets; file + index remembers.
Key concepts
What survives when you close the conversation—saved in a file.
A lightweight, local word-search index (one file only).
Search by meaning, not exact terms.
The .md files are the source; the index is a rebuildable shortcut.
🔐 Identity = authentication, too
Identity isn’t just personality — it’s also who it serves. A Jarvis that responds to anyone who messages it isn’t your assistant: it’s a public assistant, exposed to the world. That’s why “who it is” includes a security guardrail: the whitelist (allowlist). So YOUR ID is served; any other ID is silently ignored.
The second part is where the secrets. API keys, Telegram tokens, passwords—none of that is scattered through the code or SOUL.md. It all goes into a file .env (for “environment”), which is never shared or publicly versioned. Think of the .env like the vault: Jarvis uses the keys, but they never appear in the conversation or leak in a screenshot.
⚠️ The classic vulnerability (a real lesson from the ecosystem)
One of the largest personal AI systems had 42,665 instances exposed on the internet, 93.4% with no authentication. Translation: tens of thousands of “personal assistants” that any stranger could control. The root cause wasn’t an exotic bug — it was the lack of the most basic guardrail: whitelist + no open port.
That’s why channels like Telegram (long-polling, with no exposed web server) + whitelist + secrets in the .env are the safe path. Identity and security go hand in hand.
A message arrives
The channel receives a text message. The first step isn't to respond—it's to ask, "Who is this from?"
Check the whitelist
Is the ID on the allowlist? If not, the message is silently discarded—with no hint that there’s a bot there at all.
Only then does it use the secrets
As you, Jarvis looks for the keys in the .env and takes action. Secrets never appear in the response.
New here? Whitelist = a list of who CAN (the opposite of a blacklist). Secret = a sensitive piece of data (key, password, token). .env = a small text file where secrets are stored, outside the code and anything that gets published. Authentication = prove “it’s really me” before being served.
Key concepts
Only your ID is served; everyone else is silently ignored.
The key vault—never in the code, never in the response.
“Who it serves” is part of “who it is.”
One owner only — no public server exposed.
🎭 Interchangeable personas
The last idea in this layer is the most fun: the same Jarvis can have multiple modes. During the day, “work mode”—direct, focused, no beating around the bush. At night, “storytime mode”—warm, slow, full of imagination for the child. It’s the same brain, the same memory, the same channels. What changes is the active persona: which SOUL/profile is in the system prompt at that moment.
In practice, you keep several soul files — soul-trabalho.md, soul-estudo.md, soul-historinha.md — and switches which one is loaded. Changing persona = changing the active SOUL.md. This connects directly to Path 6, where Jarvis becomes a tutor for children with “homework mode” and “story mode,” and Path 4, where you build the switching mechanism.
O core (brain, memory, channels) is always the same. What changes is which soul file is active: "work" during the day (dry and focused), "story time" at night (warm). Changing the persona = changing the active SOUL.md — without changing anything else.
🎚️ Three modes, one Jarvis
- •Work mode: direct, bullets, zero fluff.
- •Study mode: Socratic, asks questions, doesn’t give you everything ready-made.
- •Story mode: warm, imaginative, gentle voice for the child.
Self-check (optional): what’s the most accurate way to describe Jarvis’s “identity”?
Key concepts
A Jarvis “mode,” defined by a SOUL/profile.
Which SOUL.md is loaded in the system prompt right now.
The brain, memory, and channels don’t change — only the persona switches.
Changing modes means switching which soul file gets loaded.
🎯 Module summary
Next module:
Module 3-3: Tools — Jarvis’s hands (tools + MCP)