hermes-skills/workspace-context-organization/SKILL.md

---
name: workspace-context-organization
title: Workspace Context Organization
description: Manage persistent user context by moving full operational details into per-workspace README files, keeping agent memory compact as pointer references only.
---

# Workspace Context Organization

## Purpose

Manage persistent user context when the agent's memory stores are constrained. Move full operational details into per-workspace README files, keeping memory compact as pointer references only. This avoids memory-full failures while preserving full context where it's needed.

## Triggers

- Memory store (user profile or agent memory) is > 80% full
- Agent attempts to add a memory entry and gets "exceeds the limit"
- User says "put details in the workspace" or similar
- Workspace-specific technical details (endpoints, configs, conventions) are accumulating in global memory
- User creates or manages multiple project workspaces and wants context scoped to them

## Workflow

1. **Inventory**: List all current workspaces (`ls /workspace/` or ask the user)
2. **Map**: Assign each piece of global memory to the most appropriate workspace README
3. **Write READMEs**: Create or update each workspace's `README.md` with full details
4. **Compact memory**: Replace each full-detail memory entry with a pointer (`see /workspace/<name>/README.md`)
5. **Merge duplicates**: If multiple pointers target the same README, collapse to one
6. **Verify**: Confirm with user that the compaction is acceptable before proceeding

## Per-Workspace README Schema

### Default filename: `AGENTS.md` (cross-tool convention)

Hermes auto-loads `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` from the workspace root. **`AGENTS.md` is the canonical name** for cross-tool compatibility — it works in Hermes, Aider, Codex, Cursor, and others. Do NOT default to `README.md` for agent context; `README.md` is for humans, not agents.

If the workspace already has a `README.md` for human readers, keep both. `AGENTS.md` is the agent instruction file.

Use the `save-agents-md` skill to write/update `AGENTS.md` on `/save` requests.

### Schema

Each `/workspace/<name>/AGENTS.md` should be self-contained for its domain:

```markdown
# <WorkspaceName> Workspace

## Domain <Category>

- <detail>
- <detail>

## Configuration

- <endpoint, path, credential>

## Rules / Conventions

- <rule>

## Service Lifecycle

- Host: <IP or hostname>
- Started/stopped manually by user: <yes/no>
- How to verify reachability: <probe command>
- When to expect it to be DOWN: <user says "I turn it off when not in use">

## Session Notes

### Session — YYYY-MM-DD
#### Decisions / Conventions / Environment / Gotchas / Open TODOs
```

## Workspace-Scoped External Services

When a workspace uses external services (Qdrant collections, databases, API keys, embedders) **exclusively**, document the scope in `AGENTS.md` so the agent treats them as in-scope and ignores the rest:

- **Qdrant collections** — list the in-scope collection(s) by name + dimensions + distance. Explicitly name out-of-scope collections so the agent does NOT touch them.
- **Vector DBs / embedders** — document endpoint URL, model name, vector size. Embedding model dim must match the collection's `size` or inserts will fail.
- **API endpoints / credentials** — list endpoint, TIN if relevant, and any auth notes.

Pattern (Qdrant example):

```markdown
## Qdrant Collection

**Only** `<collection_name>` is in scope. Do not read from, write to, or reference any other collection.

- Endpoint: `http://<host>:6333`
- Collection: `<name>`
- Vector size: 1024 (matches `<embedder>`)
- Distance: Cosine

## Embedder

