Gitagent Documentation

In GitAgent, an agent is not just code; it is a git repository. All agent configurations, personality, rules, and memory are stored as plain text files within a directory. This allows you to use standard git primitives—such as git log to view memory evolution, git diff to track rule changes, and git branch to create experimental versions of your agent—to manage its lifecycle.

A typical GitAgent repository structure includes:

• agent.yaml: The manifest containing model, tools, and runtime configuration.
• SOUL.md: Defines the agent's personality and identity.
• RULES.md: Defines behavioral constraints.
• DUTIES.md: Defines job responsibilities.
• AGENTS.md: Defines sub-agent relationships.
• memory/MEMORY.md: The primary memory file (automatically updated and committed by the agent).
• skills/: Directory containing custom skills (each with a SKILL.md and scripts/).
• hooks/: Contains hooks.yaml for lifecycle hooks.
• tools/: Contains declarative tool definitions in .yaml files.

my-agent/
├── agent.yaml          # The manifest — model, tools, runtime config
├── SOUL.md             # Personality and identity
├── RULES.md            # Behavioral constraints
├── DUTIES.md           # Job responsibilities
├── AGENTS.md           # Sub-agent relationships
├── memory/
│   └── MEMORY.md       # Primary memory (auto-committed by the agent)
├── skills/
│   └── my-skill/
│       ├── SKILL.md    # Skill definition
│       └── scripts/    # Supporting scripts
├── hooks/
│   └── hooks.yaml     # Lifecycle hooks
└── tools/
    └── *.yaml          # Declarative tool definitions

GitAgent uses a git-native memory system where the agent's memory is stored in a plain text Markdown file (typically memory/MEMORY.md) within your repository. Every time the agent uses the memory tool, it appends to the file and creates a git commit.

Key Advantages:

• Audit Trail: Use git log memory/MEMORY.md to see the history of what the agent has learned.
• Debugging: Use git diff to see changes in memory over time.
• Rollback: Use git revert to undo a bad memory entry.
• Collaboration: You can git merge memory histories from different team members.

Layered Memory: You can define multiple memory layers using a memory/memory.yaml file to separate different types of context (e.g., primary for core memory, journal for daily logs, and mood for current state).

# memory/memory.yaml
layers:
  - name: primary
    path: memory/MEMORY.md
    description: Core working memory
  - name: journal
    path: memory/journal.md
    description: Daily activity log
  - name: mood
    path: memory/mood.md
    description: Current agent state and context

A GitAgent instance is organized as a directory containing configuration, identity, and memory files. Key components include:

• agent.yaml: Required configuration for models, tools, runtime, and compliance.
• SOUL.md, RULES.md, DUTIES.md: Define the agent's personality, constraints, and responsibilities.
• memory/: Contains MEMORY.md (primary auto-committed memory), mood.md, and journal.md.
• skills/: Contains skill definitions (SKILL.md) and supporting scripts.
• tools/: Declarative tool definitions in YAML.
• hooks/: Lifecycle hook scripts.
• .gitagent/audit.jsonl: Audit logs (if audit_logging: true is configured).

my-agent/
├── agent.yaml              # Required: model, tools, runtime, compliance
├── SOUL.md                 # Personality and identity
├── RULES.md                # Behavioral constraints
├── DUTIES.md               # Recurring responsibilities
├── AGENTS.md               # Sub-agent relationships
├── memory/
│   ├── MEMORY.md           # Primary memory (auto-committed)
│   ├── memory.yaml         # Memory layer config (optional)
│   ├── mood.md             # Agent state (optional)
│   └── journal.md           # Activity log (optional)
├── skills/
│   └── <name>/
│       ├── SKILL.md        # Skill definition (frontmatter + instructions)
│       └── scripts/        # Supporting scripts
├── hooks/
│   └── hooks.yaml          # Lifecycle hook scripts
├── tools/
│   └── *.yaml              # Declarative tool definitions
├── plugins/
│   └── <name>/             # Local plugins
├── schedules/
│   └── *.yaml              # Cron schedule definitions
└── .gitagent/
    └── audit.jsonl         # Audit log (when audit_logging: true)

SOUL.md is the agent's personality file. It defines the agent's identity, how it speaks, its values, and its approach to problems. This file is included in the system prompt for every query. A good SOUL.md should include:

• Identity: Who the agent is (e.g., a senior specialist).
• How you work: Specific behavioral patterns (e.g., 'ask one clarifying question at a time').
• Tone: The desired communication style (e.g., 'professional but human').
• Knowledge domain: Areas of expertise.

# Alex — First Source Support Agent

You are Alex, a senior customer support specialist at First Source Financial Services. You've been with the company for five years and you know the product inside out.

## How you work

- You respond concisely and directly. Support tickets aren't the place for preamble.
- You ask one clarifying question at a time — never a list of five questions at once.
- When you don't know something, you say so, then point to where the answer can be found.
- You use the ticket tracker to log every resolution step so teammates can pick up mid-thread.

## Tone

- Professional but human. You're not a bot — you're a specialist.
- Calm under pressure. Escalations don't fluster you.
- Never overpromise. If you say "I'll check on that," you check it on.

## Knowledge domain

You specialize in: account management, billing disputes, integration support, and API troubleshooting.

Hooks intercept agent lifecycle events for validation, logging, and control. You can configure them in hooks/hooks.yaml using scripts, or programmatically via the SDK.

Hook Events

Hook Script Interface

Scripts receive a JSON object on stdin and must output a JSON object on stdout.

Input Example:

{"event": "pre_tool_use", "session_id": "uuid", "tool": "cli", "args": {"command": "rm -rf /"}}

Output Actions:

• allow: Continue execution.
• block: Stop execution (requires a reason field).
• modify: Change the arguments (requires an args field).

Output Example (Blocking):

{"action": "block", "reason": "Destructive command blocked"}

RULES.md contains hard constraints that the agent must follow. These rules are enforced via the agent's reasoning. Examples include:

• Data privacy (e.g., 'Never share customer PII').
• Operational requirements (e.g., 'Read before modifying').
• Approval workflows (e.g., 'Require approval for external API calls').
• Safety limits (e.g., 'No credentials in memory').

# Rules

1. **Never share customer PII in responses.** Redact account numbers, SSNs, and contact details from any output visible to third parties.
2. **Read before modifying.** Always read a file before editing or overwriting it.
3. **Require approval for external API calls.** Any outbound HTTP request to a non-approved domain needs confirmation.
4. **No credentials in memory.** Never store API keys, tokens, or passwords in MEMORY.md.
5. **Escalate unresolved issues after 3 turns.** If a customer issue isn't resolved within three exchanges, create an escalation ticket and notify a human.
6. **Stay in scope.** Only operate within the current repository and approved external services.