hermes-context-workspace-recall

name	hermes-context-workspace-recall
description	Use when Hermes is working with Context Workspace through the context_workspace MCP server and needs to refresh, verify, report, inspect, or clear project-local recall context before answering project questions or launching future agent runs.

Hermes Context Workspace Recall

Use this workflow to turn Hermes session memory into a project-local recall cache that Context Workspace automatically injects into future agent runs.

Hermes owns retrieval and summarization. Context Workspace owns injection into generated agent context. Agents consume the generated context.md; they do not need direct Hermes access.

Preconditions

• The context_workspace MCP server is configured in Hermes.
• Context Workspace Electron is running, or CONTEXT_WORKSPACE_BACKEND_URL points to a healthy backend, for backend-dependent tools.
• The project path is the WSL path to the Windows checkout, for example:

/mnt/c/Users/you/context-workspace

Recall cache tools read and write project-local files and can operate even if the backend is unavailable.

Required Operating Pattern

Before answering a substantive task about a Context Workspace project, and before spawning or coordinating agents:

1. Run session_search for the current project, branch, task, PR, error, or investigation topic.
2. Call context_workspace_summarize_agent_sessions if native Codex/OpenCode/Claude session history may contain relevant current-state context.
3. Summarize only useful carry-forward context.
4. Call context_workspace_write_recall_cache.
5. Verify with context_workspace_read_recall_cache.
6. Report the refresh result briefly before continuing.

Use this report shape:

Recall refreshed:
- project_dir: /mnt/c/Users/you/context-workspace
- query: <session_search query>
- bytes: <bytes written>

If there are no useful prior-session results, write a short empty-state summary instead of leaving stale recall in place:

## Recall

- No relevant prior-session context found for this task.

Context Workspace Refresh Hook

Context Workspace can request recall refresh through:

POST /hermes/recall/refresh

The backend runs the command configured in:

CONTEXT_WORKSPACE_HERMES_REFRESH_CMD

The Electron launcher sets a default command when the user has not provided one:

python scripts/hermes-refresh-recall.py

That script writes the project-local recall cache directly and includes native Codex/OpenCode/Claude session discovery as fallback context. Use a custom CONTEXT_WORKSPACE_HERMES_REFRESH_CMD when Hermes should run a fuller session_search refresh before writing recall.

When invoked, the command receives:

CONTEXT_WORKSPACE_PROJECT_DIR=<native project path>
CONTEXT_WORKSPACE_TASK_HINT=<current task or launch hint>
CONTEXT_WORKSPACE_BACKEND_URL=<backend URL>

The configured command should start Hermes with this skill or equivalent standing instruction. Hermes must run session_search, summarize useful prior context, call context_workspace_write_recall_cache, and exit nonzero if refresh fails.

Context Workspace uses this hook in three places:

• Manual Refresh recall action in the workspace UI.
• Pre-launch refresh before non-shell agent terminals start when recall is missing or stale.
• Background refresh after workspace selection when recall is missing or stale and the hook is configured.

If pre-launch refresh fails or the hook is not configured, Context Workspace asks the user whether to proceed with stale or missing recall.

Refresh Recall

1. Run Hermes session_search for the current project, branch, task, or problem.
2. Inspect native agent session history when useful:

{
  "project_dir": "/mnt/c/Users/you/context-workspace",
  "query": "recall Hermes sessions",
  "limit": 25
}

Use context_workspace_summarize_agent_sessions for a compact text result, or context_workspace_list_agent_sessions when exact session metadata is needed.

3. Summarize only the useful carry-forward context:
   • current objective
   • important decisions
   • relevant PRs, branches, commits, and files
   • known failures or caveats
   • next steps future agents should inherit
4. Call context_workspace_write_recall_cache:

{
  "project_dir": "/mnt/c/Users/you/context-workspace",
  "markdown": "## Recall\n\n- Concise project/session context here.\n"
}

Keep the markdown concise. Do not paste raw search dumps unless the exact text is needed.

Prefer replacing the whole cache with the latest summary. Do not append indefinitely.

Verify Recall

Call context_workspace_read_recall_cache:

{
  "project_dir": "/mnt/c/Users/you/context-workspace"
}

Expect exists: true and the markdown that was just written.

Future Context Workspace runs read this file directly:

<project>/.context-workspace/hermes/session-recall.md

The generated run context includes it under:

## Hermes Session Recall Cache

Clear Recall

If recall conflicts with current user instructions, points at the wrong branch/task, or becomes stale or harmful, call context_workspace_clear_recall_cache:

{
  "project_dir": "/mnt/c/Users/you/context-workspace"
}

Then refresh recall before launching more agents.

When clearing, report it:

Recall cleared:
- project_dir: /mnt/c/Users/you/context-workspace
- reason: <why the previous cache was stale or harmful>

Operating Rules

• Treat Hermes memory as the durable source of truth.
• Treat the recall cache as a short-lived working summary for one project.
• Refresh recall at the start of each new work session.
• Refresh recall when the task, branch, or investigation direction changes.
• Prefer overwriting stale recall over appending indefinitely.
• Verify after writing so skipped or failed refreshes are visible.
• Report refresh or clear results so the user can audit whether the workflow happened.
• Do not rely on future agents calling Hermes directly; Context Workspace injects the latest recall into their generated context.md.

Responsibility Split

Hermes = search old sessions, decide when to refresh, summarize, refresh or clear recall
Context Workspace = expose app-side tools, inspect native agent sessions, inject latest recall into future agent context
Agents = consume generated context.md

Troubleshooting

If backend-dependent tools fail, check context_workspace_health.

If health fails, start Context Workspace Electron first so this file exists:

/mnt/c/Users/you/.context-workspace/backend.json

Recall cache tools can still operate without the backend because they read and write project-local files.