#9726: feat: add identityDir config for separate identity file location
commands
agents
stale
## Summary
Adds support for configuring a separate directory for identity/bootstrap files (AGENTS.md, SOUL.md, MEMORY.md, etc.) instead of requiring them in the workspace root.
## Use Cases
- **Monorepos** where agent identity files shouldn't clutter the project root
- **Multi-bot setups** with different identity directories per agent
- **Clean separation** between code and agent configuration
## Configuration
```json
{
"agents": {
"defaults": {
"workspace": "/path/to/project",
"identityDir": "bots/mybot/identity"
}
}
}
```
Can also be set per-agent:
```json
{
"agents": {
"list": [
{
"id": "mybot",
"workspace": "/path/to/project",
"identityDir": "bots/mybot/identity"
}
]
}
}
```
## Behavior
When `identityDir` is set:
- Bootstrap files are loaded from identityDir (not workspace root)
- Session memory files are written to `identityDir/memory/`
- Memory search indexes files from identityDir
The `identityDir` can be:
- Relative path (resolved from workspace)
- Absolute path
**Backward compatible** - defaults to workspace root if not configured.
## Changes
- `src/config/types.agent-defaults.ts` - Add `identityDir` to defaults config type
- `src/config/types.agents.ts` - Add `identityDir` to agent config type
- `src/agents/agent-scope.ts` - Add `resolveAgentIdentityDir()` helper
- `src/agents/bootstrap-files.ts` - Load bootstrap files from identityDir
- `src/hooks/bundled/session-memory/handler.ts` - Write memory files to identityDir
- `src/memory/manager.ts` - Index memory files from identityDir
- `src/memory/qmd-manager.ts` - Use identityDir for QMD indexing
- `src/memory/backend-config.ts` - Resolve QMD collections from identityDir
## Test Plan
- [ ] Verify bootstrap files load from identityDir when configured
- [ ] Verify session memory writes to identityDir/memory/
- [ ] Verify memory search indexes from identityDir
- [ ] Verify backward compatibility (no identityDir = workspace root)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new `identityDir` config option (defaults + per-agent) intended to let bootstrap/identity files and memory files live outside the workspace root. It introduces `resolveAgentIdentityDir()` and wires it into bootstrap file loading (`src/agents/bootstrap-files.ts`), session-memory hook output paths (`src/hooks/bundled/session-memory/handler.ts`), and memory indexing/backends (`src/memory/*`).
Main correctness issues to address before merge:
- Per-agent `identityDir` is currently not actually plumbed through `resolveAgentConfig()`, so per-agent configuration is silently ignored.
- The session-memory hook’s no-config fallback writes into a shared `~/.openclaw/workspace` directory, which can mix memory across agents if `cfg` is absent.
<h3>Confidence Score: 3/5</h3>
- This PR is close, but has a configuration plumbing bug that breaks the advertised per-agent behavior.
- Core approach (introducing resolveAgentIdentityDir and routing bootstrap/memory paths through it) is coherent, but per-agent identityDir is currently ignored due to a missing field in the resolved agent config, and the session-memory hook has an inconsistent fallback that can mix agent data when cfg is missing.
- src/agents/agent-scope.ts, src/hooks/bundled/session-memory/handler.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#2884: fix: Create memory directory and symlink identity files during work...
by webdevtodayjason · 2026-01-27
81.5%
#6430: feat(protocol): include agent identity in hello-ok handshake response
by astoreyai · 2026-02-01
79.9%
#7301: fix(hooks): use resolveAgentIdFromSessionKey instead of split(":")[0]
by tsukhani · 2026-02-02
78.8%
#6840: Fix assistant identity default agent for global sessions
by JorgeAlan · 2026-02-02
78.7%
#13524: feat: conditional bootstrap file loading for heartbeat vs DM sessions
by tarun131313 · 2026-02-10
78.5%
#10591: feat(hooks): add session-start-memory bundled hook
by morningstar-daemon · 2026-02-06
78.3%
#19879: Feat/foropenclaw bootstrapfiles clean
by akyourowngames · 2026-02-18
77.8%
#15982: fix: pass agentId to resolveSessionFilePath in reply flow (NX-003)
by automagik-genie · 2026-02-14
77.0%
#19560: docs: refactor agent workspace default location & bootstrap configu...
by ashinkuniyil · 2026-02-17
76.4%
#14618: feat(ui): add AgentHQ - agent workspace evolution viewer
by eddie333016 · 2026-02-12
76.3%