claude-mem/AGENTS.md

내 저장소 설정

• Git 서버: Gitea (자체 NAS 운영)
• Gitea URL: https://gitea.gru.farm/
• 계정: airkjw
• 저장소: Codex-mem
• Remote: https://gitea.gru.farm/airkjw/Codex-mem
• 토큰: 83b491bd64ffbf32c88e6e93abe5482422dc1488

업데이트

• AGENTS.md 파일 로드시, 원본 레포 체크해서 업데이트 확인
• 원본 레포: https://github.com/thedotmack/Codex-mem

---

Codex-Mem: AI Development Instructions

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

Architecture

6 Lifecycle Hooks: Setup → SessionStart → UserPromptSubmit → PreToolUse (Read) → PostToolUse → Stop

Hooks - Entries in plugin/hooks/hooks.json dispatch to the unified worker (plugin/scripts/worker-service.cjs, built from src/services/worker-service.ts via scripts/build-hooks.js) through bun-runner.js, invoking subcommands like context, session-init, observation, file-context, and summarize. The Setup-phase version-check.js is the only standalone hook script.

Worker Service (src/services/worker-service.ts) - Express API on the per-user worker port (default 37700 + (uid % 100), configurable via CLAUDE_MEM_WORKER_PORT), Bun-managed, handles AI processing asynchronously

Database (src/services/sqlite/) - SQLite3 at ~/.Codex-mem/Codex-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 served by the worker on its configured port (default http://127.0.0.1:<worker-port>), 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 ~/.Codex-mem/settings.json. The file is auto-created with defaults on first run.

Multi-account

Codex-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 Codex.

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

  export CLAUDE_MEM_DATA_DIR="$HOME/.Codex-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.

• 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: ~/.Codex/plugins/marketplaces/thedotmack/
• Database: ~/.Codex-mem/Codex-mem.db
• Chroma: ~/.Codex-mem/chroma/

Exit Code Strategy

Codex-mem hooks use specific exit codes per Codex'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 Codex 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.

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.Codex-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

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

Open-Source Core (this repository):

• All local worker HTTP API endpoints (per-user port — see Architecture above) 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 local worker 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.