The .agent/ folder specification

Status: v0.1 draft. The folder contract is the public surface; the daemon, the format, and the salience formula are all replaceable around it.

This page describes the .agent/ folder that dreamd maintains inside each repository. Every supported coding agent (Claude Code, Cursor, Cline) reads and writes to the same files via the dreamd-mcp server, so memory accrues regardless of which tool you used to earn it.

The contract is three things:

1. A folder layout every agent agrees on.
2. A frontmatter schema for each file type.
3. A set of promotion rules that move learning from raw logs into durable memory.

1. Folder layout

.agent/
├── episodic/            append-only observation log
│   └── AGENT_LEARNINGS.jsonl
├── semantic/            dream-cycle output — durable, agent-readable lessons
│   └── LESSONS.md
├── personal/            your preferences and decisions
├── working/             in-flight task context
└── .dreamd/             daemon state (gitignored)

• episodic/ is append-only. Entries here are observations, not yet trusted memory.
• semantic/LESSONS.md is what an agent reads at session start. Replaced atomically each dream cycle.
• personal/ holds user-private files (PREFERENCES.md, DECISIONS.md). Excluded from LLM calls unless --share-personal is set.
• .dreamd/ is daemon-private (WAL, state, cached indexes). Gitignored by dreamd init.

2. Frontmatter schema

Every episodic event written to AGENT_LEARNINGS.jsonl carries the following fields:

{
  "schema_version": "1.0",
  "id": "evt_<26-char-ulid>",
  "timestamp": "<ISO 8601>",
  "content": "...",
  "pain": 0.0,
  "importance": 0.0,
  "recurrence": 0,
  "skill_action": "..."
}

• pain and importance are floats on a 0–10 scale.
• recurrence is a non-negative integer: how many times this pattern has resurfaced.
• id is a evt_-prefixed Crockford ULID, minted by the daemon at write time.
• schema_version must be "1.0". A dreamd migrate path is required before changing it.

3. Promotion rules

episodic/AGENT_LEARNINGS.jsonl entries are evaluated on each dream cycle (dreamd dream or the background daemon’s own tick):

1. Score each observation against the salience formula:

   salience    = exp(-age_days / 14.0) × (pain / 10.0) × (importance / 10.0) × (1 + ln(1 + recurrence))
   final_score = bm25 × salience

2. Promote high-scoring entries into semantic/LESSONS.md, replacing it atomically.
3. Merge semantically near-duplicate entries; preserve the highest recurrence count.
4. Decay entries not seen recently; the salience score falls naturally as age_days grows.