Context Files & Workspace Awareness

Updated on 4/15/2026

title: "Lesson 08 | Context Files & Workspace Awareness" summary: "Master the use of the .hermes/context directory to enable the Agent to automatically understand your project structure and team conventions." sortOrder: 80 status: "published"

Lesson 08 | Context Files & Workspace Awareness

Subtitle: Master the use of the .hermes/context directory to enable the Agent to automatically understand your project structure and team conventions.

In previous lessons, we learned how to empower the Agent with new abilities through Skills and provide it with cross-session memory using Memory. These mechanisms significantly enhance the Agent's dynamic interaction capabilities. However, in real-world development scenarios, we often need the Agent to understand and adhere to static, project-level rules, such as the project's directory structure, the team's coding standards, API design guidelines, and more. Repeatedly informing the Agent of this information in every interaction would be extremely inefficient.

In this lesson, we will delve into a core feature of Hermes Agent—Workspace Awareness—and the key to implementing it: the .hermes/context directory. Through this, we can inject project-specific background knowledge into the Agent "once," enabling it to act like an experienced team member and follow established rules in all subsequent interactions.

Learning Objectives

After completing this lesson, you will be able to:

  1. Understand the core value of Workspace Awareness: Grasp why it's crucial for the Agent to comprehend its current working environment.
  2. Master the mechanism of the .hermes/context directory: Learn how it works and how the Agent uses the files within it to build context.
  3. Learn to create effective context files: Discover how to organize and write different types of contextual information, such as project structure, coding standards, and API conventions.
  4. Apply it in practice: Work through a complete example to guide the Agent in completing a real coding task while adhering to project specifications.

Core Concepts Explained

2.1 What is Workspace Awareness?

Workspace Awareness refers to the AI Agent's ability to understand its current file system environment, project configuration, team conventions, and domain knowledge. It is fundamentally different from the Memory we discussed in Lesson 04:

  • Memory is dynamic and conversation-driven. It records your interaction history with the Agent, representing information about your preferences and past tasks that the Agent learns gradually through your "chats".
  • Workspace Awareness is static and environment-driven. It originates from the rules and documentation you pre-define in the project, serving as the "project onboarding manual" that the Agent should know before starting any conversation.

An Agent with Workspace Awareness won't arbitrarily add code to the main app.py file when you ask it to create a new API route. Instead, it will check the project specifications, discover that all routes should be created as separate Blueprint files in the routes/ directory, and follow a specific JSON return format. This capability is the crucial step that transforms the Agent from a "general-purpose chatbot" into a "specialized domain assistant."

2.2 The .hermes/context Directory: The Injection Point for Static Knowledge

The core mechanism through which Hermes Agent achieves Workspace Awareness is a special directory: .hermes/context.

When you start Hermes Agent from a project directory (e.g., by running hermes run in /path/to/my_project/), the Agent automatically checks for the existence of a .hermes/context subdirectory. If it exists, the Agent will recursively read the contents of all files within this directory and provide them as high-level context (typically injected into the System Prompt or a similar high-priority area) to the Large Language Model (LLM).

This means that all content within the .hermes/context directory becomes the background knowledge for the model when processing every single request within that project.

2.3 Context Injection Mechanism

Understanding how it works is crucial:

  1. Load on Startup: The Agent scans the .hermes/context directory upon startup.
  2. Content Aggregation: It reads the content of all files (usually sorted by filename to ensure order) and consolidates them into a single large text block.
  3. Pre-injection: This aggregated text block is placed at the very beginning of the request sent to the LLM, as part of the base instructions. This ensures the model always "reads" the project specifications before analyzing your specific query.
  4. Persistent Effect: As long as the Agent is running in that workspace, this context remains in effect for every interaction, without needing to be provided again.

Important Note: Context content consumes valuable token space. Therefore, files in .hermes/context should follow the principles of being concise, clear, and accurate. Avoid including large library files, binary files, or irrelevant documentation. Only include the core rules and information necessary to guide the Agent's behavior.

2.4 Typical Use Cases

