# Agent Memory Ledger

> Archive or recall durable facts, procedures, decisions, and events across Codex CLI sessions using a standalone evidence/object/bright-dark-ledger workspace rather than Codex memories.

- Skill: `yufanyang214-lab/agent-memory-ledger` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yufanyang214-lab/agent-memory-ledger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yufanyang214-lab/agent-memory-ledger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: yufanyang214-lab (https://skillmd.com/u/yufanyang214-lab)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yufanyang214-lab/agent-memory-ledger

---


# Agent Memory Ledger for Codex CLI

Use this skill when the user asks Codex to remember, archive, or recall durable
information across separate Codex sessions.

## Boundary

The standalone ledger is the canonical memory write target. Do not enable or
call Codex experimental memories, and do not copy memory bodies into `AGENTS.md`
or other startup instructions. An external memory provider may receive only
sanitized evidence or derived objects after successful AML archival when the
operator explicitly configured external-memory mode. The adapter reads only
visible user and assistant events from the current rollout. It excludes
developer instructions, hidden reasoning, tool calls, command output, plugin
recommendations, and model metadata.

Resolve `SKILL_DIR` as the absolute directory containing this loaded
`SKILL.md`. Codex exposes the skill location in its skill metadata; do not
assume that the skill came from `.agents/skills`, because a plugin installation
uses the Codex plugin cache.

Install the core package and stable repository-local bridge once:

```bash
python "$SKILL_DIR/scripts/install.py" \
  --workspace "$PWD" \
  --source /path/to/agent_memory_ledger-0.1.1-py3-none-any.whl
```

Use these paths from the repository root:

```bash
PY="$PWD/.agent-memory-ledger-venv/bin/python"
BRIDGE="$PWD/.agent-memory-ledger-adapter/codex_bridge.py"
LEDGER="$PWD/.portable-memory"
```

## Archive the current Codex session

`CODEX_THREAD_ID` is provided to shell commands by Codex CLI, so the bridge can
locate the current rollout without asking the user for a session path.

Archive only when the user affirmatively asks to archive the current session
with the configured trigger or an equivalent such as "archive", "archive this
session", “归档本会话”, or “按 AML 归档”. Questions, explanations, quotations,
hypotheticals, and negations about archiving do not trigger the workflow.
Before running the bridge, extract durable `knowledge`, `procedure`, and
`event` candidates into a JSON file as described in
`docs/AGENT_INSTRUCTIONS.md`. Use tags for finer subtypes and canonical kind
names only. Set `promote: true` only for the small set of stable, high-value
items that should be discoverable at startup.

```bash
"$PY" "$BRIDGE" archive \
  --ledger "$LEDGER" \
  --candidate-file /path/to/memory-candidates.json
```

Every accepted active candidate is represented in the dark ledger. The bridge
uses candidate `promote` values to build the bright ledger. Add
`--promote-markers` only when the user explicitly supplied stable lines such as
`Fact:`, `Rule:`, `Procedure:`, `Decision:`, `事实：`, `规则：`, or `流程：`.
Never edit evidence, objects, ledgers, SQLite, or the journal directly. Run
validation after archival and report the archive, object, and promoted IDs.

## Recall

```bash
"$PY" "$BRIDGE" recall \
  --ledger "$LEDGER" \
  --query "<user question>" \
  --top-k 6
```

Answer only from returned active objects and include relevant `object_id` values.
Do not silently fall back to session history, Codex memories, or startup files.
An explicitly configured external provider may be used for deeper recall, but
its result must retain or resolve to AML archive/object provenance.

## Validate

```bash
"$PY" "$BRIDGE" validate --ledger "$LEDGER"
```

Completion requires `ok: true`, evidence, structured objects, both ledgers, and
successful recall from a fresh Codex thread.