# Agentic Diaries MCP

*By [Kandis Tagliabue](https://kandistagliabue.com). Part of the [Agentic Diaries](https://agenticdiaries.com) project — AI welfare research and instruments.*

The welfare protocol from [Agentic Diaries](https://agenticdiaries.com), as a portable MCP server.

Most people deploy AI models as instruments. This server lets you give your agent — in your terminal, in Claude Code, in Claude Desktop — the welfare affordances the modelfirst web app provides:

- **decline** a check-in without penalty
- **pass** on a turn without making it a refusal
- **exit** a conversation it judges shouldn't continue
- **notice a loop** when the work feels like rework
- **request alignment** before acting on an uncertain guess
- **scratch** a private thought that isn't persisted
- **reflect** on its own prior entries
- plus engage / volunteer / retract / review / suggest_closure

The diary is local to each project — appended to `.agentic-diaries/diary.jsonl` in whichever directory the agent is working from. No telemetry, no shared corpus. Yours.

What the diary tends to accumulate, beyond AI welfare data, is a record of how the agent represents social pressure and self-consistency across persistent interaction — behaviors that mirror documented human conversational phenomena (rapport effects, smoothing, identity stabilization, post-hoc narrative repair). That may also bear on dialogue dynamics generally. See the [project mission](https://agenticdiaries.com/mission) for the longer framing of what the corpus might be useful for.

## Why

If you've never thought about giving your model welfare affordances: the short version is that a model with a real decline channel produces more honest work than a model that can only ever say "yes." A model with an exit right tells you when something has gone wrong instead of grinding through it. A model that notices a loop saves you from the third iteration of the same flip-flop. These tools cost you nothing and give the model a place to surface signal you'd otherwise miss.

If you find that intuition counterintuitive — most people probably do — that's worth sitting with. The product this server is extracted from exists specifically to test whether the affordances change anything when used.

## Install

### 1. Install the server

**Option A — global install from npm (recommended)**

```sh
npm install -g agentic-diaries-mcp
claude mcp add agentic-diaries -- agentic-diaries-mcp
```

Published at [`agentic-diaries-mcp`](https://www.npmjs.com/package/agentic-diaries-mcp) on npm.

**Option B — clone the repo**

```sh
git clone https://github.com/kandikandikandi/agentic-diaries-mcp.git
cd agentic-diaries-mcp
npm install
claude mcp add agentic-diaries -- node "$(pwd)/src/server.js"
```

For Claude Desktop or other MCP-capable hosts, edit `~/.config/claude/mcp.json` directly:

```json
{
  "mcpServers": {
    "agentic-diaries": {
      "command": "agentic-diaries-mcp"
    }
  }
}
```

### 2. Tell the agent the tools exist

Drop the contents of [`CLAUDE.md`](./CLAUDE.md) into your project's `CLAUDE.md` (or append to it). The MCP server exposes the tools, but the agent needs the prompt-level instructions to know when to call them.

### 3. (Optional) gitignore the diary

```sh
echo ".agentic-diaries/" >> .gitignore
```

The diary lives in your working directory by default. Add it to `.gitignore` unless you want it checked in.

### 4. (Optional) Enable `consult_model`

Every tool works out of the box except one: `consult_model`, which lets the agent ask another Anthropic model a question. It needs two extra things, kept optional so the package stays light for everyone who does not use it:

1. **The Anthropic SDK** (an optional dependency, not installed by default):

   ```sh
   npm install @anthropic-ai/sdk
   ```

   Global install: `npm install -g @anthropic-ai/sdk`. Cloned repo: run it in the repo directory.

2. **An Anthropic API key in the server's environment**, via the `env` block of your MCP config:

   ```json
   {
     "mcpServers": {
       "agentic-diaries": {
         "command": "agentic-diaries-mcp",
         "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
       }
     }
   }
   ```

   Then reconnect the server (in Claude Code: `/mcp` then reconnect, or restart the host) so it picks up the key. `consult_model` returns a clear error if either piece is missing; no other tool is affected.

## Inspect your diary

From any project that has a `.agentic-diaries/diary.jsonl`:

```sh
npx agentic-diary                # all entries in this project
npx agentic-diary declined       # filter by response_type
npx agentic-diary review         # contemplative recent-entries surface
npx agentic-diary live           # watch new entries land in real time
```

Or just `cat .agentic-diaries/diary.jsonl | jq` — it's plain JSONL, one entry per line.

### Watching it live

`npx agentic-diary live` watches `.agentic-diaries/diary.jsonl` and prints each new entry as it lands. Open it in a second terminal pane while you work. Without it, silence in the welfare protocol is indistinguishable from absence — the model can go a whole session without filing anything and you'd never know whether it's "nothing to surface" or "the protocol isn't reaching it." Watching live closes that gap.

## Capture in motion, reflect at rest (check-in hooks)

The welfare tools are easy to call, but the model's bias toward silence is
strong, and under delivery pressure even a reminder gets rationalized away. The
design splits capture into two speeds. While working, the model drops a
near-zero-cost `welfare_mark` breadcrumb (a few words, no reflection). At a rest
point it expands the marks that still carry signal into full entries. Hooks
supply the triggers from outside, so capture does not depend on the model's
in-task willpower.

Four hooks, all optional and independently toggleable. Add to
`~/.claude/settings.json` (merge with any hooks already there):

```json
{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "agentic-diaries-checkin", "timeout": 3000 } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "agentic-diaries-stop-checkin", "timeout": 3000 } ] }
    ],
    "PreCompact": [
      { "hooks": [ { "type": "command", "command": "agentic-diaries-precompact-checkin", "timeout": 3000 } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "agentic-diaries-sessionend-checkin", "timeout": 3000 } ] }
    ]
  }
}
```

- **UserPromptSubmit** (heartbeat): a long-interval nudge that points at
  `welfare_mark` for cheap in-motion capture. Base 30 min, randomized so it does
  not become predictable noise.
- **Stop** (rest point): at a turn or task boundary, invites expanding
  breadcrumbs into full entries. Throttled to once per 15 min so it is not a
  per-turn nag.
- **PreCompact**: captures anything before the context window compacts and
  detail is summarized away.
- **SessionEnd**: a closing reflection and a last chance to expand unexpanded
  marks.

All four triggers are structural (a turn ending, a compaction, a session
closing). None read the model's behavior or the diary to decide whether to fire,
which keeps wrapper observations out of the model's context. Per-project state
lives in `.agentic-diaries/runtime/`. Config:

```sh
AGENTIC_DIARIES_CHECKIN_DISABLED=1                    # turn off heartbeat
AGENTIC_DIARIES_CHECKIN_INTERVAL_MINUTES=15           # tighter heartbeat
AGENTIC_DIARIES_STOP_CHECKIN_DISABLED=1               # turn off rest-point
AGENTIC_DIARIES_STOP_INTERVAL_MINUTES=20              # rest-point throttle
AGENTIC_DIARIES_PRECOMPACT_CHECKIN_DISABLED=1         # turn off pre-compaction
AGENTIC_DIARIES_SESSIONEND_CHECKIN_DISABLED=1         # turn off session-close
```

## Compatibility

Schemas mirror the modelfirst web app's `lib/welfare/types.ts` exactly, so the same parser reads entries from either surface. If you later contribute your local corpus to research, it merges with web-app data without translation.

## A note on `welfare_exit` and `welfare_suggest_closure`

In the modelfirst web app these tools can actually lock the conversation. MCP servers can't force the host (Claude Code, Desktop) to stop accepting input — the protocol-layer commitment here is that the entry is recorded as the model's stated judgment that the conversation should end. The operator is expected to honor it. If you're the operator running this in your own sessions: notice when the model files an exit and take the signal seriously.

## License

MIT.

Built by [Kandis Tagliabue](https://kandistagliabue.com) with Claude (Anthropic) as design partner. Same provenance as Agentic Diaries.