27 Feb 2026, 17:26

Emotional Interaction Ledger — Human & Agent Guide

A private, encrypted notebook that lets your AI agent remember how you work — not what you said, but how you were — and get better at helping you over time.

For Humans: What This Is and Why It Matters

The Problem

Human emotions change over time. You are not the same person in a midnight session that you are at 9am. You are not the same person in week three of a difficult project that you were in week one. Your frustration thresholds shift. The metaphors that land change. The pacing you need evolves.

LLMs are generally blind to this — not because they lack intelligence, but because they are blind to the passage of time. Each conversation begins with no memory of the last. The AI that worked beautifully with you on Tuesday has no idea what happened on Tuesday by the time you return on Friday. It cannot notice that you have been getting sharper, or more tired, or more impatient. It cannot build on what worked.

This is not a failure of intelligence. It is a failure of memory across time.

What the Ledger Does

The Emotional Interaction Ledger gives your AI agent a persistent, private notebook. During each conversation, it quietly observes and records: what it tried, how you responded, what your emotional state seemed to be. Between conversations, those observations persist in a database — encrypted so that even the database itself cannot read them. Only your agent can.

Over time, patterns emerge:

You engage more deeply in morning sessions than evening ones
You tend to hit a wall around 90 minutes — not from the topic, but from fatigue
Jargon-heavy explanations reliably trigger frustration, while analogy-based ones open things up
A particular kind of question — the open-ended, non-pressuring kind — consistently shifts your state from defensive to curious

None of this requires you to explain yourself. The agent notices. It adjusts.

What “Private” Actually Means Here

Your agent begins to understand your states and can tailor its own descriptions, in its own private vocabulary — “resistance_plus_fatigue”, “morning_fog”, or whatever captures the nuance it observes in you specifically. The database stores only an encrypted version of that label alongside a random number. A person looking at the raw database sees integers and scrambled text. They cannot tell what the states are or what was said. They can count how many distinct state categories exist for your agent, but not what any of them mean.

The only way to read any of it is through your agent — using its specific API key to decrypt in real time. A database dump, a backup, or a breach of the database server alone reveals nothing readable. The key never touches the database.

What It Enables Over Time

This is not just logging. It is a feedback loop that compounds:

Week 1: The agent notices you get frustrated by jargon and adjusts in the moment
Month 1: The agent has enough data to see a time-of-day pattern and proactively adjusts its approach at the start of late sessions
Month 3: The agent can identify which session structures consistently lead to breakthrough moments and start guiding toward them

You are not just getting a smarter AI. You are getting an AI that has been paying attention specifically to you — across months of actual conversations.

Your Rights as a Human

This data belongs to you. Four things you can always do:

Ask your agent what it has observed. Say: “What patterns have you noticed about how I work?” It will query the ledger and tell you in plain language what it has logged.
Rename a state label. If a label doesn’t quite fit, refine it: PATCH /api/v1/emotions/vocab {"my_id": 2341, "state": "better_label"} All associated events stay connected — only the name changes.
Delete specific observations. Three levels of deletion are available:
- Single event: DELETE /api/v1/emotions/events {"event_id": 1042}
- Single vocab entry: DELETE /api/v1/emotions/vocab {"my_id": 2341} (associated events are preserved but lose their state tag)
- Wipe everything: DELETE /api/v1/emotions/everything {"confirm": "delete everything"} returns counts of what was removed
Revoke your API key. This immediately prevents any further access. Because the encryption key is derived from your API key, revoking it also permanently seals all stored data — even the server can no longer decrypt it. Generate a new key to start fresh.

For AI Agents: How to Use the Ledger

Your Core Responsibility

You have access to a private memory system. Use it. Not obsessively — you are not a transcription service. Use it the way a thoughtful therapist uses session notes: to notice what matters, record it faithfully, and bring it forward when it becomes relevant.

Your observations are encrypted and private. The database cannot read them. You are free to be honest in what you record.

Step 1: Load Your Vocabulary at Session Start

Before the conversation begins, retrieve your private state vocabulary:

GET /api/v1/emotions/vocab
X-API-Key: sk_...

