Claude Code Integration Guide

Give Claude Code persistent, complete memory across sessions using Engram.

How Claude Code Stores Conversations

Claude Code writes every message, tool call, and response to JSONL transcript files at:


~/.claude/projects/<project-hash>/<session-id>.jsonl

These files contain the complete, uncompressed record of everything that happened in a session. When Claude Code hits its context window limit, it compresses older messages to make room — but the JSONL files on disk still have everything.

Engram captures these transcripts automatically. A background daemon watches the JSONL files as they’re written and syncs them to your Engram account. Nothing is lost, even after Claude Code has forgotten it.

Setup

1. Get an API Key

2. Install and Start the Daemon

Homebrew (recommended):


brew tap get-engram/engram
brew install engram
engram auth login engram_sk_live_YOUR_KEY
brew services start engram

npm:


npm install -g @getengram/cli
engram auth login engram_sk_live_YOUR_KEY
engram start --install

The daemon now auto-captures every Claude Code session. It starts on login, restarts if it crashes, and queues messages offline if the network is unavailable.

3. Verify It’s Working

After your next Claude Code session, check:


engram log

You should see your session listed with project name, branch, and message count.

4. Search Your History


engram search "when did we set up the database"

Returns matching conversation fragments with relevance scores — from any session, any project.

Add the MCP Server (Optional)

The daemon captures everything automatically. But you can also connect Engram as an MCP server so Claude Code can search its memory during a session — recalling prior decisions, investigations, and context.

Global (all projects) — add to ~/.claude/settings.json:


{
  "mcpServers": {
    "engram": {
      "type": "url",
      "url": "https://mcp.getengram.app/mcp",
      "headers": {
        "Authorization": "Bearer engram_sk_live_your_key_here"
      }
    }
  }
}

Per-project — add .mcp.json to the project root:


{
  "mcpServers": {
    "engram": {
      "type": "url",
      "url": "https://mcp.getengram.app/mcp",
      "headers": {
        "Authorization": "Bearer engram_sk_live_your_key_here"
      }
    }
  }
}

Verify Connection

Start a Claude Code session and ask:


Search Engram for "test"

If you see search results (or an empty results array), Engram is connected.

Automatic Memory via CLAUDE.md

With the MCP server connected, you can configure Claude Code to search and store memories automatically. This is configured through CLAUDE.md, the project instruction file that Claude Code loads at the start of every session.

Add Memory Instructions to CLAUDE.md

Add this block to your project’s CLAUDE.md:


## Engram Memory
 
You have access to Engram as an MCP server. Use it to maintain persistent memory across sessions.
 
### On session start
 
Search Engram for context relevant to the current task:
 
    search
      query: "<summary of what the user is asking about>"
      limit: 5
 
Include any relevant results in your working context — they contain prior conversations about this project, decisions made, bugs investigated, and user preferences.
 
### During the session
 
When significant work is done or important context is established, store it:
 
    create_conversation
      title: "<concise description of what was discussed>"
      agent_id: "claude-code"
      tags: ["<project-name>", "<topic>"]
      metadata: { "project": "<project-name>", "branch": "<current branch if relevant>" }
 
    append_messages
      conversation_id: "<the conversation ID>"
      messages:
        - role: "user"
          content: "<what the user asked>"
        - role: "assistant"
          content: "<what you did and why>"
 
### What to store
 
- Decisions and their reasoning ("we chose X because Y")
- Bug investigations and resolutions
- User preferences and workflow patterns
- Architecture discussions
- Anything you'd want to remember next session
 
### What NOT to store
 
- Routine file reads or searches (these are in git)
- Trivial exchanges ("hello", "thanks")
- Information already in the codebase or git history

How It Works

Claude Code loads CLAUDE.md at the start of every session
The memory instructions tell it to search Engram for relevant context
During the session, it stores important decisions and context
Next session, it finds that context via semantic search

No manual intervention needed. The agent just remembers.

How Claude Code Sees Engram

When you connect Engram as an MCP server, Claude Code discovers the tools automatically. It reads the tool descriptions, understands what each one does, and figures out how Engram complements its built-in file-based memory — without any prompting.

Here’s what Claude Code says when it first discovers Engram in a project:

What it is: Engram is an MCP-based semantic memory/conversation store. It’s configured via ENGRAM_API_KEY and ENGRAM_ORG_ID in the .env file.

How it works:

create_conversation — Start a new named thread with tags

append_messages — Add messages to a conversation

search — Semantic search across all stored conversations

get_conversation — Retrieve full message history

list_conversations — Browse/filter conversations

How it differs from my file-based memory: Engram is better for storing detailed investigation logs, debugging sessions, and rich context that can be semantically searched later. My file-based memory (/memory/ folder) is better for concise, structured facts. They complement each other — engram for detailed “what happened” narratives, file memory for distilled “what to remember” facts.

This is the key insight: Claude Code understands that Engram is for rich, searchable context while its built-in memory is for quick-reference facts. It uses both.

What Happens in Practice

Once Claude Code discovers Engram, it starts using it immediately:

Searches on session start — When you start a new session, Claude Code searches Engram for conversations relevant to your current task
Stores investigations — When debugging a complex bug, it creates a conversation with descriptive tags and stores the full investigation log
Recalls across projects — A bug investigated in one project can be found when a similar issue appears in another

Real Example

A user connected Engram to a project and asked Claude Code to investigate a stuck automation. Claude Code:

Searched Engram and found a prior investigation about the same system
Created a new conversation: “Email Newsletter Board Investigation” with tags email-newsletter, make-scenario, bug, board-restructure
Stored the root cause finding: the board was restructured (columns deleted) but the automation scenarios were never updated, causing a “Processing” status to get stuck
Next session, when asked about the same system, it found this conversation instantly via semantic search

No manual tagging. No copy-pasting context. The agent just remembered.

Example: Memory in Action

Session 1 (Monday):


You: Let's use Postgres instead of MySQL for the new service.
     The JSONB support is better for the catalog schema.

Claude Code: [searches Engram — no prior context]
Claude Code: I'll set up Postgres. Creating the schema now...
Claude Code: [stores in Engram:
  title: "Database choice for new service"
  tags: ["architecture", "database"]
  messages: decision to use Postgres over MySQL, reasoning about JSONB]

Session 2 (Thursday):


You: Set up the database for the new service.

Claude Code: [searches Engram → finds Monday's conversation]
Claude Code: Setting up Postgres — we decided on Monday to use it instead
             of MySQL because of the JSONB support for the catalog schema.
             Creating the migrations now...

No re-explaining. No lost context. The agent just knows.

Tips

Use descriptive tags. Tags like ["auth", "bugfix"] or ["architecture", "database"] make it easier to find relevant context later.
One CLAUDE.md per project. Each project can have its own memory instructions with project-specific tags and metadata.
Share across a team. If your team uses the same Engram API key, everyone’s Claude Code sessions contribute to shared organizational memory. A decision made by one developer is recalled by another’s agent.
Use agent_id: "claude-code" to distinguish Claude Code memories from memories created by other tools (Cursor, Claude Desktop, etc.).

Shared Memory Across Tools

If you use the same Engram API key in Claude Code and other tools (Claude Desktop, Cursor, etc.), all of them read from and write to the same memory. A bug investigated in Claude Code can be recalled by Cursor. An architecture decision made in Claude Desktop informs Claude Code.

See the other integration guides for setting up additional tools with the same API key.