> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent harness

> Agent.deep() — project files, skills, workspace, notes, subagents, and learnings on the same Agent class.

# 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

```typescript theme={null}
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:

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

Or turn pieces on without `deep()`:

```typescript theme={null}
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:

```md theme={null}
# 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
```

```md theme={null}
---
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](/skills/skill-md).

***

## 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"        |

```typescript theme={null}
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](/memory/file-memory).

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.

```typescript theme={null}
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

```typescript theme={null}
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`