Memory

Package: diary/. Agent memory is five plain-file components stored under the group directory.

Overview

All memory lives under groups/<folder>/. There is no database for memory. Files can be read, edited, and versioned with standard tools.

Before each container invocation, the gateway reads the diary and recent episodes and prepends them as XML blocks to the system prompt. Facts and user files are injected at the same time.

Components

1. diary/

Dated markdown files: YYYY-MM-DD.md. Each file has a YAML frontmatter block at the top:

---
summary: one-line summary of what happened today
---

Full diary content here...

diary.Read(groupDir, max) reads the most recent max files, extracts the summary: line from each, and returns an XML block with age labels (today, yesterday, N days ago, N weeks ago). This is prepended to the agent prompt as:

<knowledge layer="diary">
  <entry age="today">summary text</entry>
  <entry age="yesterday">summary text</entry>
  ...
</knowledge>

The gateway reads the last 14 days of summaries by default. The full diary file content is accessible to the agent via normal filesystem tools.

Diary entries are written by the /diary skill, the pre-compact hook, and every 100 turns.

2. episodes/

Archived session transcripts. Each episode file follows the same summary: frontmatter format as diary entries:

---
summary: brief description of what this session accomplished
date: 2024-01-15
---

[compressed session content]

Episodes are created by the compact-memories skill when the context window compacts. They are indexed by the /recall skill. store.ReadRecentEpisodes(groupDir, n) returns the most recent n episodes for injection.

Compression hierarchy: daily → weekly → monthly. Older episodes are compressed into higher-level summaries by the recall-memories skill.

3. facts/

Freeform markdown files. Every file under facts/ is fully injected into each agent invocation as:

<knowledge layer="facts">
[file content]
</knowledge>

No summarization. Write facts here for things the agent should always know: project conventions, external system details, recurring contacts.

4. users/

One markdown file per sender JID: users/<jid>.md. When the gateway knows the sender JID of the incoming message, it checks for a matching file and injects it:

<knowledge layer="user" jid="telegram:123456">
[file content]
</knowledge>

Write user files to give the agent context about specific people: preferences, history, ongoing projects.

5. Skills

Skills are SKILL.md files in the agent's ~/.claude/skills/ directory. They are invoked with /skill-name inside Claude Code. arizuko ships five built-in skills:

Skill	Invocation	Trigger condition
`diary`	`/diary`	End of work session, or when asked to write a diary entry
`compact-memories`	pre-compact hook	Fires automatically before Claude Code compacts the context window
`recall-memories`	`/recall`	When the agent needs to search past episodes
`users`	`/users`	When creating or updating a user file
`facts`	`/facts`	When updating the facts knowledge base

Skills are seeded into the session directory by seedSkills on first run. They are versioned via MIGRATION_VERSION and updated by numbered migration files in container/skills/.

Gateway injection

Before each container invocation, the gateway calls:

diary.Read(groupDir, 14) — last 14 diary summaries
ReadRecentEpisodes(groupDir, 5) — last 5 episode summaries
Read all facts/*.md files
Read users/<senderJid>.md if it exists

These are concatenated and passed as the systemPrompt field in the container input JSON.