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

> Learn how harness-mem enables cross-session memory persistence in claude-code-harness. Discover its unified SQLite database and state files for seamless session recovery.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: deep-dive
- Published: 2026-05-28

---

**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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/session-init/SKILL.md). This executes the function:

```text
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/decisions.md)** – Past architectural decisions and rationale
- **[`patterns.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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:

```bash

# 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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-work/SKILL.md) and [`CHANGELOG.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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.

```bash

# 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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.harness-mem/state/continuity.json) maintain lightweight session pointers.
- The bridge script at [`scripts/lib/harness-mem-bridge.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-work/SKILL.md) and the [`CHANGELOG.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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.