claude-mem/docs/reports/2026-01-04--session-store-failures.md

SessionStore Test Failures Analysis

Date: 2026-01-04 Category: SessionStore Failing Tests: 2 File: tests/session_store.test.ts

---

1. Executive Summary

Two tests in the SessionStore test suite are failing due to SQLite foreign key constraint violations. The tests attempt to store observations and summaries using a memory_session_id that does not exist in the sdk_sessions table, because createSDKSession() now stores memory_session_id as NULL instead of setting it to the content_session_id.

This is a test design issue, not a production bug. The tests were written before a critical architectural change that separated memory_session_id from content_session_id to prevent memory messages from being injected into user transcripts.

---

2. Test Analysis

Test 1: should store observation with timestamp override

Location: Lines 36-74

What it does:

1. Creates an SDK session using createSDKSession(claudeId, project, prompt)
2. Constructs an observation object
3. Calls storeObservation(claudeId, project, observation, promptNumber, 0, pastTimestamp)
4. Expects the observation to be stored with the overridden timestamp
5. Retrieves the observation and verifies created_at_epoch matches the override

Expected behavior:

• Observation should be stored with createdAtEpoch = 1600000000000
• Retrieved observation should have created_at_epoch = 1600000000000
• ISO string should match the epoch timestamp

Actual error:

SQLiteError: FOREIGN KEY constraint failed

Test 2: should store summary with timestamp override

Location: Lines 76-105

What it does:

1. Creates an SDK session using createSDKSession(claudeId, project, prompt)
2. Constructs a summary object
3. Calls storeSummary(claudeId, project, summary, promptNumber, 0, pastTimestamp)
4. Expects the summary to be stored with the overridden timestamp
5. Retrieves the summary and verifies created_at_epoch matches the override

Expected behavior:

• Summary should be stored with createdAtEpoch = 1650000000000
• Retrieved summary should have created_at_epoch = 1650000000000

Actual error:

SQLiteError: FOREIGN KEY constraint failed

---

3. Current Implementation Status

Schema (from initializeSchema())

observations table:

CREATE TABLE observations (
  ...
  memory_session_id TEXT NOT NULL,
  ...
  FOREIGN KEY(memory_session_id) REFERENCES sdk_sessions(memory_session_id) ON DELETE CASCADE
);

session_summaries table:

CREATE TABLE session_summaries (
  ...
  memory_session_id TEXT NOT NULL,
  ...
  FOREIGN KEY(memory_session_id) REFERENCES sdk_sessions(memory_session_id) ON DELETE CASCADE
);

createSDKSession Implementation (Lines 1164-1182)

createSDKSession(contentSessionId: string, project: string, userPrompt: string): number {
  const now = new Date();
  const nowEpoch = now.getTime();

  // NOTE: memory_session_id starts as NULL. It is captured by SDKAgent from the first SDK
  // response and stored via updateMemorySessionId(). CRITICAL: memory_session_id must NEVER
  // equal contentSessionId - that would inject memory messages into the user's transcript!
  this.db.prepare(`
    INSERT OR IGNORE INTO sdk_sessions
    (content_session_id, memory_session_id, project, user_prompt, started_at, started_at_epoch, status)
    VALUES (?, NULL, ?, ?, ?, ?, 'active')
  `).run(contentSessionId, project, userPrompt, now.toISOString(), nowEpoch);

  // Return existing or new ID
  const row = this.db.prepare('SELECT id FROM sdk_sessions WHERE content_session_id = ?')
    .get(contentSessionId) as { id: number };
  return row.id;
}

Key observation: memory_session_id is inserted as NULL, and must be updated later via updateMemorySessionId().

storeObservation Implementation (Lines 1224-1273)

The method expects memorySessionId as the first parameter and uses it directly to insert into the observations table:

storeObservation(
  memorySessionId: string,  // <-- This is the FK value
  project: string,
  ...
)

storeSummary Implementation (Lines 1279-1324)

Similar to storeObservation, expects memorySessionId as first parameter:

storeSummary(
  memorySessionId: string,  // <-- This is the FK value
  project: string,
  ...
)

