SHEET 01.T/05 · CCRECALL · TUTORIAL ccFamily

ccFamily / ccRecall / Tutorial

SECT. 01 // QUICK START · ~5 MIN · MACOS PRIMARY

Zero to
memory,
in 4 + 1 steps

// INSTALL → DAEMON → MCP → HOOKS → (DISTILL) · LOCAL ONLY

npm install is just the start. The daemon isn't running yet, MCP isn't wired, and hooks aren't configured. This page walks you through 4 steps to get the system live, then a 5th (optional) that makes memories grow on their own.

[ ▼ START ] [ ← OVERVIEW ] [ ⭐ GITHUB → ]

SECT. 02 // PREREQUISITES · CHECK BEFORE START

Before you start / have these ready

You don't need to know SQLite, FTS5, or MCP internals — they come up as needed. Just the environment itself.

✓ 01 REQUIRED

Claude Code CLI

Not installed? See the official guide. This tutorial doesn't cover Claude Code installation.

✓ 02 PRIMARY

macOS

Auto-start uses LaunchAgent (macOS only). Linux / Windows can run the daemon in foreground — the daemon itself is cross-platform.

✓ 03 VERSION

Node.js 20–22

Check your version:

node --version

✓ 04 BASIC

Terminal comfort

cd, run commands, read logs. You don't need SQLite, shell scripting, or systemd.

SECT. 03 // 4 STEPS TO LIVE + 1 TO GROW · COPY-PASTE READY

Four steps / one command each

Each step is a single command. If one fails, it doesn't break the previous step — try them one at a time without worry. These four make the system usable; a fifth step makes memories accumulate, and it's at the end.

→ 01 / 04 INSTALL

Install the npm package

You'll get two CLI commands: ccmem (the daemon itself) and ccmem-mcp (the MCP server Claude Code calls).

CMD

npm install -g @tznthou/ccrecall

Why is the binary called ccmem instead of ccrecall? Because ccrecall on npm is already taken by spences10/ccrecall — an unrelated analytics tool. The project is still ccRecall; only the binary name sidesteps the conflict.

→ 02 / 04 DAEMON

Run the daemon at login

One command registers the daemon as a macOS LaunchAgent: writes the plist to ~/Library/LaunchAgents/, creates the log directory, starts immediately, and keeps starting at every login.

CMD

ccmem install-daemon

// LINUX / WINDOWS / JUST TRYING → run in foreground

ccmem # Ctrl+C to quit

→ 03 / 04 MCP

Wire it to Claude Code

CMD

claude mcp add ccrecall --scope user -- ccmem-mcp

→ 04 / 04 HOOKS

Wire hooks (memory shows up at the top)

Step 3's MCP is "Claude pulls memories on demand." Hooks fire automatically at session boundaries — SessionStart brings memories into a new conversation, SessionEnd confirms this one got indexed. One command finds ~/.claude/settings.json, backs it up, and merges (not overwrites) two hook registrations.

CMD

ccmem install-hooks

⚠ IMPORTANT

Restart any running Claude Code sessions after install — hook config doesn't hot-reload. Preview without writing: ccmem install-hooks --dry-run. Remove later: ccmem uninstall-hooks (only deletes ccRecall's own entries).

→ 05 OPTIONAL makes memories grow

Let each session settle into memory

The first four steps give you indexing, startup injection, and manual recall_save. Up to here, a memory only exists if you deliberately save one. To make them accumulate, add one line to your shell config — after that, every session ends with Haiku reading the transcript and distilling up to 5 entries into the store, for about $0.001 a run.

CMD · add to ~/.zshrc or ~/.bashrc

source "$(npm root -g)/@tznthou/ccrecall/scripts/post-session-extract.sh"

Then use ccrecall-extract instead of claude — every claude flag still works:

ccrecall-extract # instead of: claude

ccrecall-extract --resume # flags work as usual

alias ccdm='ccrecall-extract' # if the name is too long

// requires jq and curl on PATH (both ship with macOS)

Skip distillation for one session: CCRECALL_SKIP_EXTRACT=1 ccrecall-extract. If the daemon isn't running the wrapper skips itself — it will never block you from starting a conversation.

// 4 STEPS → SYSTEM LIVE · +1 STEP → MEMORIES GROW ON THEIR OWN

SECT. 04 // HOW IT RUNS · 5 PARTS RELAY

Five parts / running the relay

You don't do anything else. With your machine awake and Claude Code in use, the first four parts keep every conversation indexed; the fifth (optional) is what turns those conversations into memories.