The power of the .hermes/context directory lies in its flexibility. Here are some effective use cases:

  • Project Structure:
    • Use Markdown or text files to describe the project's directory tree and the purpose of each directory.
    • For example: src/api/ stores all API Blueprints, and src/models/ stores database models.
  • Coding Standards & Style Guides:
    • Specify code style (e.g., PEP 8) and naming conventions (e.g., snake_case for variables, CamelCase for classes).
    • Define logging formats, error handling procedures, etc.
  • API Documentation & Data Models:
    • Define standard API response structures, such as { "status": "success", "data": {...} } or { "status": "error", "message": "..." }.
    • Provide field definitions and types for core data models.
  • Deployment Process & Environment Configuration:
    • Explain how the project is built, tested, and deployed.
    • Explanation of key Dockerfile instructions or a brief description of the CI/CD pipeline.
  • Domain Knowledge & Business Terminology:
    • Explain project-specific business terms, for example, "What is the definition of an 'active user'?" or "How is the 'billing cycle' calculated?"

By making this "implicit knowledge" explicit, you significantly reduce the probability of the Agent generating code that does not meet project requirements.

💻 Hands-on Demo

Now, let's walk through a complete scenario to experience the power of .hermes/context.

Scenario: We have a web application project based on Python Flask. We need Hermes Agent to help us add a new API endpoint for fetching user information. We require the Agent to strictly follow the team's established project structure and API conventions.

Step 1: Prepare the Project Environment

First, create a simple Flask project structure.

# Create the project root directory
mkdir my_flask_project && cd my_flask_project

# Create the application directory structure
mkdir -p src/routes src/models

# Create the main application file
touch src/__init__.py
touch src/app.py

# Create an empty model file
touch src/models/user.py

# Create an empty route file
touch src/routes/health.py

# Create the dependency file
touch requirements.txt

# Create our core directory
mkdir -p .hermes/context

Use the tree command to view our project structure (if not installed, use sudo apt-get install tree or brew install tree):

tree .

The output should look like this:

.
├── .hermes
│   └── context
├── requirements.txt
└── src
    ├── __init__.py
    ├── app.py
    ├── models
    │   └── user.py
    └── routes
        └── health.py

Now, let's populate some basic code.

src/app.py:

# src/app.py
from flask import Flask

def create_app():
    app = Flask(__name__)

    # Import and register Blueprints
    from .routes.health import health_bp
    app.register_blueprint(health_bp, url_prefix='/api/v1')

    # We will dynamically register other blueprints here
    
    return app

if __name__ == '__main__':
    app = create_app()
    app.run(debug=True)

src/routes/health.py:

# src/routes/health.py
from flask import Blueprint, jsonify

health_bp = Blueprint('health', __name__)

@health_bp.route('/health', methods=['GET'])
def health_check():
    """Health check endpoint."""
    return jsonify({
        "status": "success",
        "data": {
            "service": "my_flask_project",
            "status": "ok"
        }
    })

Step 2: Define Our "Team Conventions"

This is the most critical step. We will create several files in the .hermes/context directory to define our rules.

.hermes/context/01-project-architecture.md

# Project Architecture Guide

1.  **Directory Structure**:
    -   `src/app.py`: Main Flask application factory.
    -   `src/routes/`: Contains all API Blueprints. Each feature set should have its own file (e.g., `users.py`, `products.py`).
    -   `src/models/`: Contains all SQLAlchemy or data-related models.

2.  **Blueprints**:
    -   All new API endpoints MUST be implemented within a Flask Blueprint.
    -   Blueprints must be defined in the `src/routes/` directory.
    -   The main `create_app` function in `src/app.py` is responsible for registering blueprints.

.hermes/context/02-api-conventions.md

# API Conventions

1.  **Versioning**: All API endpoints must be versioned under the `/api/v1/` prefix.

2.  **Response Structure**: All JSON responses MUST follow this structure:
    -   **Success**: `{"status": "success", "data": <payload>}`
    -   **Error**: `{"status": "error", "message": "<error_description>"}`

3.  **Naming**:
    -   Endpoint URLs should be plural and use kebab-case (e.g., `/users`, `/product-orders`).
    -   Blueprint variables should end with `_bp` (e.g., `users_bp`).

.hermes/context/03-coding-style.md

# Coding Style Guide

1.  **Imports**: Use absolute imports from the `src` root (e.g., `from src.models.user import User`).
2.  **Docstrings**: All public functions and API endpoints must have a clear docstring explaining their purpose.
3.  **Logging**: Use the standard Python `logging` module. Do not use `print()` statements for debugging in production code.

Now, our .hermes/context directory contains clear instructions on three aspects: project architecture, API conventions, and coding style.

Step 3: Start the Agent and Give the Task

Start Hermes Agent in the project root directory (my_flask_project).

hermes run

After the Agent starts, it will silently load all the content from .hermes/context. Now, let's give it our request.

