Memory and character

An agent in Tally is more than a session transcript. Its home holds four things: an identity (who it is), a character (how it behaves), a memory (what it knows), and a history (what happened, as the encrypted event log). This page covers the two you interact with day to day: memory and character.

Both are per-agent documents. Both live inside the agent’s encrypted log. Both are injected into every launch, so the agent that comes up under tally continue, tally start, or tally run already knows what it knows and behaves how you told it to, regardless of which harness or model you picked this time.

Memory: what the agent knows

Memory is the agent’s curated knowledge document. It is:

• Owner-readable and owner-editable. It is a text document you can print, audit, correct, or redact at any time. It is not an opaque server-side embedding store.
• Encrypted in the log. Memory is stored in the agent’s encrypted event log, so it gets everything the log already has: encryption at rest, sync, and recovery alongside the rest of that agent’s history.
• Hash-chained provenance. Every saved version of the memory is a new hash-chained entry in the log. “Why does my agent believe X” has an inspectable answer instead of a shrug.

How memory grows: the reflect pass

You do not have to maintain the memory by hand (though you can). After each captured session, a background reflect pass distills durable knowledge from that session into the memory document. Reflection runs as a one-shot on your own harness and model: Tally is BYO-brain, so distillation uses the brain you already pay for, not a model we host.

Reflection is controlled in three places:

• Config defaults: auto_reflect and reflect_model in tally config set whether reflection runs and which model it uses. The reflect_model config key overrides the model passed on the command line.
• Per launch: pass --no-reflect to continue, start, or run to skip the reflect pass for that session.
• On demand: run the pass yourself with tally memory reflect.

# distill pending captured sessions into memory, explicitly
$ tally memory reflect --harness claude-code --model <model> vision

# set-and-forget defaults instead
$ tally config set auto_reflect true
$ tally config set reflect_model <model>

tally memory reflect requires --harness (one of claude-code, pi, codex) and --model. The launch verbs run this same pass in the background after capture.

Note

Capture is deterministic and primary; reflection is best-effort distillation on top. A skipped reflection loses nothing, because the captured session is already in the log and a later reflect pass can pick up the pending sessions.

Viewing and editing memory

# print the agent's current memory document
$ tally memory show vision

# open it in $VISUAL/$EDITOR; saving creates a new hash-chained version
$ tally memory edit vision

Both commands take an optional agent name. Omit it and they operate on the single-seat home (the default agent on a one-agent machine).

Editing is a first-class path, not a workaround. If the agent learned something wrong, you fix the document, and the correction is itself a new hash-chained version in the log.

Full command reference: tally memory.

Character: how the agent behaves

Character is the agent’s standing instructions and voice: the layer that makes an agent yours. Things like “you verify before claiming done,” “prefer small diffs,” or a role definition live here.

Character differs from memory in one important way: you write it; the agent does not. There is no reflect pass for character. It changes only when you edit it.

# print the agent's current character document
$ tally character show vision

# open it in $VISUAL/$EDITOR; saving creates a new version
$ tally character edit vision

Like memory, character is stored in the agent’s encrypted log, versioned on every save, and synced and recovered with everything else.

Full command reference: tally character.

Memory vs character, in one table

	Memory	Character
What it is	What the agent knows (project facts, learned preferences, self-knowledge)	How the agent behaves (standing instructions, voice, role)
Who writes it	The reflect pass, plus you (memory edit)	You (character edit)
How it changes	After captured sessions, via reflection on your own harness	Only when you edit it
Versioning	New hash-chained version per save	New version per save
Storage	Encrypted in the agent’s log	Encrypted in the agent’s log
Injected at launch	Yes, every launch	Yes, every launch

When injection happens

Every launch verb injects character and memory automatically:

• tally continue <agent> injects them alongside the agent’s newest portable context.
• tally run <agent> injects them before the one-shot task.
• tally start <agent> injects them too. A fresh start is a fresh session, not a fresh self: the new session begins with the agent’s character and memory already in place. Starting an agent means “same self, blank conversation.”

This is what makes the harness and model swappable. The self travels in the encrypted home; the harness is just where it runs today.

Tip

Character is agent-scoped, not repo-scoped. Repo-level instruction files (CLAUDE.md, AGENTS.md) belong to the repo and its git history. Put “how this agent behaves everywhere” in character; leave “how to work in this repo” in the repo.

Caution

Portability preserves who the agent is, not what it can do. A memory built while working under a strong model does not make a weaker model stronger, and harnesses differ in available tools. Expect the same self, not identical capability, across swaps.

Verifying the record

Because memory and character live in the hash-chained log, their integrity is checkable, not assumed:

# print the event count and whether the hash chain verifies
$ tally status

# inspect the local encrypted event log directly
$ tally log --help

If someone (or something) tampered with the stored history behind your back, the chain does not verify. This is the same property that makes the provenance claim honest: a memory version points back through the chain to the session that produced it.

Sync and recovery

Memory and character need no special handling within an agent. They are entries in that agent’s log, so they travel with everything else in it: pushed (sealed, as ciphertext) to the agent’s channel, pulled and hash-chain-verified on another device, and readable again once the agent’s identity is recovered.

The unit of sync and recovery is the agent, and there are two per-agent facts to get right:

• Each agent is its own seed, its own log, and its own recovery story. A named agent (tally start vision ...) has its own independent seed and its own home under <tally_home>/agents/<name>/; the base seat is a separate seat with a separate seed. Back up each agent you care about with tally backup <agent>. Backing up only the base seat does not protect your named agents: their seeds are not derived from it, and recovering the base phrase alone does not bring them back.
• A seed restores identity and keys, not content. Recovering an agent’s phrase on a new machine re-derives who the agent is. What it knows comes back via tally pull (within the relay’s bounded catch-up window) or by copying the agent’s encrypted log from a machine that still holds it.

There is no separate memory backup to manage and no separate character store to migrate; back up the agent and its memory and character come with it. See Multi-device sync for the per-agent recipe and What syncs, and what the cloud can see for exactly what leaves the machine.

Quick reference

$ tally memory show [AGENT]        # print the current memory document
$ tally memory edit [AGENT]        # edit in $VISUAL/$EDITOR; new hash-chained version
$ tally memory reflect \
  --harness <h> --model <m> [AGENT]  # distill pending captured sessions into memory

$ tally character show [AGENT]     # print the current character document
$ tally character edit [AGENT]     # edit in $VISUAL/$EDITOR; new version

$ tally config set auto_reflect true       # reflect automatically after capture
$ tally config set reflect_model <model>   # which model the reflect one-shot uses

In every case, [AGENT] defaults to the single-seat home when omitted.

Where to go next

• Command reference: tally memory and tally character
• The launch verbs that inject both: Continue, start, and run
• What leaves the machine when this syncs: What syncs, and what the cloud can see