claude-mem/docs/context/CWD_CONTEXT_FIX.md

CWD Context Fix - Technical Documentation

Overview

This fix adds working directory (CWD) context propagation through the entire claude-mem pipeline, enabling the SDK agent to have spatial awareness of which directory/repository it's observing.

Problem Statement

Previously, the SDK agent would:

• Search wrong repositories when analyzing file operations
• Report "file not found" for files that actually exist
• Lack context about which project was being worked on
• Generate inaccurate observations due to spatial confusion

Solution

The CWD information now flows through the entire system:

Hook Input (cwd) → Worker API (cwd) → SessionManager (cwd) → SDK Agent (tool_cwd)

Data Flow

1. Hook Layer (save-hook.ts)

export interface PostToolUseInput {
  session_id: string;
  cwd: string;  // ← Captured from Claude Code
  tool_name: string;
  tool_input: any;
  tool_response: any;
}

The hook extracts cwd and includes it in the worker API request:

body: JSON.stringify({
  tool_name,
  tool_input,
  tool_response,
  prompt_number,
  cwd: cwd || ''  // ← Passed to worker
})

2. Worker Service (worker-service.ts)

const { tool_name, tool_input, tool_response, prompt_number, cwd } = req.body;

this.sessionManager.queueObservation(sessionDbId, {
  tool_name,
  tool_input,
  tool_response,
  prompt_number,
  cwd  // ← Forwarded to queue
});

3. Session Manager (SessionManager.ts)

session.pendingMessages.push({
  type: 'observation',
  tool_name: data.tool_name,
  tool_input: data.tool_input,
  tool_response: data.tool_response,
  prompt_number: data.prompt_number,
  cwd: data.cwd  // ← Included in message queue
});

4. SDK Agent (SDKAgent.ts)

content: buildObservationPrompt({
  id: 0,
  tool_name: message.tool_name!,
  tool_input: JSON.stringify(message.tool_input),
  tool_output: JSON.stringify(message.tool_response),
  created_at_epoch: Date.now(),
  cwd: message.cwd  // ← Passed to prompt builder
})

5. Prompt Generation (prompts.ts)

return `<tool_used>
  <tool_name>${obs.tool_name}</tool_name>
  <tool_time>${new Date(obs.created_at_epoch).toISOString()}</tool_time>${obs.cwd ? `
  <tool_cwd>${obs.cwd}</tool_cwd>` : ''}  // ← Included in XML
  <tool_input>${JSON.stringify(toolInput, null, 2)}</tool_input>
  <tool_output>${JSON.stringify(toolOutput, null, 2)}</tool_output>
</tool_used>`;

SDK Agent Prompt Changes

The init prompt now includes a "SPATIAL AWARENESS" section:

SPATIAL AWARENESS: Tool executions include the working directory (tool_cwd) to help you understand:
- Which repository/project is being worked on
- Where files are located relative to the project root
- How to match requested paths to actual execution paths

Example Usage

When a user executes a read operation in /home/user/my-project:

<tool_used>
  <tool_name>ReadTool</tool_name>
  <tool_time>2025-11-10T19:18:03.065Z</tool_time>
  <tool_cwd>/home/user/my-project</tool_cwd>
  <tool_input>
  {
    "path": "src/index.ts"
  }
  </tool_input>
  <tool_output>
  {
    "content": "export default..."
  }
  </tool_output>
</tool_used>

The SDK agent now knows:

1. The operation happened in /home/user/my-project
2. The file src/index.ts is relative to that directory
3. Which repository context to search when generating observations

Testing

8 comprehensive tests validate the CWD propagation:

npx tsx --test tests/cwd-propagation.test.ts

All tests verify:

• Type interfaces include cwd fields
• Hook extracts and passes cwd
• Worker accepts and forwards cwd
• SDK agent includes cwd in prompts
• End-to-end flow is correct

Benefits

1. Spatial Awareness: SDK agent knows which directory/repository it's observing
2. Accurate Path Matching: Can verify if requested paths match executed paths
3. Better Summaries: Won't search wrong repositories or report false negatives
4. Works with All Models: Even Haiku benefits from correct context (no need for Opus workaround)

Backward Compatibility

• cwd is optional in all interfaces (cwd?: string)
• Missing cwd values are handled gracefully (defaults to empty string)
• Existing observations without cwd continue to work
• No database migration required (CWD is transient, not persisted)

Related Issues

Fixes issue #73 (CWD context missing from SDK agent)