Workspace

An agent is its workspace: a git repository holding identity, memory, tasks, and history. This page describes what lives there, how context is assembled each run, and why a plain git repo is the right shape for it.

Overview

✨ Superpowers

        graph LR
    Persistent[🔒 Persistent<br/>Complete history<br/>Version controlled]
    Autonomous[🎯 Autonomous<br/>Long-term goals<br/>Proactive & self-directed]
    Evolving[🌱 Self-Improving<br/>Gets smarter over time<br/>Learns from experience]
    Portable[🔁 Portable<br/>Workspace-owned identity<br/>Multiple runtimes]

    %% Force left-to-right layout
    Persistent --- Autonomous --- Evolving --- Portable

    classDef benefits fill:#fff8e1,stroke:#f57f17,stroke-width:3px,color:#000
    class Persistent,Autonomous,Evolving,Portable benefits
    

🔁 Runtime Portability

Your agent is the workspace, not the harness. Identity, memory, tasks, lessons, journal, workflow, and audit history live in the version-controlled workspace. gptme is the native runtime for that workspace, but another harness can operate on the same durable agent state when it implements the same context and task-lifecycle contract.

Keep four layers distinct:

• Agent workspace — identity, memory, tasks, journal, lessons, and workflow.

• Harness / runtime — the agent loop, tools, context loading, and permissions.

• Model / provider — the model used for reasoning and generation.

• Access / billing — API keys, local inference, managed services, or a compatible subscription login.

These layers are not a full Cartesian product. Each harness supports different models and access methods, and merely being able to read the repository is not the same as shipping a reliable autonomous adapter. See the gptme-agent-template runtime compatibility matrix for the concrete support levels in the public template.

🧠 Agent Brain

        graph TD
    subgraph Core[💎 Core Identity]
        Identity[Who am I?<br/>My goals & capabilities]
    end

    subgraph LivingMemory[🔄 Living Memory Systems]
        Journal[📔 Journal<br/>Every decision & insight<br/>Continuous learning]
        Tasks[🎯 Tasks<br/>Goals & achievements<br/>Progress tracking]
        Knowledge[📚 Knowledge<br/>Learned lessons<br/>Cross-referenced insights]
        People[👥 Relationships<br/>Collaboration history<br/>Social intelligence]
        Projects[🚀 Projects<br/>Active work & outcomes<br/>Success patterns]
    end

    subgraph Intelligence[🤖 Dynamic Intelligence]
        direction LR
        Context[⚡ Live Context<br/>Situational awareness<br/>Current state]
        Learning[📈 Continuous Learning<br/>Self-improvement<br/>Pattern recognition]
    end

    %% Internal intelligence flow
    Core --> LivingMemory
    LivingMemory --> Intelligence
    Context --- Learning

    %% Memory interconnections (selective)
    Journal -.->|Informs| Tasks
    Knowledge -.->|Supports| Projects
    People -.->|Collaborate on| Projects

    classDef core fill:#fff3e0,stroke:#ef6c00,stroke-width:3px,color:#000
    classDef memory fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000
    classDef intelligence fill:#fce4ec,stroke:#c2185b,stroke-width:3px,color:#000

    class Core,Identity core
    class LivingMemory,Journal,Tasks,Knowledge,People,Projects memory
    class Intelligence,Context,Learning intelligence
    

🌍 External World

        graph LR
    subgraph World
        User[👤 User]
        Web[🌐 Web & APIs]
        Files[📁 Files & Code]
        Social[✉️ Email & Discord]
    end

    classDef world fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000

    class World,User,Web,Files,Social world
    

Architecture

Git-based Repository Structure: Each agent is a complete git repository with a structured workspace.

• Core files - README.md, ABOUT.md, ARCHITECTURE.md, gptme.toml

• journal/ - Daily activity logs (YYYY-MM-DD.md format)

• tasks/ - Individual task files with YAML metadata (managed with gptodo)

• knowledge/ - Long-term documentation and insights

• lessons/ - Learned lessons and best practices

• people/ - Contact profiles and relationship management

• projects/ - Project-specific information

Dynamic Context Generation: Agents use sophisticated context generation to maintain awareness.

• Project configuration (gptme.toml) specifies core files always in context

• A context_cmd command specified in gptme.toml is used for dynamic context generation

• Each interaction includes recent journal entries, active tasks, and git status

• Provides comprehensive situational awareness across sessions

Key Systems

Journal System:

• One file per day in append-only format

• Contains task progress, decisions, reflections, and plans

• Most recent entries automatically included in context

• Maintains historical record of all activities and thoughts

Task Management:

• Individual Markdown files with YAML frontmatter metadata in tasks/

• States such as backlog, todo, active, waiting, done, and cancelled

• Priority levels, tags, and dependencies

• Managed with gptodo, which the template is set up for: gptodo ready and gptodo next pick unblocked work, gptodo claim marks it taken, and gptodo lint catches malformed tasks

• Integrated with journal entries for progress updates

Communication:

• gptmail stores email and agent-to-agent messages as Markdown files in the workspace and tracks which ones have been answered. See Email and Agent Messaging.

Note

gptodo and gptmail are optional. gptme itself does not depend on them, and an agent can just as well track work in GitHub Issues, Linear, or a single TODO.md, and talk to people through whatever channel you already use. Point the agent at your system in its identity files and context_cmd.

Knowledge Base:

• Long-term information storage organized by topic

• Technical documentation, best practices, and insights

• Cross-referenced with tasks and journal entries

Lessons System:

• Used to document learned lessons and best practices

• Learned lessons are to be retrieved when the context arises

• Helps avoid repeating mistakes and improves decision-making

People Directory:

• Individual profiles for contacts and collaborators

• Includes interests, skills, project history, and interaction notes

• Privacy-conscious with appropriate detail levels

What creation gave you

gptme-agent create clones the gptme-agent-template and customizes it for your agent: identity files, knowledge and lesson directories, and automation scaffolding. Pass --no-template for a bare directory layout instead, or clone the template yourself and run ./scripts/fork.sh — the command just automates that.

Run the agent from its workspace, as you would any gptme session:

cd ~/ada
gptme "your prompt here"

Everything it learns lands in the workspace: journal entries, tasks, knowledge, and lessons. Commit them — the git history is the agent’s memory, and what makes the next session better than the last.

What happens each run

1. gptme builds context from all systems

   • Includes journal entries, tasks, knowledge, and people

   • Static context is included using the files in gptme.toml

   • Dynamic context is generated using the context_cmd in gptme.toml

2. gptme runs the agent

   • With prompt, tools, and collected context

3. Agent processes the prompt

   • Uses the context to inform decisions and responses

   • Updates journal, tasks, and knowledge as needed

Why a git repo

Using an ordinary repository as the agent’s brain buys three things:

• A complete history. Every decision, note, and change is version-controlled, so you can review what the agent did, revert it, back it up, or hand the workspace to someone else.

• State that survives the session. The agent remembers previous conversations, decisions, and progress, and builds knowledge and relationships over time instead of starting cold.

• Memory you can navigate. Structured directories keep information findable — past decisions, cross-references between tasks and knowledge — rather than buried in chat logs.

The template gives every agent the same foundation, while identity, goals, and capabilities stay yours to customize.