04. Agents, Swarm, Memory, and Workspace

This chapter covers the higher-level workflow features in the Hadamard SDK.

1. Named agents

Register reusable agent roles:

const sdk = await createAgentSdk({
  agents: [
    {
      name: 'reviewer',
      description: 'Review work and report the sharpest findings first.',
      systemPrompt:
        'You are a careful reviewer. Prioritize bugs, regressions, and missing verification.',
    },
  ],
});

Run directly through that role:

const result = await sdk.runWithAgent(
  'reviewer',
  'Review this repository as if you were preparing a release.',
);

2. Agent delegation

If named agents are registered, the Hadamard SDK exposes the model-facing Agent tool. Task remains an alias for compatibility.

Useful entry points:

1. sdk.createTaskTool()
2. sdk.runWithAgent(...)
3. sdk.createAgentSession(...)
4. sdk.tasks.list(), sdk.tasks.wait(...), and sdk.tasks.stop(...)

The Agent tool supports foreground and background execution, named agent instances, per-call model selection, explicit working directories, and isolation: "worktree". Background completion is injected into the parent session as a structured notification. SendMessage can steer a running agent at its next tool boundary or continue a completed persisted agent session.

Agent definitions can also be loaded from Markdown:

---
name: reviewer
description: Review code without editing it
tools: Read, Grep, Glob
disallowedTools: Write, Edit
skills: release-checklist
effort: high
permissionMode: plan
memory: project
background: true
---
Prioritize correctness, regressions, and verification gaps.

Place project definitions in .actoviq/agents/*.md and user definitions in ~/.actoviq/agents/*.md. Programmatic definitions override project definitions, which override user definitions. Definitions can also constrain nested agents, require MCP servers, preload skills, and opt into worktree isolation. A dirty delegated worktree is retained and its path is returned; an unchanged worktree is removed automatically.

3. Swarm teammates and side sessions

Use swarm helpers when you want a leader plus teammate pattern:

const team = sdk.swarm.createTeam({
  name: 'release-team',
  leader: 'lead',
  continuous: true,
});

Useful operations:

1. spawn(...)
2. message(...)
3. continueFromMailbox(...)
4. reenter(...)
5. runBackground(...)
6. transcript(...)
7. waitForIdle()

You can now also apply team-level runtime context:

team.setRuntimeContext({
  permissions: [{ toolName: 'write_note', behavior: 'ask' }],
  approver: ({ publicName }) =>
    publicName === 'write_note'
      ? { behavior: 'allow', reason: 'Approved for teammate work.' }
      : { behavior: 'deny', reason: 'Unexpected tool.' },
});

Repository example:

• examples/actoviq-swarm.ts

4. Workspace helpers

You can create isolated directories before starting an agent session.

Available helpers:

1. createWorkspace(...)
2. createTempWorkspace(...)
3. createGitWorktreeWorkspace(...)

const workspace = await createTempWorkspace({
  prefix: 'actoviq-demo-',
  copyFrom: './examples',
});

const sdk = await createAgentSdk({
  workDir: workspace.path,
});

5. Memory and session memory

The SDK provides:

1. relevant memory selection
2. session-memory prompt and summary helpers
3. compact-state inspection
4. automatic session-memory extraction once a session is large enough

Main APIs:

const memory = sdk.memory;
console.log(await memory.findRelevantMemories('how should I release this package?'));

At session level:

const extraction = await session.extractMemory();
const state = await session.compactState({
  includeSessionMemory: true,
  includeSummaryMessage: true,
});

Repository examples:

• examples/actoviq-memory.ts
• examples/actoviq-session-memory.ts

6. Buddy

Buddy is a persistent companion-style context layer. It is not a separate tutorial section in the nav because it works best as part of the wider clean-SDK workflow story.

Useful entry points:

1. sdk.buddy.get()
2. sdk.buddy.hatch(...)
3. sdk.buddy.mute() / unmute()
4. sdk.buddy.pet()
5. sdk.buddy.getPromptContext()

Example:

await sdk.buddy.hatch({
  name: 'Luna',
  persona: 'A calm engineering companion.',
});

console.log(await sdk.buddy.state());

7. Dream

Dream is the Hadamard SDK's reflective memory-consolidation pass over recent sessions.

const state = await sdk.dreamState();
console.log(state);

const session = await sdk.createSession({ title: 'Dream demo' });
const result = await session.dream({
  extraContext: 'Consolidate stable release workflow notes and recurring project facts.',
});

console.log(result.result?.text);
console.log(result.touchedFiles);

Auto-dream:

await sdk.memory.updateSettings({ autoDreamEnabled: true });
await sdk.maybeAutoDream({
  currentSessionId: session.id,
  background: true,
});

Repository example:

• examples/actoviq-dream.ts

8. Compact

The Hadamard SDK supports:

1. automatic compact
2. reactive compact
3. API-oriented microcompact shaping
4. persisted compact history and continuity metadata

This matters most in long-running sessions and multi-turn task flows.

Manual compact accepts optional summary guidance and returns structured failure state instead of losing continuity:

const result = await session.compact({
  force: true,
  summaryInstructions: 'Preserve unresolved test failures and exact file paths.',
});

if (!result.compacted) {
  console.error(result.reason, result.error, result.consecutiveFailures);
}

Compact history and the three-failure circuit breaker are stored with the session, so resumeSession() does not reset recovery state.

Next chapter:

• 05-testing-troubleshooting-cheatsheet.md