Personal Memory

Personal Memory

This skill manages memory in two contexts:

• User level: rooted at ~/.codex
• Project level: rooted at the project directory

For any selected root, the skill manages:

• AGENTS.md
• personal-memory/
• automation/

Script Directory

Important: All scripts are located in the scripts/ subdirectory of this skill.

Agent Execution Instructions:

1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Script path = ${SKILL_DIR}/scripts/<script-name>.py
3. Replace all ${SKILL_DIR} in this document with the actual path

Files

• README.md: 当前 memory 目录的最小说明和入口命令
• profile.md: explicitly confirmed user preferences
• summary.md: promoted memory digest for fast lookup
• observations.jsonl: raw captured observations
• facts.jsonl: promoted facts and stable preferences
• patterns.jsonl: promoted workflow patterns
• anti_patterns.jsonl: promoted repeated failures and things to avoid

Rules

• User level: store only cross-project, user-level information.
• Project level: store only information that is valid inside that project.
• Never store secrets, tokens, credentials, or sensitive private data.
• Do not promote single incidents into long-term memory.
• Project-specific facts may be captured only as scope=project, but they must not be promoted into user-level memory.

Commands

Check initialization status:

python3 ${SKILL_DIR}/scripts/memory_cli.py status --level user
python3 ${SKILL_DIR}/scripts/memory_cli.py status --level project --root /path/to/project

Initialize AGENTS, personal-memory, and automation:

python3 ${SKILL_DIR}/scripts/memory_cli.py init --level user
python3 ${SKILL_DIR}/scripts/memory_cli.py init --level project --root /path/to/project

Show summary:

python3 ${SKILL_DIR}/scripts/memory_cli.py show

Search memory:

python3 ${SKILL_DIR}/scripts/memory_cli.py show 中文

List long-term memory records:

python3 ${SKILL_DIR}/scripts/memory_cli.py list
python3 ${SKILL_DIR}/scripts/memory_cli.py list --level project --root /path/to/project

Review recent Codex history and generate safe candidates:

python3 ${SKILL_DIR}/scripts/memory_cli.py review-history

Apply safe candidates into observations:

python3 ${SKILL_DIR}/scripts/memory_cli.py review-history --apply

If the user explicitly asks to remember something, write it directly as long-term memory:

python3 ${SKILL_DIR}/scripts/memory_cli.py remember \
  --kind preference \
  --scope user \
  --summary "用户要求先给结论，再展开细节" \
  --details "这是明确的跨项目沟通偏好"

Capture a preference, fact, pattern, or failure:

python3 ${SKILL_DIR}/scripts/memory_cli.py capture \
  --kind preference \
  --scope user \
  --summary "用户要求始终使用简体中文回复" \
  --details "这是明确声明的全局偏好" \
  --source conversation \
  --tag language

Promote repeated observations and rebuild summary:

python3 ${SKILL_DIR}/scripts/memory_cli.py evolve

Delete one memory:

python3 ${SKILL_DIR}/scripts/memory_cli.py forget --query 简体中文

Clear all stored memories:

python3 ${SKILL_DIR}/scripts/memory_cli.py clear --yes

Compatibility Notes

• Project-level memory should prefer the project-local skill copy, so generated commands and docs should point to the current skill directory instead of hard-coding ~/.codex.
• User-level memory is agent-specific by nature. Different agents may keep their own user-level roots, summaries, and automation layouts.
• Therefore the stable boundary should be:
  • user level = agent-owned runtime state
  • project level = repo-owned shared convention
• The user-level root may be overridden with PERSONAL_MEMORY_HOME or CODEX_HOME. If neither is set, the default root is ~/.codex.
• If an agent wants to reuse this skill outside Codex, it should vendor the skill into the project or map SKILL_DIR to its own installed location, rather than assuming ~/.codex/skills/... exists.

Recommended Workflow

1. First run status to determine whether the selected context is initialized.
2. If not initialized, run init.
3. Before substantial work, read summary.md and profile.md if relevant.
4. When you observe durable information, capture it.
5. When the user explicitly says to remember something, use remember directly.
6. Optionally run review-history to mine conservative candidates from recent Codex history.
7. After meaningful additions, run evolve to refresh promoted memory.
8. Use promoted memory as guidance, not as unquestionable truth; prefer recent, higher-evidence records.