---

4. Root Cause Analysis

The Problem

The tests pass claudeId (which equals content_session_id) to storeObservation() and storeSummary(), but these methods require a valid memory_session_id that exists in sdk_sessions.memory_session_id.

Flow of test:

1. createSDKSession('claude-sess-obs', ...) creates a row with:

   • content_session_id = 'claude-sess-obs'
   • memory_session_id = NULL

2. storeObservation('claude-sess-obs', ...) tries to insert with:

   • memory_session_id = 'claude-sess-obs'

3. FK check: Does 'claude-sess-obs' exist in sdk_sessions.memory_session_id? NO (it's NULL)

4. Result: FOREIGN KEY constraint failed

Historical Context

The test comments reveal the original assumption (lines 40-42):

// createSDKSession inserts using memory_session_id = content_session_id in the current implementation
// "VALUES (?, ?, ?, ?, ?, ?, 'active')" -> contentSessionId, contentSessionId, ...

This comment is outdated. The implementation was changed to set memory_session_id = NULL to prevent memory messages from leaking into user transcripts (a critical architectural fix noted in the code comment at line 1170-1171).

Why This Matters

In production, the flow is:

1. Hook creates session with memory_session_id = NULL
2. SDKAgent processes messages and captures the actual memory session ID from the SDK response
3. updateMemorySessionId() is called to set the proper value
4. Only then can observations/summaries be stored

The tests skip step 2-3, which is why they fail.

---

5. Recommended Fixes

Option A: Update Tests to Use Proper Flow (Recommended)

Modify the tests to call updateMemorySessionId() before storing observations/summaries:

it('should store observation with timestamp override', () => {
  const claudeId = 'claude-sess-obs';
  const memorySessionId = 'memory-sess-obs';  // Separate ID
  const sessionDbId = store.createSDKSession(claudeId, 'test-project', 'initial prompt');

  // Simulate SDKAgent capturing the memory session ID
  store.updateMemorySessionId(sessionDbId, memorySessionId);

  const obs = { ... };
  const pastTimestamp = 1600000000000;

  const result = store.storeObservation(
    memorySessionId,  // Use the memory session ID, not claudeId
    'test-project',
    obs,
    1,
    0,
    pastTimestamp
  );

  expect(result.createdAtEpoch).toBe(pastTimestamp);
  // ... rest of assertions
});

Similar change for the summary test.

Option B: Add Test Helper Method

Create a helper that combines session creation and memory ID assignment:

function createTestSession(store: SessionStore, sessionId: string, project: string): { dbId: number; memorySessionId: string } {
  const memorySessionId = `memory-${sessionId}`;
  const dbId = store.createSDKSession(sessionId, project, 'test prompt');
  store.updateMemorySessionId(dbId, memorySessionId);
  return { dbId, memorySessionId };
}

Option C: Keep Tests Simple with In-Memory Workaround

For unit tests only, after createSDKSession(), manually set the memory_session_id:

beforeEach(() => {
  store = new SessionStore(':memory:');
  // No workaround here, but tests must explicitly call updateMemorySessionId
});

---

6. Priority/Effort Estimate

Metric	Value
Priority	Medium
Effort	Low (15-30 minutes)
Risk	Low
Impact	Test suite only, no production impact

Reasoning

• Medium priority: Tests should pass, but this doesn't affect production functionality
• Low effort: Simple test modifications, no architectural changes needed
• Low risk: Only test code changes, implementation is correct
• No production impact: The FK constraint is working correctly in production where the proper flow (session creation -> memory ID assignment -> observation storage) is followed

---

7. Additional Notes

Test Comment Accuracy

The test file contains an outdated comment that should be removed or updated:

// createSDKSession inserts using memory_session_id = content_session_id in the current implementation

This is no longer accurate and may confuse future developers.

Related Architecture Decision

The separation of memory_session_id from content_session_id is intentional and critical. From the implementation comment:

CRITICAL: memory_session_id must NEVER equal contentSessionId - that would inject memory messages into the user's transcript!

The tests should reflect and respect this architectural decision rather than assuming the two IDs are the same.