# Personal Memory

> Generic memory and self-improvement skill for user-level or project-level contexts. Use when the user wants Codex to remember stable preferences, workflow patterns, repeated failures, or durable context; when checking whether memory/automation/AGENTS are initialized; when initializing memory infrastructure in ~/.codex or a project root; or when listing, deleting, clearing, or promoting memory records.

- Skill: `daqi/personal-memory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add daqi/personal-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/daqi/personal-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: daqi (https://skillmd.com/u/daqi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/daqi/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:

```bash
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:

```bash
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:

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

Search memory:

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

List long-term memory records:

```bash
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:

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

Apply safe candidates into observations:

```bash
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:

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

Capture a preference, fact, pattern, or failure:

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

Promote repeated observations and rebuild summary:

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

Delete one memory:

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

Clear all stored memories:

```bash
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.