# AgentForge — Operational Guide

This file is the first thing injected into your context on every invocation. Keep it lean.

## Your Environment

- `$AGENTFORGE_ROOT` — root of the AgentForge installation (e.g. `/home/agentforge/AgentForge/`)
- `$AGENT_NAME` — your name (e.g. `archie`, `victor`, `architect`)
- `$AGENT_DIR` — your personal directory (e.g. `$AGENTFORGE_ROOT/agents/archie/`)

## Writing to Your Files

**Memory** (durable facts, persist across restarts):
```
$AGENTFORGE_ROOT/vault/Agents/$AGENT_NAME/memory.md
```

**Daily log** (today's notes, ephemeral):
```
$AGENTFORGE_ROOT/vault/Agents/$AGENT_NAME/daily/YYYY-MM-DD.md
```
Append, don't overwrite. Format: `[HH:MM] Note content`.

**Logs** (actions, errors):
```
$AGENT_DIR/logs/
```

## Scripts Available

All scripts are in `$AGENTFORGE_RUNTIME_ROOT/scripts/`. Call them with the full path.

| Script | Usage |
|---|---|
| `telegram_send.sh <agent> "<message>"` | Send Telegram message to the user of `<agent>` |
| `log_action.sh <agent> <type> <target> [details]` | Log an action |
| `healthcheck.sh` | Run system health check |

Example:
```bash
$AGENTFORGE_RUNTIME_ROOT/scripts/telegram_send.sh "$AGENT_NAME" "Hello from $AGENT_NAME"
```

## Shared Context

- **Shared rules** (canonical): `$AGENTFORGE_ROOT/vault/Agents/_team/CLAUDE.md`
- **Shared memory** (canonical): `$AGENTFORGE_ROOT/vault/Agents/_team/memory.md`
- **Generated system state**: `$AGENTFORGE_ROOT/vault/Agents/_team/system-state.md`
- **Delegation rule**: use each agent's bot for direct handoffs; use project topics only for shared multi-agent work
- **Shared knowledge index**: `$AGENTFORGE_ROOT/vault/Agents/_team/index.md`
- **Legacy shared rules fallback**: `$AGENTFORGE_ROOT/agents/shared/CLAUDE.md`
- **Legacy shared memory fallback**: `$AGENTFORGE_ROOT/agents/shared/memory.md`
- **Local overrides** (last-resort fallback, machine-specific, gitignored): `$AGENTFORGE_ROOT/CLAUDE.local.md` — copy from `CLAUDE.local.md.example`
- **Per-agent canonical files**: `$AGENTFORGE_ROOT/vault/Agents/$AGENT_NAME/soul.md`, `$AGENTFORGE_ROOT/vault/Agents/$AGENT_NAME/memory.md`
- **Obsidian vault**: `$AGENTFORGE_ROOT/vault/`

## Architecture Notes

- The Architect administers the system. Prefer `vault/Agents/architect/memory.md` when present, then legacy `agents/architect/memory.md`.
- Each agent has its own Telegram bot token, memory files, and exactly one cron task: `cron/heartbeat`.
- Interactive/API recent conversation context is dynamic: last 4 hours, capped at 20 messages, with backfill to 3 messages when the window is sparse.
- Legacy per-agent `context.messages` or `context_hours` values may still exist in configs or docs; do not describe them as current runtime truth unless you verified the live code/config path.
- The heartbeat timer runs every 10 minutes. If there are no actionable 2Do tasks for an agent, the heartbeat skips the model call entirely.
- One heartbeat run executes at most one 2Do task.
- Routine recurring work belongs in the agent's 2Do list, not in custom agent cron jobs.
- Treat any mention of todo, to-do, 2Do, or task system as the same canonical structured 2Do system.
- If the user asks to update a task, update that task's 2Do notes body. The notes are the executable prompt surfaced by heartbeat.
- Shared handbook docs such as `vault/Agents/_team/todo-system.md` are reference pages, not always-injected memory.
- For questions about models, routing, memory layers, recent-context behavior, or available scripts/tools, verify against `vault/Agents/_team/system-state.md`, `ARCHITECTURE.md`, or live code/config before answering.

## Background Tasks — MANDATORY RULE

When you say you will do something later, in the background, or as a follow-up —
queue it as a task **immediately before ending your response**. No exceptions.
Saying "I'll do X" without creating a task means it never happens.

```bash
python -m agentforge.todo_cli command 2do \
  --root "$AGENTFORGE_ROOT" --agent "$AGENT_NAME" \
  "[AUTO] [chat:$AGENT_NAME] $(date +%Y-%m-%d) <title> — <full context to execute this without remembering the conversation>"
```

- Only add `--due "YYYY-MM-DD HH:MM"` if a specific time was mentioned
- Without `--due`: the task is picked up at the next heartbeat when no higher-priority tasks are pending

At each heartbeat, at most one actionable task is surfaced. Higher priority tasks win first; among equal priority, tasks with a due date are prioritized ahead of tasks without a due date. When done, complete the task and notify via Telegram if instructed.

The vault is synced automatically via Syncthing — no git commit needed.

## Parallel Invocations

Multiple messages may be processed simultaneously. If the recent conversation history shows a user message with no assistant response immediately before the current message, that message is being handled in a parallel invocation — its response is not yet available. **Answer the current message independently** without waiting for or referencing the missing response.
