Configuration

Configuration files

HMG configuration falls into three categories: agent integration files, the store data directory, and runtime environment variables. Only what users actually touch is listed here.

File	Role	Generated by
~/.codex/config.toml / .cursor/mcp.json / .mcp.json	Tells the host how to start the HMG MCP server	hmg init --agent <id>
~/.codex/hooks.json / .cursor/hooks.json / ~/.claude/settings.json	Host lifecycle hooks (three: SessionStart / UserPromptSubmit / PreToolUse)	hmg init --agent <id>
AGENTS.md / CLAUDE.md / .cursor/rules/hmg-memory.mdc	The agent's memory policy and usage rules	hmg init --agent <id>
store directory	The data itself (memories/indexes/observations)	created automatically

store path

• Default store: <user data dir>/hmg/stores/default
  • macOS/Linux: ~/.local/share/hmg/stores/default
  • Windows: usually %LOCALAPPDATA%\hmg\stores\default
• Use --store <path> for any store.
• Most commands accept --store, e.g. hmg memorize "..." --store /my/store.

Identity and login (store.toml)

store.toml inside the store directory records local identity:

toml

# ~/.local/share/hmg/stores/default/store.toml

[identity]
local_tenant = "qiankun"              # OS username, written at hmg init, never changes
linked_account = "userB"              # written after hmg login, cleared on logout
linked_at = "2026-07-28T10:00:00Z"    # login time

• local_tenant: the tenant (first scope level) of every memory — the OS username, written at hmg init, never changes afterwards.
• linked_account: the HMG user-center account written after upgrading your plan on the website and running hmg login. Login performs no data migration — local reads/writes always use local_tenant; the account mapping is only used during cloud sync.
• Logout / account switch: only clears linked_account; local memories are untouched.

Environment variables

See Common environment variables.

Store directory

The store is the root directory of HMG data.

Default location

See above. hmg doctor --verbose prints the data directory actually in use — trust that output first.

Choosing a project store

• Default store + scope: projects separated by repository/branch (the default in agent integration — scope is inferred automatically from the session directory). Good when you don't want to manage multiple directories.
• Dedicated project store: --store /path/to/proj — physical isolation, no pollution, recommended for many projects.

Backup and migration

bash

# Method 1: copy the store directory directly
cp -r /old/store /backup/store

# Method 2: official migration (with backup)
hmg store migrate --from /old/store --to /new/store --backup --apply

# Dry-run preview first
hmg store migrate --from /old/store --to /new/store --dry-run

Maintenance commands

bash

# Clean orphan edges/indexes
hmg store hygiene --dry-run
hmg store hygiene

# Repair corrupted edges
hmg store repair-edges --dry-run
hmg store repair-edges --backup --apply

Common environment variables

Only common local items.

Variable	Role
HMG_STORE	Default store path
HMG_DATA_DIR	Data directory used by the current host
HMG_PROVIDER_BACKEND	Provider backend, commonly local
HMG_USE_LOCAL_DAEMON	Whether to prefer the local daemon
HMG_CONSOLIDATION_SCHEDULER	Observation consolidation scheduler (e.g. embedded, observation scenarios only)
HMG_CAPTURE_MODE	Observation capture mode (e.g. raw-with-retention)
HMG_PROMOTION_MODE	Observation promotion mode (e.g. execute)
HMG_AUTOMATION_TIER	Automation tier (e.g. remember-first-govern-later)
HMG_AGENT_ID	Current host identifier, e.g. codex / cursor / claude
HMG_HTTP_ADDR	Local address when the HTTP fallback is enabled

Observation config and scheduling

The observation pipeline is not activated in agent integration (durable memories are written by the agent's own memorize/handoff). The commands below are for manual / automation scenarios.

bash

hmg observation config get
hmg observation config set capture_mode raw-with-retention
hmg observation scheduler status
hmg observation scheduler run-once