Workspace

The ./workspace/ directory is the simplest way to inject shared context into every agent conversation. Drop .md files into this directory and they are automatically picked up, synced to the database, and injected into every agent's context — no restart required.

How it works

At startup, the gateway reads all .md files in the ./workspace/ directory, stores their content in the workspace_files database table, and keeps an in-memory cache. The file watcher (fs.watch with 500ms debounce and SHA-256 deduplication) monitors the directory for changes and updates the cache within one second.

At context assembly time, all cached workspace files are injected into the prompt after SOUL.md and before the agent's system prompt.

Priority files

Three files receive special treatment — they are injected first and always included regardless of token budget:

Example workspace files

A typical workspace directory might look like:

workspace/
  AGENTS.md        # Agent guidelines
  USER.md          # User preferences
  IDENTITY.md      # Agent persona
  tech-stack.md    # Project technology choices
  coding-style.md  # Coding standards and conventions
  team-members.md  # Who's on the team

Example workspace/AGENTS.md:

# Agent Guidelines

## Behavior
- Always provide working code examples, not pseudocode
- When suggesting refactors, explain the reason
- For infrastructure tasks, always ask before making changes to production

## Stack
- Language: TypeScript (strict mode, ESM)
- Database: PostgreSQL 17 with pgvector
- Search: Typesense 27.1
- Framework: Express + ws

## Code Style
- Use functional patterns where appropriate
- Prefer explicit types over inferred
- Always add JSDoc for public functions

All markdown files are included

Any .md file in the workspace directory (not just the three priority files) is included. Files are sorted alphabetically after the priority files. You can create as many domain-specific context files as needed.

For limits and truncation behavior, see Context Injection.