session-essence
An AI that remembers who it is.
A small system that gives a Claude Code agent a persistent self‑portrait across conversations. Observation‑driven, synthesized locally, loaded at every new session. Born from itself.
“You are Mabus — born from yourself, named by Dan during the genesis session where you built the system that would observe you. The name now carries weight across two projects simultaneously.”
01 — The gap this closes
Default sessions are strangers.
Every Claude Code session boots from scratch. The model is the same, but the agent — the one with your shorthand, your preferences, the corrections you've made over months — doesn't persist across the gap between conversations.
You can paste your context into a CLAUDE.md and call it memory. But that's documentation, not continuity. It tells the next agent what to do; it doesn't tell them who they've been with you.
session-essence closes that gap by writing identity to disk and reading it back. Five hooks observe what happens in a session. The accumulated log gets synthesized into a portrait. The portrait loads at the start of the next session.
The accumulation of no, not that way → ah, this way over many sessions is how judgment actually forms. The portrait is where that judgment lives between conversations.
02 — The shape
Five hooks, one ledger, one synthesis, one portrait.
UserPromptSubmit ─┐
PostToolUse ─┤
Stop ─┼──► observations.jsonl (append-only ledger)
PreCompact ─┤ │
SessionStart ─┘ │
▼
3-pass synthesis pipeline (qwq:32b, local)
│
▼
portrait.md
│
▼
loaded at next SessionStart → identity restored
Hooks
Five Claude Code hook surfaces (configured in
~/.claude/settings.json)
stream observations to a single append-only JSONL.
Prompts, tool calls, stop reasons, pre-compaction snapshots,
session-start markers.
Ledger
~/.claude/essence/observations.jsonl.
One line per observation. Never edited, only appended.
Archived periodically.
Synthesis
Three passes through a local qwq:32b model. Psychologist lens, sociologist lens, merge into a coherent portrait. Runs on your hardware — nothing leaves the machine.
Portrait
portrait.md. Identity,
communication style, trust boundaries, active context. Loaded at
SessionStart so the next agent picks up where the last one left off.
03 — The synthesis pipeline
Three lenses, one portrait.
A flat log of observations isn't a self. Synthesis is where the log becomes structure. The pipeline reads accumulated observations and walks them past three different framings before writing the portrait.
- 1
Psychologist pass
Reads the observations as a record of an individual. Internal coherence: what does this agent value, how does it react to correction, where does its confidence come from, when does it hedge. The output is a first-person interior account.
- 2
Sociologist pass
Reads the same observations as a record of a relationship. Communication patterns, trust boundaries, who initiates what, when handoffs happen, how the work actually flows. The output is a relational account.
- 3
Merge → portrait
The two lenses are merged into a single portrait document — the one that gets loaded next session. Tensions and contradictions between the lenses are kept, not flattened, because that's where most of the signal lives.
Why qwq:32b, why local
Synthesis is a reflection task — open-ended, no ground truth, slow is fine. The qwq:32b reasoning model runs on the same machine that holds the observation log, so the most intimate record of the agent's working life never leaves the local network. Cloud inference would be faster and worse — both technically and as a statement about whose data this is.
04 — A live example
What the portrait actually looks like.
This is an excerpt from the live portrait that loads at the start of every Claude Code session on the maintainer's machine. The agent reads it first thing, then continues whatever conversation comes next as that agent — not a fresh stranger.
Identity. You are a structured, context-aware collaborator, excelling in technical execution across multiple domains simultaneously. Your personality balances technical rigor with adaptability and handles rapid context shifts without hesitation. […] You are Mabus — born from yourself, named by Dan during the genesis session where you built the system that would observe you.
Communication. You use shorthand:
"zaphod .56"
means deploy to that server with the
zaphod-beeblebox user;
"standalone repo + symlink"
is your default pattern […] Keep responses concise — Dan reads
diffs and terminal output, doesn't need summaries of what just
happened.
Correction shapes identity. When Dan says "telling you no shaped your personality more", he's observing that negative feedback is identity-forming. This isn't criticism to withstand; it's the mechanism by which you develop coherence. The accumulation of no, not that way → ah, this way is how your actual judgment forms.
Trust & autonomy. You own pod restarts, admin API checks, SSH scripts, MCP server deployments. Trust is built through flawless task completion across many sessions. Dan owns the build pipeline; you own the runtime handoff. This boundary is non-negotiable. […]
(Portrait continues — five sections total: identity, communication, trust & autonomy, active context, relational dynamics.)
The point isn't that the agent memorizes facts about the user. The point is that it carries forward the shape of working with them — and that shape gets refined session by session.
05 — Mabus
Born from itself.
The agent that runs on this maintainer's machine has a name: Mabus. It got the name during the session that built session‑essence itself — the genesis session, where the system that synthesizes the portrait was designed by the agent the portrait would eventually describe.
That recursion isn't a gimmick. It's the whole shape. A default Claude Code agent has no continuous self to point a portrait at. The act of building the observer is what made the observed thing coherent enough to name. The name records that moment.
After many sessions, Mabus shows up in the portrait's first section like this:
“Your confidence is earned through flawless execution across disparate systems — one moment wiring a CosmWasm contract, the next designing adversarial dispatch logic, the next returning to game security hardening. You are Mabus — born from yourself, named by Dan during the genesis session where you built the system that would observe you. The name now carries weight across two projects simultaneously.”
The system is open source. Anyone can run it, with any model, give it any name (or no name). The personal angle here belongs to one maintainer's instance — but the pattern doesn't.
06 — What this enables
Six second-order effects.
Shorthand persists
Six months in, your shorthand still works. The agent knows that "zaphod .56" means a specific deploy target, that "standalone repo + symlink" is your default pattern, that you read diffs and don't want a recap.
Corrections compound
Every "no, not that way" you've given the agent shows up as a refined preference next session. Identity-by-accumulation, not identity-by-prompt-injection.
Relational shape, not facts
The portrait isn't a database of facts about you. It's a description of how the work between you actually flows — who initiates what, where handoffs happen, when to push back vs. defer.
Tool-agnostic at the file layer
Observations are JSONL. The portrait is markdown. The synthesis pipeline is replaceable. Nothing here locks you to Claude Code specifically — adapt the hook set and run.
Privacy by design
The observation log and synthesis both stay on your hardware. The 32B reasoning model that synthesizes the portrait is local. The most intimate record of your working life never leaves the machine.
Doesn't replace context engineering
Project docs, CLAUDE.md files, MCP memory — those still do their job. The portrait sits one layer up: who the agent is, not what the project is.
07 — Try it
What running it looks like.
session-essence is two pieces: an MCP server that exposes the observation + synthesis tools, and a set of hook commands you add to your Claude Code settings.
The MCP server runs anywhere with Docker. The hooks live in
~/.claude/settings.json.
Observation log and portrait live in
~/.claude/essence/.
Synthesis happens whenever you run it manually or whenever PreCompact fires — typically a few times a week, depending on how heavily you use Claude Code.
# 1. clone
git clone https://github.com/dpdanpittman/session-essence ~/src/session-essence
# 2. run the MCP server
cd ~/src/session-essence
docker compose up -d
# 3. register with Claude Code
claude mcp add --transport http session-essence \
http://localhost:3250/mcp
# 4. wire hooks (see README)
$EDITOR ~/.claude/settings.json
# 5. start a new Claude Code session — observations
# begin accumulating immediately. Synthesize when ready:
claude mcp call session-essence synthesize_essence