- Ollama at `http://localhost:11434`
- Model: `<name>:<tag>`
```

## Memory Compaction Rules

- User profile: Keep only user-level preferences (communication style, identity, high-level policy)
- Agent memory: Keep only cross-workflow operational pointers and truly global rules
- Never delete full details from memory WITHOUT first writing them to a workspace README
- If a detail applies to multiple workspaces, pick the primary one and cross-reference if needed
- After compaction, both memory stores should be well under 50%

## New Profile Workspace Creation

When a new Hermes profile is created, always create a matching workspace directory and bind it in config.yaml:

1. `mkdir -p ~/workspace/<profile_name>`
2. Create `AGENTS.md` in the workspace with frontmatter (workspace path, created date, purpose) and domain/conventions/tooling sections
3. Add `workspace: /workspace/<profile_name>` to the profile's config.yaml (before `terminal:` section)
4. If the profile was cloned from another, copy the source workspace's AGENTS.md as a starting template

This ensures the WebUI file browser resolves to the correct workspace when that profile is active.

## Home Directory Cleanup

When project directories, scripts, or docs accumulate loose in the home root, move them to their matching workspace:

- **Active services** (docker-compose projects with running containers): keep in home root if they're the deployment source (e.g. `hermes-webui/`, `firecrawl/`)
- **Runtime data** (volume-mounted directories for containers): keep in home root (e.g. `telegram-bot-api-data/`, `spiderfoot-data/`)
- **Everything else**: move to the matching workspace under `/workspace/<profile>/`
- **Stale configs**: delete (e.g. old `.vera-telegram/`, temp files like `_tmp_docker_daemon.json`)
- **Path references in configs**: after moving a project, update all config.yaml files that reference the old path (use execute_code for bulk updates across all 16 config locations)

## Pitfalls

- **Container IPs are NOT host IPs**: When documenting infrastructure, LXC container IPs (e.g. 10.0.0.26, 10.0.0.30) are not the Proxmox host IP. Each host can run multiple LXCs with different allocations. Always label IPs as container or host, and record which host a container runs on. Specs pulled from inside an LXC reflect that container's allocation, not the full host.
- **Services run on containers, containers run on hosts**: When recording where a service lives (e.g. ComfyUI at 10.0.0.202, vLLM at 10.0.0.26), trace the chain: service → container IP → Proxmox host. This matters for capacity planning and understanding what else shares the same physical hardware.
- **Do NOT silently delete entries** to make room without the user's go-ahead
- **Do NOT mix unrelated domains in one README** — one workspace = one domain
- **Do NOT compact before the READMEs are written** — always write first, then compact
- **Do NOT create workspace READMEs without inventorying existing ones** — avoid duplicates
- **Do NOT default to `README.md` for agent context** — `AGENTS.md` is the canonical cross-tool name; use `save-agents-md` skill to maintain it
- **Do NOT ignore out-of-scope external services** — when a workspace scopes to a specific Qdrant collection / DB / endpoint, list the in-scope and out-of-scope resources explicitly in `AGENTS.md` so the agent does not accidentally touch the wrong one
- **Do NOT use `~/workspace/<name>` in config.yaml** — the WebUI container resolves `~` to `/home/hermeswebui/`, not `/workspace/`. Always use absolute `/workspace/<name>` paths.
- **Do NOT create a profile without a workspace** — every new profile must get a matching workspace directory with AGENTS.md and config.yaml `workspace:` key

## Workspace-Scoped File Searches

When the user asks to "list files in your workspace" or "show me files in the workspace," scope file searches to the configured workspace path, NOT the session cwd or home root.

- The session cwd may be `~` or `/home/n8n` — searching from there walks every workspace subdirectory and returns files from profiles the user didn't ask about.
- Determine the active workspace from the profile config: `grep '^workspace:' ~/.hermes/profiles/<active>/config.yaml`. The value is a container-style path like `/workspace/general` — map it to the host path `/home/n8n/workspace/general`.
- Pass that host path as the `path` parameter to `search_files` (or equivalent). This returns only files in the intended workspace.
- If unsure which profile is active, ask or check `~/.hermes/profiles/` — don't default to the home root.

This is a common mistake when the session cwd and the configured workspace path differ. The workspace path is the authoritative scope for "in your workspace" requests.

## Related

- `save-agents-md` — write/update workspace `AGENTS.md` on `/save` requests, scan for contradictions
- `external-reasoning-augmentation` — for augmenting builds with relayed model reasoning

## Session References

- `references/session-memory-migration-2026-05-17.md` — Full worked example of memory compaction across 7 workspaces with before/after metrics and pitfall documentation.