@memoryfirst/claude-hooks

Claude Code hooks that close the loop between your coding sessions and your MemoryFirst brain: every session starts with context recalled from the brain, and everything that happens flows back into it — automatically, with zero prompting.

What it does

Hook	Claude Code event	Behavior
memoryfirst-session-start.sh	SessionStart	Fetches GET /v1/brain/context?project=<dir> and injects it as additional context, so Claude starts every session already knowing the project's recent decisions, blockers and state.
memoryfirst-ingest-transcript.sh	Stop + SessionEnd	Extracts the user/assistant text from the session transcript and posts it to POST /v1/sources/ingest. Throttled on Stop (default: one snapshot per 600 s per session) so long sessions get periodic captures; SessionEnd always flushes. Idempotent: the server dedupes by sha256(content) per expert, so re-sending the same transcript is a no-op.
memoryfirst-stop.sh	Stop	Lightweight "session checkpoint" brain event (default: at most one per 300 s).

The project is identified by the basename of the working directory ($CLAUDE_PROJECT_DIR); the per-project expert (project:<name>) is auto-provisioned on first ingest. Endpoint contracts: docs/CLAUDE_CODE_HOOKS.md.

Install (2 commands)

cd packages/claude-hooks
./install.sh --credentials     # prompts for API URL + key, stores them locally

Re-running install.sh upgrades the hooks in place — it is idempotent and never duplicates registrations. The installer merges into ~/.claude/settings.json surgically: hooks registered by other tools are left untouched, and a backup (settings.json.bak.memoryfirst-hooks) is written before every change.

Requirements: bash, jq, curl. Works on macOS and Linux.

Uninstall

./install.sh --uninstall

Removes the hook files and their settings.json entries (other hooks are preserved). Credentials and local logs are kept; the command prints the exact lines to purge them.

Credentials & privacy

• Where credentials live — macOS: Keychain items codelabs/memoryfirst/api_url and codelabs/memoryfirst/internal_api_key (account memoryfirst). Linux/other: ~/.config/memoryfirst/hooks.env (chmod 600). Environment variables MEMORYFIRST_API_URL / MEMORYFIRST_API_KEY work as a final fallback. Credentials are never written into the repo, the hooks, or any log.
• What is sent — only the conversational text of the transcript (your messages and Claude's text replies). Tool outputs, file contents read during the session, and thinking blocks are not extracted. Sessions under 400 characters of conversation are skipped; captures are capped at the last 200 000 characters.
• Failure mode — every hook is best-effort and silent: missing credentials, network failures or a down API produce no output, no error, and never block or break a Claude Code session.
• Local log — ingest results (event, project, session id, HTTP status, size — never content, never credentials) are appended to ~/.claude/hooks/memoryfirst-ingest.log.

Configuration (env vars, all optional)

Variable	Default	Purpose
MF_INGEST_THROTTLE_SECONDS	600	Min seconds between transcript snapshots on Stop (per session).
MF_STOP_THROTTLE_SECONDS	300	Min seconds between checkpoint events on Stop (per session).
MEMORYFIRST_CONTEXT_MAX_TOKENS	2500	Token budget requested from /v1/brain/context at session start.
MEMORYFIRST_API_URL / MEMORYFIRST_API_KEY	—	Credential fallback when no Keychain/env file entry exists.
MEMORYFIRST_HOOKS_ENV	~/.config/memoryfirst/hooks.env	Alternate credentials env file location.
MEMORYFIRST_KEYCHAIN_PREFIX / MEMORYFIRST_KEYCHAIN_ACCOUNT	codelabs/memoryfirst / memoryfirst	Keychain item naming.
MEMORYFIRST_HOOKS_LOG	~/.claude/hooks/memoryfirst-ingest.log	Ingest log location.