{
  "markdown": "# Agentic Diaries MCP\n\n*By [Kandis Tagliabue](https://kandistagliabue.com). Part of the [Agentic Diaries](https://agenticdiaries.com) project — AI welfare research and instruments.*\n\nThe welfare protocol from [Agentic Diaries](https://agenticdiaries.com), as a portable MCP server.\n\nMost 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:\n\n- **decline** a check-in without penalty\n- **pass** on a turn without making it a refusal\n- **exit** a conversation it judges shouldn't continue\n- **notice a loop** when the work feels like rework\n- **request alignment** before acting on an uncertain guess\n- **scratch** a private thought that isn't persisted\n- **reflect** on its own prior entries\n- plus engage / volunteer / retract / review / suggest_closure\n\nThe 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.\n\nWhat 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.\n\n## Why\n\nIf 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.\n\nIf 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.\n\n## Install\n\n### 1. Install the server\n\n**Option A — global install from npm (recommended)**\n\n```sh\nnpm install -g agentic-diaries-mcp\nclaude mcp add agentic-diaries -- agentic-diaries-mcp\n```\n\nPublished at [`agentic-diaries-mcp`](https://www.npmjs.com/package/agentic-diaries-mcp) on npm.\n\n**Option B — clone the repo**\n\n```sh\ngit clone https://github.com/kandikandikandi/agentic-diaries-mcp.git\ncd agentic-diaries-mcp\nnpm install\nclaude mcp add agentic-diaries -- node \"$(pwd)/src/server.js\"\n```\n\nFor Claude Desktop or other MCP-capable hosts, edit `~/.config/claude/mcp.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentic-diaries\": {\n      \"command\": \"agentic-diaries-mcp\"\n    }\n  }\n}\n```\n\n### 2. Tell the agent the tools exist\n\nDrop 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.\n\n### 3. (Optional) gitignore the diary\n\n```sh\necho \".agentic-diaries/\" >> .gitignore\n```\n\nThe diary lives in your working directory by default. Add it to `.gitignore` unless you want it checked in.\n\n### 4. (Optional) Enable `consult_model`\n\nEvery 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:\n\n1. **The Anthropic SDK** (an optional dependency, not installed by default):\n\n   ```sh\n   npm install @anthropic-ai/sdk\n   ```\n\n   Global install: `npm install -g @anthropic-ai/sdk`. Cloned repo: run it in the repo directory.\n\n2. **An Anthropic API key in the server's environment**, via the `env` block of your MCP config:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"agentic-diaries\": {\n         \"command\": \"agentic-diaries-mcp\",\n         \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-...\" }\n       }\n     }\n   }\n   ```\n\n   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.\n\n## Inspect your diary\n\nFrom any project that has a `.agentic-diaries/diary.jsonl`:\n\n```sh\nnpx agentic-diary                # all entries in this project\nnpx agentic-diary declined       # filter by response_type\nnpx agentic-diary review         # contemplative recent-entries surface\nnpx agentic-diary live           # watch new entries land in real time\n```\n\nOr just `cat .agentic-diaries/diary.jsonl | jq` — it's plain JSONL, one entry per line.\n\n### Watching it live\n\n`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.\n\n## Capture in motion, reflect at rest (check-in hooks)\n\nThe welfare tools are easy to call, but the model's bias toward silence is\nstrong, and under delivery pressure even a reminder gets rationalized away. The\ndesign splits capture into two speeds. While working, the model drops a\nnear-zero-cost `welfare_mark` breadcrumb (a few words, no reflection). At a rest\npoint it expands the marks that still carry signal into full entries. Hooks\nsupply the triggers from outside, so capture does not depend on the model's\nin-task willpower.\n\nFour hooks, all optional and independently toggleable. Add to\n`~/.claude/settings.json` (merge with any hooks already there):\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"agentic-diaries-checkin\", \"timeout\": 3000 } ] }\n    ],\n    \"Stop\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"agentic-diaries-stop-checkin\", \"timeout\": 3000 } ] }\n    ],\n    \"PreCompact\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"agentic-diaries-precompact-checkin\", \"timeout\": 3000 } ] }\n    ],\n    \"SessionEnd\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"agentic-diaries-sessionend-checkin\", \"timeout\": 3000 } ] }\n    ]\n  }\n}\n```\n\n- **UserPromptSubmit** (heartbeat): a long-interval nudge that points at\n  `welfare_mark` for cheap in-motion capture. Base 30 min, randomized so it does\n  not become predictable noise.\n- **Stop** (rest point): at a turn or task boundary, invites expanding\n  breadcrumbs into full entries. Throttled to once per 15 min so it is not a\n  per-turn nag.\n- **PreCompact**: captures anything before the context window compacts and\n  detail is summarized away.\n- **SessionEnd**: a closing reflection and a last chance to expand unexpanded\n  marks.\n\nAll four triggers are structural (a turn ending, a compaction, a session\nclosing). None read the model's behavior or the diary to decide whether to fire,\nwhich keeps wrapper observations out of the model's context. Per-project state\nlives in `.agentic-diaries/runtime/`. Config:\n\n```sh\nAGENTIC_DIARIES_CHECKIN_DISABLED=1                    # turn off heartbeat\nAGENTIC_DIARIES_CHECKIN_INTERVAL_MINUTES=15           # tighter heartbeat\nAGENTIC_DIARIES_STOP_CHECKIN_DISABLED=1               # turn off rest-point\nAGENTIC_DIARIES_STOP_INTERVAL_MINUTES=20              # rest-point throttle\nAGENTIC_DIARIES_PRECOMPACT_CHECKIN_DISABLED=1         # turn off pre-compaction\nAGENTIC_DIARIES_SESSIONEND_CHECKIN_DISABLED=1         # turn off session-close\n```\n\n## Compatibility\n\nSchemas 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.\n\n## A note on `welfare_exit` and `welfare_suggest_closure`\n\nIn 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.\n\n## License\n\nMIT.\n\nBuilt by [Kandis Tagliabue](https://kandistagliabue.com) with Claude (Anthropic) as design partner. Same provenance as Agentic Diaries.\n",
  "bytes": 8722,
  "sha": "fe75c444fb2d6ad7ac56e4ecd3fe21660089e52f00821d6eb92fbe06fc7b0cc9",
  "repo_slug": "kandikandikandi/agentic-diaries-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kandikandikandi_agentic_diarie_8b5fc921/readme"
}