paths

Documentation

Overview

Package paths provides centralized path resolution for the Echoryn runtime.

All paths in the Echoryn system derive from a single "state directory" (~/.echoryn), which serves as the canonical root for configuration, session data, memory indices, and workspace prompt files.

The system supports two node roles:

• Hivemind (control plane): config at ~/.echoryn/hivemind.json
• Golem (worker node): config at ~/.echoryn/golem.json

Design principles (aligned with OpenClaw's config/paths.ts):

• resolve* functions are pure path computation (no I/O)
• Environment variable overrides take the highest priority
• Ensure* functions perform I/O (MkdirAll) and are called once at startup

Index

• func DefaultAgentID() string
• func EnsureAgentDirs(agentID string) error
• func EnsureStateDir() (string, error)
• func EnsureStateDirForRole(role NodeRole) (string, error)
• func EnsureWorkspaceDir(wsDir string) error
• func GetDataDir() string
• func ResolveAdminTokenPath() string
• func ResolveAgentDir(agentID string) string
• func ResolveConfigPath(role ...NodeRole) string
• func ResolveCredentialsDir() string
• func ResolveGolemDataDir() string
• func ResolveGolemLogsDir() string
• func ResolveGolemSkillsDir() string
• func ResolveGolemWorkspace() string
• func ResolveHomeDir() string
• func ResolveMCPConfigPath() string
• func ResolveMemoryDBPath(agentID string) string
• func ResolveSessionStorePath(agentID string) string
• func ResolveStateDir() string
• func ResolveTemplatesDirs() []string
• func ResolveWorkspaceDir(agentID, explicit string) string
• func SetDataDir(dir string)
• type NodeRole
  • func ParseRole(s string) NodeRole
  • func (r NodeRole) ConfigFileName() string
  • func (r NodeRole) String() string

Functions

func DefaultAgentID

func DefaultAgentID() string

DefaultAgentID returns the default agent identifier.

func EnsureAgentDirs

func EnsureAgentDirs(agentID string) error

EnsureAgentDirs creates agent-specific subdirectories for the given agentID.

func EnsureStateDir

func EnsureStateDir() (string, error)

EnsureStateDir creates the Hivemind state directory structure if it does not exist. Called once at startup for the Hivemind control plane. Returns the resolved stateDir path.

Creates:

~/.echoryn/
├── agents/
│   └── main/
│       └── sessions/
├── memory/
├── workspace/
│   ├── memory/
│   └── prompts/
└── credentials/

func EnsureStateDirForRole

func EnsureStateDirForRole(role NodeRole) (string, error)

EnsureStateDirForRole creates the state directory structure for the given node role. Hivemind and Golem have different directory layouts.

func EnsureWorkspaceDir

func EnsureWorkspaceDir(wsDir string) error

EnsureWorkspaceDir ensures the workspace directory and its convention subdirectories exist.

func GetDataDir

func GetDataDir() string

GetDataDir returns the current custom data directory, or empty string if not set.

func ResolveAdminTokenPath

func ResolveAdminTokenPath() string

ResolveAdminTokenPath returns the admin token file path. Layout: <stateDir>/credentials/admin_token

func ResolveAgentDir

func ResolveAgentDir(agentID string) string

ResolveAgentDir returns the agent-specific data directory. Layout: <stateDir>/agents/<agentID>/

func ResolveConfigPath

func ResolveConfigPath(role ...NodeRole) string

ResolveConfigPath returns the config file path for the given role. Priority: ECHORYN_CONFIG env → <stateDir>/<role>.json.

When role is RoleHivemind: ~/.echoryn/hivemind.json When role is RoleGolem: ~/.echoryn/golem.json

func ResolveCredentialsDir

func ResolveCredentialsDir() string

ResolveCredentialsDir returns the credentials directory. Layout: <stateDir>/credentials

func ResolveGolemDataDir

func ResolveGolemDataDir() string

ResolveGolemDataDir returns the golem-specific data directory. Layout: <stateDir>/golem/

func ResolveGolemLogsDir

func ResolveGolemLogsDir() string

ResolveGolemLogsDir returns the golem skills directory. Layout: <stateDir>/golem/data/logs

func ResolveGolemSkillsDir

func ResolveGolemSkillsDir() string

ResolveGolemSkillsDir returns the golem skills directory. Layout: <stateDir>/golem/skills

func ResolveGolemWorkspace

func ResolveGolemWorkspace() string

ResolveGolemWorkspace returns the golem workspace directory. Layout: <stateDir>/golem/workspace

func ResolveHomeDir

func ResolveHomeDir() string

ResolveHomeDir returns the effective home directory. Priority: ECHORYN_HOME env → os.UserHomeDir().

func ResolveMCPConfigPath

func ResolveMCPConfigPath() string

ResolveMCPConfigPath returns the MCP config file path. Layout: <stateDir>/mcp.json

func ResolveMemoryDBPath

func ResolveMemoryDBPath(agentID string) string

ResolveMemoryDBPath returns the memory SQLite index path. Layout: <stateDir>/memory/<agentID>.db

func ResolveSessionStorePath

func ResolveSessionStorePath(agentID string) string

ResolveSessionStorePath returns the session BoltDB file path. Layout: <stateDir>/agents/<agentID>/sessions/store.db

func ResolveStateDir

func ResolveStateDir() string

ResolveStateDir returns the root state directory. Priority: ECHORYN_STATE_DIR env → <dataDir>/.echoryn (if set) → ~/.echoryn.

func ResolveTemplatesDirs

func ResolveTemplatesDirs() []string

ResolveTemplatesDirs returns the list of directories to search for team template. Priority follows the same pattern as config loading: 1. ./conf/templates (project-specific templates, checked into source control) 2. <stateDir>/templates (~/.echoryn/templates by default, user-level)

The TemplateLoader will scan all directories in order, loading templates from each. Later directories can override templates from earlier ones.

func ResolveWorkspaceDir

func ResolveWorkspaceDir(agentID, explicit string) string

ResolveWorkspaceDir returns the agent workspace directory.

If explicit is non-empty, it is used as-is (absolute or relative). Otherwise, the default workspace is: <stateDir>/workspace

func SetDataDir

func SetDataDir(dir string)

SetDataDir sets a custom data directory for all path resolution. When set, ResolveStateDir returns <dir>/.echoryn instead of ~/.echoryn. Pass an empty string to revert to the default (home-based) behaviour.

Types

type NodeRole

type NodeRole string

NodeRole identifies the type of node in the Echoryn cluster.

const (
	// RoleHivemind is the control plane / central brain node.
	RoleHivemind NodeRole = "hivemind"
	// RoleGolem is the worker / executor node.
	RoleGolem NodeRole = "golem"
)

func ParseRole

func ParseRole(s string) NodeRole

ParseRole converts a string to a NodeRole, returning RoleHivemind as default.

func (NodeRole) ConfigFileName

func (r NodeRole) ConfigFileName() string

ConfigFileName returns the configuration file name for the given role.

func (NodeRole) String

func (r NodeRole) String() string

String returns the string representation of the role.