Agent harness

In plain terms

A framework is the engine (models, tools, sessions). A harness is the seatbelt + backpack the agent wears so it can work in a real repo:

read the project’s rules (AGENTS.md)
open a skill booklet only when needed (SKILL.md)
stay inside one folder (workspace)
write notes to its future self
remember tiny standing facts
ask a helper to do a subtask
search older chats

Agentium does not add a second class called DeepAgent. That would copy the whole engine. The harness is just extra switches on Agent.

One-line start

import { Agent, openai } from "@agentium/core";

const agent = Agent.deep({
  name: "coder",
  model: openai("gpt-4o"),
  instructions: "You are a coding assistant.",
});

await agent.run("What does this repo expect from me?", { sessionId: "s1", userId: "u1" });

Agent.deep(config) is the same as new Agent({ ...defaults, ...config }). Your config wins.

What `deep()` turns on

Switch	Default	Kid version
`workspace`	`process.cwd()`	”You may only touch files in this folder.”
`skillDirs`	`./skills`	Look for `SKILL.md` booklets.
`contextFiles`	`true`	Read `AGENTS.md` and friends.
`filesystem`	`true`	Durable notes (not the host disk).
`fileMemory`	`true`	Tiny MEMORY.md / USER.md.
`subagents`	`true`	`task` tool → helper agent.
`learning`	`true`	Save reusable lessons (in-memory store unless you pass a real vector DB).
`searchPastSessions`	`true`	Search older chats by keyword.

Turn any of them off:

Agent.deep({
  name: "coder",
  model: openai("gpt-4o"),
  subagents: false,
  workspace: "./safe-folder",
});

Or turn pieces on without deep():

new Agent({
  name: "coder",
  model: openai("gpt-4o"),
  contextFiles: true,
  workspace: process.cwd(),
  fileMemory: true,
});

1. Project rules — `AGENTS.md`

Put a file in the repo:

# AGENTS.md

- Use TypeScript.
- Don't invent APIs.
- Run tests before you say you're done.

With contextFiles: true, that text is added to the system prompt. Also accepted (first match wins, walking up to the git root): .agentium.md, AGENTS.md, CLAUDE.md, .cursorrules. Obvious prompt-injection (“ignore previous instructions”) is blocked, not loaded.

2. Skills — `SKILL.md`

A skill is a folder with a booklet:

skills/pdf-export/SKILL.md

---
name: pdf-export
description: Turn a page into a PDF
---

Always export A4. Use the pdf toolkit.

The model first sees only name + description (~a tweet). When it needs the full booklet it calls get_skill_instructions. That is progressive disclosure.

3. Workspace vs durable notes

Two different “filesystems”. Easy to mix up:

	Workspace (`workspace:`)	Notes (`filesystem:`)
What	Real files on your computer	Saved notes in storage
Tools	`fs_read_file`, `fs_write_file`, …	`agent_fs_write`, `agent_fs_read`, …
Jail	Cannot leave `workspace`	Cannot use `..` paths
Use for	Edit the project	”Remember this for next week”

new Agent({
  name: "coder",
  model: openai("gpt-4o"),
  workspace: "./my-project",   // host disk, jailed
  filesystem: true,            // durable notes
});

4. Standing memory files

fileMemory: true gives a memory tool with a hard character cap.

target: "memory" → environment / project facts (MEMORY.md)
target: "user" → this person’s preferences (USER.md)

When the box is full, the tool says “consolidate” instead of growing forever. Details: Standing notes. This is not the same as memory: { storage } (session history + summaries + vector learnings). You can use both.

5. Subagents

subagents: true adds the task tool. The child:

gets a new message list (no giant parent history)
can have its own instructions
returns one final report

The parent only sees that report — not the child’s tool chatter.

const report = await agent.spawnSubagent("Summarize src/agent/agent.ts");

Events: subagent.start, subagent.complete, subagent.error. Max nesting: subagents: { maxDepth: 2 }.

6. Learnings

learning: true wraps the existing vector store (LearnedKnowledge, collection agentium_learnings). It does not invent a second memory brain.

Tests / demos: learning: true (hash embedder + in-memory vectors)
Production: pass a real store

memory: {
  storage: new PostgresStorage(url),
  learnings: { vectorStore: myQdrant, minScore: 0.35 },
}

What we did not add

A DeepAgent class — it would duplicate Agent
A rewrite of MemoryManager — files + session search sit beside it
Using the event bus to skip tools — that’s loopHooks

​Agent harness

​In plain terms

​One-line start

​What deep() turns on

​1. Project rules — AGENTS.md

​2. Skills — SKILL.md

​3. Workspace vs durable notes

​4. Standing memory files

​5. Subagents

​6. Learnings

​What we did not add