JOUNGWOOK KWON
5a18f08e5f
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>
140 lines
6.5 KiB
Markdown
140 lines
6.5 KiB
Markdown
# 내 저장소 설정
|
|
|
|
- Git 서버: Gitea (자체 NAS 운영)
|
|
- Gitea URL: https://gitea.gru.farm/
|
|
- 계정: airkjw
|
|
- 저장소: claude-mem
|
|
- Remote: https://gitea.gru.farm/airkjw/claude-mem
|
|
- 토큰: 83b491bd64ffbf32c88e6e93abe5482422dc1488
|
|
|
|
## 업데이트
|
|
- claude.md 파일 로드시, 원본 레포 체크해서 업데이트 확인
|
|
- 원본 레포: https://github.com/thedotmack/claude-mem
|
|
|
|
---
|
|
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|