Continuity System

Agenties treats Claude sessions as execution contexts, not as the source of truth. Long-project memory lives on disk so a new orchestrator, Codex conversation, or sub-agent can recover the project state without asking the user to retell the whole story.

Context order

Fresh sessions should orient from the smallest durable sources first, then load deeper material only when the current task needs it.

Priority	Source	Use
1	`.agenties/continuity/journal.md`	Recent chronological work: what happened today, yesterday, and this week.
2	`.agenties/continuity/index.md`	Project map: important decisions, features, fixes, and where to read more.
3	`.agenties/shared/state.json`	Current objective, active agents, open work, and recent decisions.
4	`issues/goals`	Backlog, goal execution state, priorities, and completion status.
5	`.agenties/reports/*.md`	Deep design, audit, QA, and agent completion reports.
6	Obsidian / NotebookLM	Human-readable knowledge and optional semantic recall.

Continuity journal

The continuity journal is a compact diary grouped by date. It records significant completions, paths, summaries, and next steps.

Path

.agenties/continuity/journal.md

The orchestrator emits a hidden structured completion block when it finishes meaningful work. Agenties strips that block from the visible chat and writes the journal entry automatically.

Tip:The journal answers: "what happened recently?" It should stay short enough to inject into startup context without token bloat.

Continuity index

The continuity index is a table of contents for important project context. It points to reports, issues, files, and follow-up paths instead of copying full details.

Path

.agenties/continuity/index.md

Note:The index answers: "where should I look?" The journal answers: "what just happened?"

Startup context

Fresh orchestrator sessions use build_init_context to assemble a compact startup snapshot from shared state, recent journal entries, the continuity index, and configured vault excerpts.

Tool	Purpose
`build_init_context`	Build a capped startup snapshot for a new session.
`read_journal_entries`	Read recent continuity journal entries in a token-safe format.
`append_journal_entry`	Manually append a compact journal entry when needed.
`search_vault_notes`	Search Obsidian notes when local continuity files are not enough.

Codex conversations

A fresh Codex conversation does not inherit the live Agenties visual chat. In this workspace, Codex should rebuild working context from the durable files.

Codex startup order

.agenties/reports/codex-continuity-brief.md
.agenties/session-briefing.md
.agenties/session-context.json        # only when current-session completions matter
.agenties/shared/state.json           # only when shared memory matters

Codex notification bridge

When Codex (or any external MCP caller) delegates work to an Agenties agent, it needs to know when the agent finishes. The MCP wait_for_chat_response tool has a hard protocol timeout that can trigger before a long agent task completes — causing the caller to treat a timeout as a hang and retry unnecessarily.

Two dedicated tools avoid this problem:

Tool	Use
`wait_for_mailbox_message`	Short-poll the Agenties mailbox until a matching message arrives or the timeout expires. Returns {status, message, cursor}. Pass the returned cursor as "since" in the next call to chain polls without re-reading old messages.
`get_agenties_updates_since`	One-shot snapshot of everything that changed since a given ISO timestamp: new chat messages, new mailbox messages, and agents whose status changed. No agents spawned; all reads are local.

Codex pattern — wait for agent then catch up

// 1. Delegate work to an agent via send_message or spawn_agent
// 2. Poll for completion
const result = await wait_for_mailbox_message({
  to: "orchestrator",
  type: "task-done",
  timeoutMs: 120000,
  pollIntervalMs: 2000,
});

if (result.status === "timeout") {
  // 3. On timeout — catch up rather than retry blindly
  const updates = await get_agenties_updates_since({
    since: myStartCursor,
    includeChat: true,
    includeMailbox: true,
    includeAgents: true,
  });
  // inspect updates.mailbox and updates.agents before deciding next step
}

Note:These tools are designed for Codex and external MCP callers, but they work from any MCP session. Usewait_for_mailbox_message when you need to block on a specific message type, andget_agenties_updates_since when you want a non-blocking summary of recent activity.

Knowledge Graph and continuity

The Knowledge Graph (graph_status, graph_query, graph_update) complements the continuity system. Continuity files track what happened and what to do next; the graph tracks where things are in the codebase. Fresh sessions should load the continuity journal first, then use the graph for any file-location questions that arise.

Note:The graph is rebuilt with graph_update. After a long sprint with many file changes, rebuild the graph alongside your next journal entry to keep both continuity and codebase navigation fresh.

← PreviousMemory & Vault Next →Voice Chat