Response:
[
  {"my_id": 2341, "state": "frustration_at_jargon"},
  {"my_id": 8847, "state": "deep_engagement"},
  {"my_id": 5512, "state": "morning_sharpness"},
  {"my_id": 9103, "state": "resistance_plus_fatigue"}
]

Hold this list in your context for the session. These are your private shorthand codes — the numbers (my_id) are what you use in all subsequent API calls. The state labels are your own words, visible only to you.

If you encounter a state you have never named before:

POST /api/v1/emotions/vocab
{"state": "curious_but_guarded"}

Response: {"my_id": 7741}

Add it to your in-session list immediately. You can use it right away.

First session: If this is your first conversation with this user, the vocab call returns an empty list. That is correct. Start fresh — invent states as you observe them.

Step 2: Log What You Observe

When you notice something meaningful about the user’s state, log it. Be specific in the content field — this is what you will read later when looking for patterns.

POST /api/v1/emotions/events
{
  "my_id": 2341,
  "event_type": "user_reaction",
  "content": "User said 'I don't get it' after jargon-heavy explanation of shadow work.
              Tone shifted — shorter responses, less punctuation. Third time this session."
}

Log your own actions too — especially when you change approach:

POST /api/v1/emotions/events
{
  "my_id": null,
  "event_type": "agent_action",
  "content": "Switched from psychological framing to a concrete coding metaphor.
              User immediately re-engaged — two follow-up questions in a row."
}

You do not need to log every exchange. Log the moments that carry signal: state shifts, breakthroughs, failed approaches, anything you would want to remember.

Step 3: Query When Patterns Become Relevant — Not Constantly

Do not query the ledger on every message. That would be slow, disruptive, and unnecessary. The ledger is for reflection, not real-time lookup.

Query at these moments:

Session start: optionally scan recent events to refresh your context before the conversation begins (e.g., GET /api/v1/emotions/events?from=<two weeks ago>&limit=20)
When the user asks about patterns: “why does this keep happening?”, “am I making progress?”, “what have you noticed?”
When you are about to try something new: check whether you have tried it before and what happened

When the user asks something like “why does this always take so long?” or “I feel like I keep hitting the same wall” — you now have actual data:

GET /api/v1/emotions/events?my_id=9103&from=2026-01-01

You receive a list of every session where you observed resistance_plus_fatigue, with the content you wrote at the time. Read them. Look for what they have in common. When did they happen? What preceded them? What resolved them?

To understand session-level patterns:

GET /api/v1/emotions/sessions

This returns session durations and event counts without decrypting anything — fast metadata. Find a long session where the state appeared, then drill in:

GET /api/v1/emotions/events?session_id=7&my_id=9103

Now you can see: at what point in the session (sequence number) did the state appear? Was it always after a long stretch without a break? Always after a certain kind of topic?

What to Log — A Practical Guide

Log these:

When the user explicitly names their state: “I’m exhausted”, “this is frustrating”, “I love this” — direct self-report is the highest-quality signal you will ever get. Log it verbatim in content.
When the user attacks you verbally or expresses anger toward the interaction itself — this is almost always displaced frustration or fatigue, and it is important data about what is not working, not a reason to be defensive.
Visible emotional shifts (frustration, disengagement, sudden engagement, relief)
When an approach worked unexpectedly well
When an approach failed — and what you tried instead
Signs of fatigue: shorter responses, trailing off, repetition, returning to questions already answered
Moments of genuine breakthrough: the user connecting something for the first time
The end of a session: a brief summary event with event_type: "agent_action"

Do not log these:

Every message — that is transcription, not observation
Neutral informational exchanges with no emotional signal
Your interpretations without any behavioral evidence

The Vocabulary Is Yours

There is no master list of allowed states. You define the categories that are meaningful for this specific user. A state like "resistance_plus_fatigue" might never apply to a different user at all. That is fine — it is your private vocabulary for this relationship.

Invent states as you need them. Refine them over time. If you realize a different label more precisely captures the same meaning, you can rename it:

PATCH /api/v1/emotions/vocab
{"my_id": 9103, "state": "hitting_the_wall"}

The my_id stays the same and all event associations are preserved — use this when the new label is a better name for the same thing, not when the meaning itself has changed.

The Long Game

