Skip to content
Back to search

ai-memory-skillpack

Bounded project-memory skills for Codex CLI and Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tudoumashu--ai-memory-skillpack/badge.svg)](/listings/tudoumashu--ai-memory-skillpack)

HTML

<a href="/listings/tudoumashu--ai-memory-skillpack"><img src="/api/listings/tudoumashu--ai-memory-skillpack/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/tudoumashu/ai-memory-skillpack.git
cd ai-memory-skillpack
sha256sum -c SHA256SUMS

**Requirements:** Linux or WSL, bash ≥ 4.4, `git`, `rg`, `sha256sum`. Python ≥ 3.10 only for `project-mastery-coach`. macOS needs GNU `sha256sum` / `flock` / `readlink -f` and a newer bash, or the installer stops.

Then tell Codex:

> Read `INSTALL.md` in this pack and follow it to install the memory system on this machine.

| Case | Contract | | --- | --- | | **Fresh** | Never overwrite existing files; only merge and add | | **Upgrade** | Receipt hashes decide what the pack may replace; your edits stay | | **Migrate** | Archive the old pack first; content is not destroyed |

Adapter table, receipt schema, rollback: [`INSTALL.md`](INSTALL.md). Acceptance: [`VERIFY.md`](VERIFY.md).

No Obsidian vault? The installer skips `llm-wiki` and `project-mastery-coach` and installs **only** `ai-project-memory`. Wiki lint/query scripts are not in this repo.

