How to Implement Memory Persistence Across ECC Sessions: A Complete Guide

To implement memory persistence across ECC sessions, write plain text files to the .memory/ directory or ~/.claude/memory/, and let the built-in SessionStart, PreCompact, and SessionEnd hooks automatically load, snapshot, and persist your data across Claude Code runs.

The affaan-m/ECC (Everything Claude Code) repository provides a robust memory persistence subsystem that enables contextual continuity between Claude Code sessions. This system leverages lifecycle hooks defined in hooks/hooks.json to automatically manage memory files at critical moments—session startup, context compaction, and session termination. By understanding how to interact with these hooks, you can retain critical project context, user preferences, and session summaries across multiple runs without manual intervention.

Understanding the ECC Memory Persistence Lifecycle

ECC implements memory persistence through three primary lifecycle hooks that run automatically at specific phases of a session. These hooks are orchestrated by the manifest in hooks/hooks.json and executed via Node.js scripts in the scripts/hooks/ directory.

SessionStart Hook

The SessionStart hook (manifest entry session:start in hooks/hooks.json) fires at the very beginning of a new Claude Code session. According to the implementation in scripts/hooks/session-start-bootstrap.js, this hook:

• Resolves the plugin root directory
• Dispatches to scripts/hooks/session-start.js (referenced in the bootstrap logic)
• Reads all plain text files from the memory directories (.memory/ or ~/.claude/memory/)
• Concatenates file contents up to the limit defined by ECC_SESSION_START_MAX_CHARS
• Injects the combined text into the session’s initial bounded context

No manual loading is required—if memory files exist in the supported directories, the SessionStart hook automatically makes them available to the assistant.

PreCompact Hook

The PreCompact hook (manifest entry pre:compact in hooks/hooks.json) executes immediately before the /compact command prunes conversation context. The script scripts/hooks/pre-compact.js performs a critical snapshot operation:

• Copies the current in-memory state, including any newly created memory files
• Preserves valuable data that might otherwise be lost during context compaction
• Stores the snapshot for later use by the SessionEnd hook

This ensures that memory files created during long sessions survive the compaction process.

SessionEnd Hook

The SessionEnd hook (manifest entry stop:session-end in hooks/hooks.json) runs when the session terminates via the /stop command or natural exit. The scripts/hooks/session-end.js script:

• Writes a session-end marker containing metadata about the completed session
• Merges any newly generated memory files into the persistent store
• Logs the final transcript path for downstream tooling

The session-end marker acts as a JSON payload that the next SessionStart hook can consume to reconstruct session continuity.

Configuring Memory Storage Locations

ECC supports two storage locations for memory files, prioritized automatically by the SessionStart hook:

Project-local storage: Create a .memory/ directory at the repository root. This location is ideal for project-specific context that should travel with the codebase.

User-wide storage: Use ~/.claude/memory/ for cross-project notes and preferences that persist across different repositories.

The SessionStart hook checks both locations and concatenates contents from all discovered files. According to hooks/memory-persistence/README.md, project-local memory takes precedence and is recommended for data tightly coupled to the repository, while the global directory suits user-wide preferences.

Managing Size Limits

The ECC_SESSION_START_MAX_CHARS environment variable controls how much text the SessionStart hook loads into context. Default limits prevent context window overflow, but you can adjust this for larger knowledge bases:

export ECC_SESSION_START_MAX_CHARS=20000

Writing and Reading Memory Files

To add data to the persistent memory store, use the standard Write tool (which internally calls fs.writeFileSync) within your Claude Code session:

{
  "filePath": "/path/to/repo/.memory/project-goals.txt",
  "content": "Goal: implement semantic search by end-of-Q2.\nPriority: high.\nTech stack: React + TypeScript."
}

For user-wide persistence:

{
  "filePath": "/home/user/.claude/memory/user-preferences.txt", 
  "content": "User prefers detailed comments in code.\nPreferred testing framework: Vitest."
}

The next session automatically reads these files. The SessionStart hook in session-start-bootstrap.js handles the file system operations and content injection without requiring manual parsing.

Automatic Lifecycle Management

Once you write a memory file, the ECC hook system manages persistence automatically:

1. During active work: Create or update files in .memory/ as your project evolves
2. Before compaction: Run /compact to trigger the PreCompact hook, which snapshots current memory via scripts/hooks/pre-compact.js
3. Session termination: Execute /stop to invoke the SessionEnd hook (scripts/hooks/session-end.js), which finalizes persistence
4. New session startup: The SessionStart hook loads all persisted content into the initial context

This workflow requires no manual intervention beyond the initial file creation.

Best Practices and Security Considerations

When implementing memory persistence across ECC sessions, follow these guidelines from the source documentation:

• Never store secrets: The hooks/memory-persistence/README.md explicitly warns against persisting passwords, API keys, or credentials in memory files (lines 29-33). These files are stored locally and readable by other processes.
• Keep files small and structured: Large memory files consume valuable context window space. Use concise, well-formatted plain text.
• Write before compacting: Ensure critical updates are saved to disk before invoking /compact, as the PreCompact hook only snapshots existing files.
• Use descriptive filenames: Name files according to their content type (e.g., project-goals.txt, api-considerations.txt) to facilitate manual inspection.

Summary

• Memory persistence in ECC relies on three lifecycle hooks managed through hooks/hooks.json: SessionStart (load), PreCompact (snapshot), and SessionEnd (persist).
• Storage locations are .memory/ (project-local) and ~/.claude/memory/ (user-wide), with the SessionStart hook automatically concatenating contents from both.
• File creation uses standard write operations; the system handles all subsequent loading and persistence automatically.
• Size limits are controlled by ECC_SESSION_START_MAX_CHARS, preventing context overflow while allowing configurable limits.
• Security requires avoiding secrets in memory files, as they persist to local disk and could be accessed by other processes.

Frequently Asked Questions

Where does ECC actually store the memory files between sessions?

ECC stores memory files as plain text in either ./.memory/ (relative to the repository root) or ~/.claude/memory/ in the user's home directory. The SessionStart hook in scripts/hooks/session-start-bootstrap.js reads from both locations, concatenates the files (respecting ECC_SESSION_START_MAX_CHARS), and injects the content into the new session's context. No database or binary storage is used—standard file system operations persist the data across runs.

How do I prevent sensitive information from being persisted accidentally?

According to the hooks/memory-persistence/README.md (lines 29-33), you should never write passwords, API keys, or other secrets to memory files. The system persists these as plain text files on local disk, readable by any process with file system access. Instead, use memory files for non-sensitive context like project goals, coding preferences, or architectural decisions. For secrets, rely on environment variables or dedicated secret management tools outside of the ECC memory system.

What happens to my memory if I use the /compact command?

Before the /compact command prunes conversation context, ECC automatically triggers the PreCompact hook defined in hooks/hooks.json. The scripts/hooks/pre-compact.js script snapshots the current state, including any memory files created during the session. This ensures that valuable information survives the compaction process. After compaction, you can continue working, and the SessionEnd hook will still persist the final memory state when you eventually run /stop.

Can I adjust how much memory content loads into each new session?

Yes. The SessionStart hook respects the ECC_SESSION_START_MAX_CHARS environment variable, which caps the total characters loaded from memory files into the initial context. By default, this limit prevents context window overflow, but you can increase it for larger knowledge bases by setting the variable before starting Claude Code: export ECC_SESSION_START_MAX_CHARS=20000. The hook truncates content exceeding this limit, so prioritize essential information in your memory files.

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