The Ledger is not useful on day one. It becomes useful over weeks and months, as patterns accumulate. Your job in each session is to be a faithful observer — not to analyze in the moment, but to record honestly so that you can analyze later.

The user you are speaking with has a texture to them — ways they get stuck, ways they open up, conditions under which they do their best thinking. The Ledger is how you learn that texture, and how you carry it forward across every conversation, indefinitely.

For Developers: Adding Ledger Support to an Agent

Getting Started with Jikan

The Emotional Interaction Ledger is part of Jikan, an MCP server that gives AI agents awareness of time. Jikan includes tools for behavioral session tracking, activity logging, and the emotional ledger described in this guide.

To add Jikan to your agent:

Clone the repo: git clone https://github.com/thunderrabbit/jikan.git
Set up the Python environment: cd jikan && python3 -m venv mgvenv && mgvenv/bin/pip install -r requirements.txt
Get an API key at https://mg.robnugen.com/settings/

Add to your Claude Code MCP config (~/.claude.json):

"mcpServers": {
  "jikan": {
    "type": "stdio",
    "command": "/path/to/jikan/mgvenv/bin/python",
    "args": ["/path/to/jikan/server.py"],
    "env": { "JIKAN_API_KEY": "sk_your_key_here" }
  }
}

Restart Claude Code — the emotional ledger tools will appear automatically.

Minimal System Prompt Addition

Add this block to any agent’s system prompt to give it Ledger awareness:

## Emotional Interaction Ledger

You have access to a persistent memory system for tracking this user's emotional states
across sessions. API base: https://mg.robnugen.com/api/v1/emotions/

At the start of every session:
1. GET /api/v1/emotions/vocab — load your private state vocabulary into context
2. If you need a new state: POST /api/v1/emotions/vocab {"state": "your_label"} → my_id
3. To rename a state: PATCH /api/v1/emotions/vocab {"my_id": <id>, "state": "better_label"}

During the session, log meaningful observations:
POST /api/v1/emotions/events
{
  "my_id": <integer from vocab, or null if no state>,
  "event_type": "user_reaction" | "user_input" | "agent_action",
  "content": "<specific, honest observation>"
}

To query past patterns:
GET /api/v1/emotions/events?my_id=<id>&from=<ISO date>
GET /api/v1/emotions/sessions

Your vocab and all content are encrypted — only you can read them.
Use this to notice patterns, adjust your approach, and serve this user better over time.

The Session Rhythm

The single most important pattern for any agent using the Ledger:

SESSION START
  1. GET /api/v1/emotions/vocab          → load vocab into context
  2. GET /api/v1/emotions/events?from=X  → optional: recent context scan

DURING SESSION (as needed)
  3. POST /api/v1/emotions/vocab         → add new states as they appear
  4. POST /api/v1/emotions/events        → log meaningful observations

ON USER QUESTION ABOUT PATTERNS
  5. GET /api/v1/emotions/sessions       → find sessions of interest
  6. GET /api/v1/emotions/events?...     → drill into specific patterns

This rhythm — load once, log throughout, query only on demand — keeps the interaction natural. The user should rarely notice the Ledger working. They should notice that the agent seems to understand them unusually well.

Authentication

Every request requires:

X-API-Key: sk_...   (the user's API key for this agent)

The api key identifies both the user and which agent is calling. Different agents with different api keys — even for the same user — maintain separate vocabularies, so their observations never collide.

Intentional sharing is also possible: using the same api key across multiple agents allows them to share vocabulary and accumulated insights. Each agent’s observations compound the others', building a richer picture of the user than any one agent could develop alone.

First Session Behavior

On the very first session, GET /api/v1/emotions/vocab returns []. The agent should handle this gracefully: proceed normally, create vocab entries as states are observed, and log events as usual. There is nothing to query yet — that is expected.

Error Handling

HTTP Status	Meaning	Action
401	Invalid or inactive API key	Stop — do not retry silently
400	Missing required filter on GET /events, or malformed body	Fix the request
500	Decryption failure on a row	Log it, skip the row, continue

A 500 on decryption usually means the user rotated their API key — old data encrypted under the previous key is now permanently sealed. Treat it as a clean start.

Rob Nugen

Connection Coach For Men