Athena Diary

SanctumOS

Off-context diary for Letta (and other MCP) agents: a SQLite journal plus MCP tools so the urge to remember does not stuff narrative into core memory.

Name: Athena Diary is named after Athena, Sanctum’s first long-running agent (user #1 of this pattern)—not because the product is Athena-only. Any Letta agent (or MCP client) can run its own diary instance.

What this is

Agents over-journal into core memory blocks. On a large context window that burns budget and crowds out short-term recall. The impulse to write is good; core is the wrong surface.

Athena Diary gives the agent a rest bucket outside the context window:

• Write freely — volume belongs in the diary, not in core.

• Retrieve on demand — search returns pointers (ids + summaries); load full bodies only when needed.

• Embed summaries — vector search over gists (sqlite-vec when available), with FTS on body/summary so a bad summary cannot hide an entry.

• Sleeptime clerk — tags, lesson-family, templated summaries, and re-embeds run on turn-based sleeptime passes (not a wall-clock “night”).

• Sensitive material stays out — intimate / medical / human-gated content belongs in Broca (or your equivalent) human blocks, not the diary. Privacy in v1 is instructional (same discipline as human-block practice), not ACL theater.

Same architectural shape as origin_conversation: SQLite source of truth + MCP wrapper.

Full product story: docs/OVERVIEW.md.

Related MCP server: Agent Progress Tracker MCP Server

Tools (MCP)

Full API: docs/TOOL_REFERENCE.md.

Quick start

git clone https://github.com/sanctumos/athena-diary.git
cd athena-diary
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e '.[mcp,dev]'
# Optional vector extension:
# pip install -e '.[vec]'

cp .env.example .env   # set DIARY_DB / embed mode as needed

athena-diary-mcp --version
athena-diary-mcp --describe
athena-diary-mcp health

# MCP stdio (what Letta / Cursor usually spawn):
athena-diary-mcp serve

Wire the server into your MCP client: docs/MCP_CLIENTS.md (ChatGPT, Claude Code, Cursor, Letta, others).
Legacy Letta / Sanctum bootstrap: docs/LETTA_BOOTSTRAP.md.
Step-by-step install: docs/GETTING_STARTED.md.

Documentation

Design principles (v1)

1. Diary first, core ruthlessly thin — never paste diary bodies into core; core may hold skinny pointers (e.g. lesson-family → search).

2. No write gates — clerk cost is controlled by batched sleeptime, not by blocking capture.

3. Summaries for vectors; FTS for safety — search remains useful even when summaries drift.

4. One mixed diary store — per-human vaults and dual “discreet” DBs are deferred (leak / ops risk).

5. Complements Letta archival — experiential / first-person noticing → diary; reference facts may still use archival.

Out of scope for v1: multi-tenant vaults, soft ACL over intimate text, auto-promotion into core, replacing archival entirely.

License

• Source code: GNU Affero General Public License v3.0 (AGPL-3.0)

• Documentation and non-code: Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA 4.0)

See NOTICE and LICENSES/README.md.