▶ 01 DAEMON

Background service

ccmem install-daemon registered it as a LaunchAgent. It sits idle waiting for HTTP requests. Mac is awake → daemon is alive.

PORT: 127.0.0.1:7749

▶ 02 WATCHER

File watcher

The daemon points chokidar at ~/.claude/projects/. Whenever Claude Code writes a new session JSONL, the watcher notices within seconds, indexes it, updates SQLite. No manual rescans.

LATENCY: ~seconds

▶ 03 BACKSTOP

10-minute backstop

Filesystem events occasionally drop (sleep/wake, external disks). Every 10 minutes the daemon does a full rescan as a safety net. Anything the watcher missed lands here.

INTERVAL: 600s

▶ 04 HOOKS

Lifecycle hooks

Step 4's hooks fire automatically at:

SessionStart: inject up to 5 memories before your first prompt
SessionEnd: confirm this session got indexed

▶ 05 DISTILL OPTIONAL · STEP 5

Distillation wrapper

The first four parts get every conversation into the index — but an index isn't a memory. This is the part that turns one into the other: after a session ends it spawns a Haiku run over the transcript and writes 0–5 entries back through MCP recall_save. Without it, memories only exist when you save them by hand.

COST: ~$0.001/session · SKIP: CCRECALL_SKIP_EXTRACT=1

In one line: four steps give you a system that looks things up; the fifth gives you one that grows.

SECT. 05 // VERIFY · IS IT ALIVE?

Verify / it's actually running

Three quick checkpoints. If something's off, this section helps you locate which link is broken.

CHECK #01

Daemon alive

curl http://127.0.0.1:7749/health

{"status":"ok"} means yes. 7749 is the default port; override via CCRECALL_PORT in the plist if needed.

CHECK #02

MCP connected

Start a fresh Claude Code session and ask:

"Have we talked about xxx before?"

Claude should proactively invoke mcp__ccrecall__recall_query to search past conversations. Seeing "looking up memories" in tool calls means the connection is live.

CHECK #03

First query empty?

On first boot, the daemon kicks off runIndexer to walk every historical JSONL and build the index. The watcher only arms after that pass completes. Empty results during this window aren't a bug — a dozen sessions take seconds; hundreds may take a minute or two.

tail -f ~/Library/Logs/ccrecall/ccrecall.out.log
# "Indexer complete." means you're good

SECT. 06 // TROUBLESHOOTING · TOP 3

Top three / snags people hit

These are the three that catch 90% of people.

Q #01

After install, ccmem says command not found?

Your npm global bin isn't on PATH. Find where it lives, then add the /bin directory to PATH.

npm config get prefix # find the location
export PATH="$(npm config get prefix)/bin:$PATH"

Q #02

Daemon won't start, log shows EADDRINUSE?

Port 7749 is taken by something else. Override CCRECALL_PORT and reinstall the plist:

export CCRECALL_PORT=17749
ccmem install-daemon # reinstall with new port

Q #03

Claude never calls recall_query?

First check claude mcp list shows ccrecall. If not, re-run Step 3. If it's there, Claude doesn't always decide to call it on its own — it depends on context. Naming the tool explicitly almost always works:

To look up: "use recall_query to search for xxx"
To save: "use recall_save to remember xxx"

SECT. 07 // NEXT · INTERNAL

Up and running / here's what's next

Now that it's installed, these pages cover what it does behind the scenes and how it splits work with the other tool.

CCRECALL · DETAIL

How it actually works

Component spec, trust contract, the full index → distill → inject → recall flow, and what actually lands on disk.

→ ccrecall detail page

SCHEMA · CONTRACT

20 tables, by ownership

Why the 6 baseline tables demand a cross-PR, how ownership splits the rest, why every migration step rolls back.

→ architecture page

CCFAMILY · OVERVIEW

Which one, when

ccRecall remembers forward, ccRewind digs backward — they don't solve the same problem.

→ ccfamily home

SUPPORT

Report bug / ask question

GitHub Issues for bug tracking, design discussion, feature requests.

→ github.com/tznthou/ccRecall/issues

SECT. 08 · NEXT

That's it / it runs itself now

Open your next Claude Code session. Before you type anything, the SessionStart hook has already injected relevant memories — just keep talking. If you wired up step 5, this conversation will settle back into the store when it ends.

[ ← OVERVIEW ] [ ⭐ STAR ON GITHUB ]

// INSTALLED · DAEMON UP · MCP CONNECTED · HOOKS WIRED · DISTILL OPTIONAL

Zero to memory, in 4 + 1 steps