airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5a18f08e5f51c272fba59440a97ff145c5e77cec
claude-mem/CLAUDE.md
T
JOUNGWOOK KWON 5a18f08e5f chore: merge upstream v12.4.7 + keep local fixes 
Major upstream changes (v12.3.9 → v12.4.7):

v12.3.9 — Stop hook fire-and-forget (eliminates ~110s terminal block);
  hook port precedence; Telegram notifier; security_alert/security_note
  observation types

v12.4.0/12.4.1 — worker startup streamlined; consolidated DB connections;
  Chroma backfill watermark cache (422% CPU → 0% on restart)

v12.4.2 — context-overflow infinite loop fixed (clears memorySessionId
  on "Prompt is too long"); <task-notification> payload pollution blocked
  at hook + worker boundary

v12.4.3 — one-time pollution cleanup migration (CleanupV12_4_3):
  purges observer-sessions rows + cascade, stuck pending chains, Chroma
  rebuild; auto VACUUM INTO backup. Ran successfully on this DB:
  - 1463 observer-sessions purged
  - 3682 cascade rows
  - 102MB backup at ~/.claude-mem/backups/

v12.4.4 — stop draining queue on /clear (removes SessionEnd shim that
  had been abandoning pending observations for 6 months)

v12.4.5 — fix observation persistence on fresh installs (migration 28
  mirror in SessionStore)

v12.4.7 — cynical-deletion sweep (closes 27 issues); multi-account
  isolation via per-UID worker port (37700 + uid % 100, with explicit
  CLAUDE_MEM_WORKER_PORT override); CLAUDE_MEM_INTERNAL=1 trust boundary
  replaces cwd-based observer-session detection; observations.metadata
  column (migration 30); proxy env vars stripped from spawned subprocs

Local fixes preserved:
- env-sanitizer PATH extension for claude CLI lookup (auto-merged
  cleanly with upstream's new ENV_PROXY_VARS proxy stripping)
- SessionStore stale session reset (mac sleep / 4h wall-clock)

Settings: CLAUDE_MEM_WORKER_PORT=37777 explicit override preserved
through the per-UID port migration. Worker restarted to v12.4.7.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-26 18:13:22 +09:00

6.5 KiB
Raw Blame History

내 저장소 설정

업데이트

Claude-Mem: AI Development Instructions

Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

Architecture

5 Lifecycle Hooks: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd

Hooks (src/hooks/*.ts) - TypeScript → ESM, built to plugin/scripts/*-hook.js

Worker Service (src/services/worker-service.ts) - Express API on port 37777, Bun-managed, handles AI processing asynchronously

Database (src/services/sqlite/) - SQLite3 at ~/.claude-mem/claude-mem.db

Search Skill (plugin/skills/mem-search/SKILL.md) - HTTP API for searching past work, auto-invoked when users ask about history

Planning Skill (plugin/skills/make-plan/SKILL.md) - Orchestrator instructions for creating phased implementation plans with documentation discovery

Execution Skill (plugin/skills/do/SKILL.md) - Orchestrator instructions for executing phased plans using subagents

Chroma (src/services/sync/ChromaSync.ts) - Vector embeddings for semantic search

Viewer UI (src/ui/viewer/) - React interface at http://localhost:37777, built to plugin/ui/viewer.html

Privacy Tags

  • <private>content</private> - User-level privacy control (manual, prevents storage)

Implementation: Tag stripping happens at hook layer (edge processing) before data reaches worker/database. See src/utils/tag-stripping.ts for shared utilities.

Build Commands

npm run build-and-sync        # Build, sync to marketplace, restart worker

Configuration

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

Multi-account

Claude-mem supports running multiple isolated profiles on the same machine (e.g. work vs personal accounts) via environment variables. No CLI subcommand needed — set the env vars in the shell where you run Claude Code.

  • Switch profiles per shell: Set CLAUDE_MEM_DATA_DIR=<path> and every claude-mem path (database, chroma, logs, settings.json, worker.pid, transcripts config) derives from it. Example:

    export CLAUDE_MEM_DATA_DIR="$HOME/.claude-mem-work"

  • Port collisions are auto-handled: The default worker port is 37700 + (uid % 100), so two different OS users on the same box get different ports for free. If you want fixed ports per profile (e.g. you run two profiles as the same UID), set CLAUDE_MEM_WORKER_PORT too:

    export CLAUDE_MEM_WORKER_PORT=37800

  • All paths and ports derive from these two env vars. Hooks, npx-cli (install/uninstall/start/search), the OpenCode plugin, the OpenClaw installer, and the timeline-report skill all honor them. The settings file itself lives at $CLAUDE_MEM_DATA_DIR/settings.json.

  • Closes #2101. See src/shared/SettingsDefaultsManager.ts for the canonical port/data-dir defaults and plugin/skills/timeline-report/SKILL.md for the shell snippet that resolves the port for arbitrary skills.

File Locations

  • Source: <project-root>/src/
  • Built Plugin: <project-root>/plugin/
  • Installed Plugin: ~/.claude/plugins/marketplaces/thedotmack/
  • Database: ~/.claude-mem/claude-mem.db
  • Chroma: ~/.claude-mem/chroma/

Exit Code Strategy

Claude-mem hooks use specific exit codes per Claude Code's hook contract:

  • Exit 0: Success or graceful shutdown (Windows Terminal closes tabs)
  • Exit 1: Non-blocking error (stderr shown to user, continues)
  • Exit 2: Blocking error (stderr fed to Claude for processing)

Philosophy: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.

See private/context/claude-code/exit-codes.md for full hook behavior matrix.

Requirements

  • Bun (all platforms - auto-installed if missing)
  • uv (all platforms - auto-installed if missing, provides Python for Chroma)
  • Node.js

Documentation

Public Docs: https://docs.claude-mem.ai (Mintlify) Source: docs/public/ - MDX files, edit docs.json for navigation Deploy: Auto-deploys from GitHub on push to main

Pro Features Architecture

Claude-mem is designed with a clean separation between open-source core functionality and optional Pro features.

Open-Source Core (this repository):

  • All worker API endpoints on localhost:37777 remain fully open and accessible
  • Pro features are headless - no proprietary UI elements in this codebase
  • Pro integration points are minimal: settings for license keys, tunnel provisioning logic
  • The architecture ensures Pro features extend rather than replace core functionality

Pro Features (coming soon, external):

  • Enhanced UI (Memory Stream) connects to the same localhost:37777 endpoints as the open viewer
  • Additional features like advanced filtering, timeline scrubbing, and search tools
  • Access gated by license validation, not by modifying core endpoints
  • Users without Pro licenses continue using the full open-source viewer UI without limitation

This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.

Important

No need to edit the changelog ever, it's generated automatically.

Daily Maintenance

Run a daily version check across all package manifests and upgrade every dependency to its latest version — including major version bumps. Staying on the latest is the goal; do not skip majors.

  • Check package.json (root) and all nested package.json files (e.g. plugin/, openclaw/) for outdated dependencies via npm outdated.
  • Upgrade every package to latest (use npm install <pkg>@latest for each, or npx npm-check-updates -u && npm install). Bump majors too.
  • Run npm audit fix to resolve advisories.
  • After upgrades, run npm run build-and-sync and verify the worker starts and tests pass. Fix any breakage caused by major bumps in the same change.
  • Commit the updated package.json and package-lock.json files.
Reference in New Issue View Git Blame Copy Permalink