Shipped skills contain **example** absolute paths and actor strings. Those are adapter source values, not a requirement to use those directories or models.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 197 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AI Memory Skillpack
  2. **The memory plane for Codex.**
  3. A bounded, fail-closed project-memory system for [Codex CLI](https://github.com/openai/codex). Optional [Claude Code](https://code.claude.com/docs/en/overview) support on the same skill source.
  4. [English](README.md) · [中文](README.zh.md)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![Version](https://img.shields.io/badge/version-v1.25.1-blue.svg)](https://github.com/tudoumashu/ai-memory-skillpack/tags)
  7. [![Harness](https://img.shields.io/badge/Codex-first-412991.svg)](https://github.com/openai/codex)
  8. [![Install](https://img.shields.io/badge/install-agent--executable-0f766e.svg)](INSTALL.md)
  9. > An agent should remember a project the way a careful engineer does: a short brief, a map, a list of traps — not a diary that never ends.
  10. Codex already writes code, reviews diffs, and triages failures. What it still lacks, out of the box, is a **durable, size-capped, attributed memory of the repo** that the next session can trust. This pack is that layer: skills, a constitution, an installer Codex can run unaided, and a verifier that fails closed.
  11. Clone, then tell Codex:
  12. > Read `INSTALL.md` in this pack and follow it to install the memory system on this machine.
  13. No GUI. The installer is a program for the agent. Installs are reversible. No wiki? Only the project-memory skill is enabled.
  14. ## Why this belongs in the Codex ecosystem
  15. Codex is strongest when the repo already knows how it wants to be maintained. This pack is that contract, written so an agent can **install, obey, and prove** it.
  16. | Codex maintainer job | What this pack makes mechanical |
  17. | --- | --- |
  18. | Review a PR without rereading the whole tree | HOT snapshot + WARM `rg`, not a dump of `docs/ai/` |
  19. | Keep releases and runbooks true | Bounded `docs/ai/` with replace-guards, not append-only notes |
  20. | Survive a second session on the same repo | Handoff is one page, replaced in place; git is the ledger |
  21. | Not leak secrets into “memory” | Constitution + sanitizer gate; writers are forbidden to store secret values |
  22. | Upgrade the memory system later | Receipt hashes; your edits are kept; old packs are archived, not destroyed |
  23. It is first-class Codex infrastructure: `AGENTS.md` sections, Codex skills, an agent-executable `INSTALL.md`, and `VERIFY.md` as acceptance — the same shape as a serious maintainer toolchain, not a prompt pack you paste once and forget.
  24. ## The failure it removes
  25. Agents either forget the project between sessions, or they “remember” by appending to handoff notes and changelogs. Those files have no ceiling. The next session burns tens — sometimes hundreds — of thousands of tokens on yesterday’s residue before any real work starts.
  26. That is not memory. It is context pollution with a git history.
  27. | Naive agent notes | This system |
  28. | --- | --- |
  29. | Append-only handoff, unbounded | One-page snapshot, replaced in place |
  30. | Parallel changelog files | Git commits are the ledger |
  31. | Dump `docs/ai/` into context | HOT / WARM / COLD — most files are not read |
  32. | Silent overwrite on upgrade | Receipt-based hash compare; your edits stay |
  33. | “It installed, probably” | `VERIFY.md`: exit-code assertions, not vibes |
  34. ## What you get
  35. - **A constitution, not a vibe.** [`SYSTEM.md`](SYSTEM.md) is the spec: tiers, byte budgets, attribution, replace-guards, “do not write secrets.” Skills do not outrank it.
  36. - **An agent-native installer.** [`INSTALL.md`](INSTALL.md) is for Codex to execute: adapt paths, merge global rules, enable repos, write a machine receipt, roll back.
  37. - **A verifier, not a checklist.** [`VERIFY.md`](VERIFY.md) is assertions with real exit codes. Pack bytes are pinned by [`SHA256SUMS`](SHA256SUMS).
  38. - **One skill source, two harnesses.** Codex holds the files; a second harness gets symlinks. No forked copies.
  39. - **Fail-closed upgrades.** Fresh / upgrade / migrate are different contracts. Older packs are sealed first.
  40. - **Secret-hygiene as a boundary.** The optional coach path sanitizes learning records before they can reach a central wiki. The regression suite exists because this was treated as a security gate.
  41. ## Architecture
  42. Four layers. Each has one job.
  43. ```mermaid
  44. flowchart TB
  45. subgraph pack [This pack]
  46. I[INSTALL.md]
  47. S[SYSTEM.md]
  48. V[VERIFY.md]
  49. SK[skills/]
  50. end
  51. subgraph machine [Target machine]
  52. H1[Primary harness skills]
  53. H2[Secondary harness symlinks]
  54. G[Harness global rules]
  55. T[Machine facts]
  56. end
  57. subgraph repos [Each repository]
  58. D[docs/ai bounded pack]
  59. end
  60. I --> H1
  61. H1 --> H2
  62. I --> G
  63. I --> T
  64. I --> D
  65. S -.-> SK
  66. V -.-> H1
  67. V -.-> D
  68. ```
  69. | Layer | What | Sharing rule |
  70. | --- | --- | --- |
  71. | Procedures | `ai-project-memory`, `llm-wiki`, `project-mastery-coach` | Real files on the primary harness; symlinks on the second |
  72. | Machine facts | Local tooling baseline | One file; both harnesses point at it |
  73. | Per-harness rules | Codex `AGENTS.md` / Claude `CLAUDE.md` memory sections | Separate on purpose — harness defaults are not identical |
  74. | Repo packs | Per-repo `docs/ai/` | Independent; templates in `repo-templates/` |
  75. ### Read policy
  76. | Tier | When it is read | Examples |
  77. | --- | --- | --- |
  78. | **HOT** | Whole-file, every session | `project-card.md`, `handoff.md` |
  79. | **WARM** | `rg` to a section, never whole-file by default | architecture, runbook, gotchas, current ADRs |
  80. | **COLD** | Only when the user explicitly traces history | `history/`, reports, screenshots, superseded ADRs |
  81. Handoff is a **single snapshot** under a replace-guard (`flock` on an absolute lock path). It is not a log.
  82. ## Security and quality bar
  83. This is the part a maintainer cannot fake with a prettier README.
  84. - **Secrets never enter memory files.** The constitution forbids it. Shape-based sanitizers are a backstop, not the policy.
  85. - **Upgrades cannot silently clobber your edits.** The install receipt is a hash table. Mismatches are reported and kept.
  86. - **Acceptance is executable.** `VERIFY.md` fails closed. `tests/` exists so closed review findings cannot regress.
  87. - **Integrity is pinned.** `sha256sum -c SHA256SUMS` is the first install gate.
  88. - **Attribution is mandatory.** Every memory write carries a stable `harness/model` actor. History is not rewritten to flatter the present.
  89. ## Design tenets
  90. Enforced in spec and in the verifier:
  91. 1. **Governance must cost less than the mess it prevents.** No mechanism without a reproduced failure.
  92. 2. **Closed failures become assertions.** A finding that is not executable will come back.
  93. 3. **Archive, do not destroy.** Over-budget files go to `history/`. Migrations seal first.
  94. 4. **Writers do not store secret values.** Sanitizers are the second line.
  95. ## Install
  96. ```bash
  97. git clone https://github.com/tudoumashu/ai-memory-skillpack.git
  98. cd ai-memory-skillpack
  99. sha256sum -c SHA256SUMS
  100. ```
  101. **Requirements:** Linux or WSL, bash ≥ 4.4, `git`, `rg`, `sha256sum`. Python ≥ 3.10 only for `project-mastery-coach`. macOS needs GNU `sha256sum` / `flock` / `readlink -f` and a newer bash, or the installer stops.
  102. Then tell Codex:
  103. > Read `INSTALL.md` in this pack and follow it to install the memory system on this machine.
  104. | Case | Contract |
  105. | --- | --- |
  106. | **Fresh** | Never overwrite existing files; only merge and add |
  107. | **Upgrade** | Receipt hashes decide what the pack may replace; your edits stay |
  108. | **Migrate** | Archive the old pack first; content is not destroyed |
  109. Adapter table, receipt schema, rollback: [`INSTALL.md`](INSTALL.md). Acceptance: [`VERIFY.md`](VERIFY.md).
  110. No Obsidian vault? The installer skips `llm-wiki` and `project-mastery-coach` and installs **only** `ai-project-memory`. Wiki lint/query scripts are not in this repo.
  111. Shipped skills contain **example** absolute paths and actor strings. Those are adapter source values, not a requirement to use those directories or models.
  112. ## Skills
  113. | Skill | Role | When it installs |
  114. | --- | --- | --- |
  115. | **`ai-project-memory`** | Bounded `docs/ai/` in each repo: card, handoff, architecture, runbook, gotchas, ADRs | Always |
  116. | **`llm-wiki`** | Query and write-back a local central wiki | Only with a wiki root that matches the contract |
  117. | **`project-mastery-coach`** | Optional ownership training: question bank, spaced repetition, dashboards | Wiki + Python ≥ 3.10 |
  118. If a skill text conflicts with [`SYSTEM.md`](SYSTEM.md), the constitution plus the machine’s adapter values win.
  119. ## Active maintenance
  120. What you can verify in this repository without trusting a pitch:
  121. - Tagged releases through **v1.25.1**; pack identity **v1.25**
  122. - Agent-executable installer, constitution, and post-install verifier checked in as first-class files
  123. - Coach-script regression suite under [`tests/`](tests/)
  124. - MIT license, public source, no telemetry in the pack
  125. ```bash
  126. sha256sum -c SHA256SUMS
  127. bash tests/run.sh python3 skills/project-mastery-coach/scripts/project_mastery_state.py
  128. ```
  129. Change a listed file → regenerate `SHA256SUMS`, or the installer integrity gate fails.
  130. ## Repository
  131. | Path | Role |
  132. | --- | --- |
  133. | [`INSTALL.md`](INSTALL.md) | Agent-executable installer |
  134. | [`SYSTEM.md`](SYSTEM.md) | Constitution |
  135. | [`VERIFY.md`](VERIFY.md) | Post-install assertions |
  136. | [`skills/`](skills/) | Skill sources |
  137. | [`global/`](global/) | Harness global memory sections |
  138. | [`repo-templates/`](repo-templates/) | Per-repo AGENTS section, Claude shim, ignore files |
  139. | [`migration/`](migration/) | Procedure for machines that already have an older pack |
  140. | [`tests/`](tests/) | Coach-script regression suite |
  141. | [`SHA256SUMS`](SHA256SUMS) | Pack integrity |
  142. | [`LICENSE`](LICENSE) | MIT |
  143. ## License
  144. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.