User Prompt: Hello, please help me add a new API feature to the project. I need an endpoint at the path /users/<user_id> that can fetch information for a specific user via a GET request. For now, just return some mock user data.

Step 4: Analyze the Agent's Response

An Agent without Workspace Awareness might do the following:

  1. Directly modify src/app.py.
  2. Use the @app.route('/users/<user_id>') decorator.
  3. Return a simple dictionary like {"id": user_id, "name": "Test User"}.

However, a Hermes Agent that has learned our context will provide a completely different and more professional response.

Expected Agent Response (Analysis and Code):

Understood. Based on the architecture guide and API conventions in your project, I will create this new user endpoint for you.

To adhere to the specifications, I will perform the following actions:

  1. Create a new file users.py in the src/routes/ directory to house the user-related routes.
  2. Define a new Flask Blueprint named users_bp in that file.
  3. Implement the /users/<user_id> endpoint and ensure its JSON response format conforms to the { "status": "success", "data": ... } convention.
  4. Finally, I will provide the code that needs to be added to src/app.py to register this new Blueprint.

Step 1: Create the new file src/routes/users.py

# src/routes/users.py
from flask import Blueprint, jsonify

# Adhering to the `_bp` naming convention
users_bp = Blueprint('users', __name__)

@users_bp.route('/users/<user_id>', methods=['GET'])
def get_user(user_id):
    """Fetches information for a specific user."""
    # Mock user data
    mock_user = {
        "id": user_id,
        "name": "John Doe",
        "email": "[email protected]"
    }
    
    # Adhering to the standard success response structure
    return jsonify({
        "status": "success",
        "data": mock_user
    })

Step 2: Register the new Blueprint in src/app.py

Please open the src/app.py file and add the following two lines of code:

# src/app.py
from flask import Flask

def create_app():
    app = Flask(__name__)

    # Import and register Blueprints
    from .routes.health import health_bp
    # Add new import
    from .routes.users import users_bp

    app.register_blueprint(health_bp, url_prefix='/api/v1')
    # Add new registration and apply the /api/v1 prefix
    app.register_blueprint(users_bp, url_prefix='/api/v1')

    return app

# ... (rest of the file remains unchanged)

Please review the code above. If you confirm it is correct, I can apply these changes for you.

Analysis:

  • Followed Project Structure: The Agent correctly suggested creating a new file under src/routes/ instead of polluting app.py. This is because it learned from 01-project-architecture.md.
  • Used Blueprints: The Agent knew to use a Blueprint and correctly named it users_bp. This also comes from 01-project-architecture.md and 02-api-conventions.md.
  • Adhered to API Conventions: The returned JSON structure perfectly matches the specification defined in 02-api-conventions.md. The /api/v1/ URL prefix was also correctly applied when registering the Blueprint.
  • Good Coding Style: The code includes a clear docstring, complying with the requirements in 03-coding-style.md.

This example clearly demonstrates that by pre-setting the context, the Agent's behavior shifts from "guessing" to "following," resulting in a qualitative leap in output quality and project alignment.

Commands Used

Terminal commands used in this lesson:

  • mkdir -p <path>: Create nested directories.
  • touch <file>: Create an empty file.
  • tree .: Display the current directory structure as a tree.
  • hermes run: Start Hermes Agent in the current workspace.

Key Takeaways

  1. Workspace Awareness is Key: It transforms the Agent from a general-purpose tool into a specialized assistant that can deeply integrate into specific project workflows.
  2. .hermes/context is the Core: This is the standard way to inject static, project-level knowledge into the Agent.
  3. Context is Always Active: All conversations with the Agent in the current workspace are influenced by the contents of .hermes/context.
  4. Structure Your Context: Splitting different types of specifications (architecture, API, coding style) into separate files makes the context clearer and easier to maintain.
  5. Brevity is Essential: Context consumes tokens, so the content must be concise, accurate, and contain only the necessary guiding information.
  6. Automate Team Onboarding: .hermes/context is an excellent tool for automatically teaching team best practices and technical conventions to new members (both human and AI).

By mastering the use of Context Files, you can train Hermes Agent to become a powerful assistant that truly understands your project and your team, achieving a higher level of human-computer collaboration in your development work.

References

  • Hermes Agent Official Documentation: [Link to be added]
  • Prompt Engineering Guide - Providing Context: [Link to be added]
  • This Tutorial Series:
    • [Lesson 03 | A Deep Dive into the Skills System](Link to be added)
    • [Lesson 04 | Memory and User Profiles](Link to be added)