Configure shared memory domains, references, external docs, metrics, and workspace for agents

Memory

The memory block defines how agents store and retrieve persistent knowledge. Memory is organized into sub-blocks that each serve a different purpose — from domain-specific knowledge to external documentation to runtime metrics.

Basic Syntax

memory {
  domains {
    architecture {
      path: "memory/architecture"
      routing: "architecture, system design, infrastructure"
    }
  }
}

Sub-Blocks

Sub-Block	Purpose
`domains`	Organized knowledge areas agents can read from and write to
`references`	Blueprint files and reference materials
`external-docs`	Documentation loaded on demand
`metrics`	Runtime metrics storage
`workspace`	Shared workspace configuration

Domains

Domains partition memory into named areas with routing keywords. When an agent needs context, the routing field helps match the right domain:

memory {
  domains {
    frontend {
      path: "memory/frontend"
      routing: "UI, components, React, CSS, styling"
    }

    backend {
      path: "memory/backend"
      routing: "API, database, server, auth"
    }

    decisions {
      path: "memory/decisions"
      routing: "architecture decisions, ADRs, trade-offs"
    }
  }
}

Field	Type	Required	Description
`path`	string	Yes	File system path for this domain's storage
`routing`	string	Yes	Comma-separated keywords for matching

References

References point to blueprint files and structured reference material:

memory {
  references {
    api-spec {
      path: "references/api"
      blueprints: ["openapi.yaml", "schema.graphql"]
    }
  }
}

Field	Type	Required	Description
`path`	string	Yes	Directory containing reference files
`blueprints`	list	No	Specific files to load as blueprints

External Docs

Load documentation from external sources on demand:

memory {
  external-docs {
    react-docs {
      path: "docs/react"
      files: ["hooks.md", "patterns.md"]
      load-when: "frontend tasks"
    }

    aws-docs {
      path: "docs/aws"
      files: ["lambda.md", "s3.md"]
      load-when: "infrastructure or deployment"
    }
  }
}

Field	Type	Required	Description
`path`	string	Yes	Directory containing documentation files
`files`	list	No	Specific files within the directory
`load-when`	string	No	Natural language condition for when to load

Metrics

Configure where runtime metrics are stored:

memory {
  metrics {
    performance {
      path: "metrics/performance"
      mode: append
    }
  }
}

Field	Type	Required	Description
`path`	string	Yes	Storage path for metrics
`mode`	identifier	No	`append` or `overwrite` (default: `append`)

Workspace

Define the shared workspace agents use for collaboration:

memory {
  workspace {
    shared {
      path: "workspace"
      protocol: "read-write"
      structure: "flat"
    }
  }
}

Field	Type	Required	Description
`path`	string	Yes	Workspace root path
`protocol`	string	No	Access protocol (e.g. `read-write`, `read-only`)
`structure`	string	No	Directory structure style (e.g. `flat`, `nested`)

Agent Memory References

Agents reference memory domains with the memory field:

agent frontend-dev {
  model: sonnet
  memory: [frontend, decisions]
  tools: [Read, Write]
}

Tips

Use routing keywords to help agents find the right domain automatically.
load-when in external-docs prevents unnecessary context loading, saving tokens.
Memory paths are relative to the topology file's directory.
Agents only access memory domains listed in their memory field.

Memory

On this page