How harness-mem Provides Cross-Session Memory Persistence in claude-code-harness

harness-mem provides cross-session memory persistence by maintaining a unified SQLite database and project-specific state files that generate resume packs for new Claude sessions.

The claude-code-harness repository implements a companion memory service called harness-mem that enables AI agents to retain project knowledge across disconnected work sessions. This system ensures that architectural decisions, code patterns, and task progress survive process restarts and persist across different host adapters including Claude, Codex, and OpenCode.

Three-Layer Storage Architecture

The persistence mechanism relies on a tiered architecture that separates global storage from project-local metadata.

Unified SQLite Database

All memory records live in a single file at ~/.harness-mem/harness-mem.db. This common DB stores decisions, reusable patterns, checkpoint metadata, and session history for every project. Because the database is never deleted automatically—following the rule documented in docs/onboarding/migration.md that states "memory DB を削除しない" (do not delete the memory DB)—data survives across machine restarts and migrations.

Project-Specific State Directory

Each checkout maintains a small continuity file under .harness-mem/state/continuity.json. This JSON file tracks the last recorded checkpoint and session ID, acting as a lightweight pointer into the global database. It allows the system to determine exactly where a specific project left off without scanning the entire SQLite store.

Bridge and Client Scripts

The scripts/lib/harness-mem-bridge.sh script locates the sibling harness-mem repository (or respects a user-provided $HARNESS_MEM_ROOT) and executes the real wrapper scripts (harness-mem-client.sh, harness-memd). When invoked during session startup, the bridge returns a resume pack containing historical context that is injected into the new Claude context.

Session Initialization and Resume Packs

When a new session begins, the session-init skill runs the "Unified Harness Memory Resume Pack" step defined in skills/session-init/SKILL.md. This executes the function:

harness_mem_resume_pack(project, session_id?, limit=5, include_private=false)

The function communicates with the harness-mem daemon, queries the SQLite database for the most recent records matching the project identifier, and returns a structured JSON resume pack containing:

• decisions.md – Past architectural decisions and rationale
• patterns.md – Reusable code patterns and conventions
• session-state – The last session's state, including unfinished tasks
• checkpoint – The most recent completion marker before the pause

This pack is written to .claude/state/resume-pack.json and injected into the model's prompt context, allowing Claude to continue exactly where the previous session ended.

Recording Progress Across Sessions

During active work, the harness-work and harness-sync skills record progress back into harness-mem by invoking specific checkpoint functions:

# Record completion of a specific task

harness_mem_record_checkpoint \
    project="claude-code-harness" \
    session_id="${CLAUDE_SESSION_ID}" \
    task_id="R42" \
    status="completed"

# Finalize the session when all tasks are complete

harness_mem_finalize_session \
    project="claude-code-harness" \
    session_id="${CLAUDE_SESSION_ID}"

These calls write new entries to the SQLite database and update the project's continuity.json file. Because updates are atomic and the database file is persistent, cross-session memory remains consistent even if the host process crashes or the machine reboots.

Fail-Open Safety Mechanisms

If the harness-mem daemon is unavailable, the system follows a fail-open policy. The harness_mem_health() function in the bridge scripts prints a diagnostic warning, and the session proceeds without a resume pack. As noted in skills/harness-work/SKILL.md and CHANGELOG.md, the session initialization logic specifically handles the case where "resume pack generation now works when harness-mem is missing", ensuring that work can continue even when the memory service is offline.

# Generate a resume pack at session start (internal implementation)

resume=$(harness_mem_resume_pack \
          project="$(basename "$(git rev-parse --show-toplevel)")" \
          session_id="${CLAUDE_SESSION_ID}" \
          limit=5)

# Diagnostic utilities

scripts/harness-memd health
bin/harness doctor --migration-report

Summary

• harness-mem uses a unified SQLite database at ~/.harness-mem/harness-mem.db to store all memory records across projects.
• Project-specific continuity files in .harness-mem/state/continuity.json maintain lightweight session pointers.
• The bridge script at scripts/lib/harness-mem-bridge.sh connects the harness to the memory daemon and handles resume pack generation.
• The harness_mem_resume_pack function injects historical context into new sessions via the session-init skill.
• Checkpoint recording via harness_mem_record_checkpoint and harness_mem_finalize_session ensures durability across restarts.
• The system implements a fail-open policy that allows sessions to start even when the memory daemon is unavailable.

Frequently Asked Questions

What happens if the harness-mem daemon is not running?

The system implements a fail-open policy. When the daemon is unreachable, the harness_mem_health() function prints a warning to stderr, and the session initialization proceeds without injecting a resume pack. The session starts fresh but remains fully functional, as documented in skills/harness-work/SKILL.md and the CHANGELOG.md entry regarding resume pack generation.

Where is the cross-session memory data physically stored?

Persistent data resides in two locations: a global SQLite database at ~/.harness-mem/harness-mem.db storing all records across projects, and project-specific metadata in .harness-mem/state/continuity.json within each repository checkout. The global database follows a strict "never delete" policy, ensuring survival across machine migrations.

How does claude-code-harness retrieve previous session context?

The session-init skill calls harness_mem_resume_pack(), which queries the SQLite database for records matching the current project identifier. It returns a JSON structure containing previous decisions, patterns, and checkpoint data. This resume pack is injected into the Claude context before the session begins, enabling seamless continuation of interrupted work.

Is the memory database ever automatically deleted?

No. According to docs/onboarding/migration.md, the system adheres to the rule "memory DB を削除しない" (do not delete the memory DB). The database persists indefinitely until manually removed by the user, ensuring that cross-session memory survives across restarts, host adapter changes, and even different machines sharing the same home directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}