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.

Why Agenties doesn't forget

Most AI tools forget everything the moment the chat window closes. Agenties works differently: your project's memory lives in local files, not in a Claude session. When you come back days later — or open a completely new Codex conversation — the orchestrator reads those files and picks up where you left off, without you having to explain anything.

Here is what happens when a new session starts:

What fires	What it does for you
Session briefing	A compact summary of recent work, open goals, and active agents is assembled from local files and injected before the first message. No re-prompting needed.
Re-entry brief / startup snapshot	If the orchestrator was mid-task, you see a re-entry brief: what was being worked on, which agents were running, and the suggested next step — not a blank slate.
Continuity journal	A date-grouped diary of completed tasks, key decisions, and paths touched. Updated automatically at the end of every significant turn. The journal answers: "what happened recently?"
Continuity index	A table of contents for important project context — pinned decisions, major features, known risks. Updated as work lands. Answers: "where should I look?"
Facts	Durable, structured facts about the project (integration states, architecture decisions, completed issue results). Persisted independently of chat history so they survive compaction.
Zombie agent alerts + open risks	If an agent was spawned but never finished — a crash, a timeout, a denial — the startup snapshot flags it as a zombie. Open risk facts surface the same way. You see blockers before you start, not mid-task.

Tip:Scenario: you close the app on Thursday, come back Monday. The orchestrator opens with the re-entry brief listing the in-progress issue, the last journal entry summarising Thursday's commits, and a zombie alert for the agent that timed out. You type "continue" — and it does.

The rest of this page covers the technical details of each component.

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.

Why Agenties does not get lost

When you come back days later, Agenties does not rely on the last visible chat message. It rebuilds the working picture from durable project files: the session briefing, re-entry brief, continuity journal, continuity index, facts, open goals, open issues, and shared state.

That means the orchestrator can start a new turn with a compact answer to: what were we doing, what changed, what is still open, which agents look stale, and which risks need attention. You should not have to explain the whole project again just because the chat was compacted, restarted, or opened from another Codex session.

Signal	What it gives the orchestrator
`session-briefing.md`	The current handoff: what changed recently, what remains, and what the next useful step is.
Re-entry brief / startup snapshot	A short boot summary built from local state before the orchestrator decides what to do.
`continuity/journal.md`	A chronological record of completed work and decisions.
`continuity/index.md`	A compact map of important features, reports, fixes, and where details live.
Facts	Durable project facts such as issue results, risks, decisions, and validated capabilities.
Zombie agent alerts	Warnings that an agent or spawn looks stale so the orchestrator can inspect instead of assuming progress.
Open risks	Known unresolved risks that should survive session restarts.

Tip:Example: you reopen a project after a weekend and ask "where were we?" Agenties should be able to answer from the local continuity layer: the active goal, the last closed issues, stale agents if any, and the next recommended step.

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