Agent skill

AI Project Memory

by tudoumashu in tudoumashu/ai-memory-skillpack

Maintain bounded, durable AI project memory in a repository's docs/ai/ pack.

MITAuto-check passedAgent Workflows

Install AI Project Memory

skills CLI
$ npx skills add tudoumashu/ai-memory-skillpack --skill ai-project-memory -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install tudoumashu/ai-memory-skillpack ai-project-memory --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/tudoumashu/ai-memory-skillpack.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/ai-project-memory .claude/skills/ai-project-memory && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ai-project-memory
GitHub stars
443
Token cost
~1.1k tokens
SKILL.md length
264 words
Files
2
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Maintain bounded, durable AI project memory in a repository's docs/ai/ pack.

  • Works in 7 steps: 谁干活谁写:Codex 与 Claude Code… → 强制署名,actor… → 状态用替换:handoff.md 永远是单快照… → …
  • Claude Code needs to create
  • SKILL.md covers Core Rule, 读取纪律(检索先行), 写入纪律 and 何时更新什么, plus 3 more sections
  • Calls rg and git

What it does

AI Project Memory is an agent skill from tudoumashu/ai-memory-skillpack. Maintain bounded, durable AI project memory in a repository's docs/ai/ pack. Use when Codex or Claude Code needs to create, read, update, or audit project memory (project-card, architecture, diagrams, runbook, handoff, gotchas, ADRs), install AGENTS.md memory rules, or sync a lightweight central LLM Wiki project entity for user-owned projects.

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `agents/openai.yaml`).

It sits in Agent Workflows, covering Agent memory, Architecture decision records and LLM wikis. It works with Git. The repository describes itself as: Bounded project-memory skills for Codex CLI and Claude Code. The licence is MIT.

When your agent uses it

  • Claude Code needs to create
  • Audit project memory (project-card
  • Install AGENTS.md memory rules
  • Sync a lightweight central LLM Wiki project entity for user-owned projects

Example prompts

  • “/ai-project-memory”

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. 谁干活谁写:Codex 与 Claude Code 均可写,完成实质任务的一方负责更新。
  2. 强制署名,actor 只有两个拼法:claude-code/fable-5、codex/gpt-5.6-sol-pro。
  3. 状态用替换:handoff.md 永远是单快照 replace-in-place,不追加历史;追加语义仅限 gotchas 条目与新 ADR。
  4. 替换守卫(一体动作):写 handoff 前立即重读其头部(grep -m1 '^- updated: ',无匹配即中止写入,不得盲写),基线 = 最后一次实际读取的 updated 与内容;文件比基线新则先合并再写;临时文件必须建在 docs/ai/ 同目录(如…
  5. 预算写入时执行:超出上限当场裁剪,不留给下次会话。
  6. git 即账本:实质任务完成即提交,提交正文写 目标 / 验证 / 风险;禁止积压跨任务未提交改动;不把完整 diff 粘进文档。非 git 仓库(降级安装,收据 git=no):提交类条款不适用,改动以文件落盘为准并在最终回复明示「非 git 降级」;不得擅自 git…
  7. 未提交内容不进 canonical 文档:只可写入 handoff 并标 WIP/unverified。非 git 仓库:本条以「未验证」代读「未提交」——未验证内容同样只可写入 handoff 并标 WIP/unverified。

What it can do on your machine

Read from SKILL.md and the folder at commit f85cdec. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • rg
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

AI Project Memory loads about 1.1k tokens when it runs. Until then it costs about 91 tokens; SKILL.md has 264 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~91
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from tudoumashu/ai-memory-skillpack at commit f85cdec, republished under its MIT licence (© tudoumashu). 264 words, ~1,097 tokens.

Download SKILL.mdSave it as .claude/skills/ai-project-memory/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
ai-project-memory
description
Maintain bounded, durable AI project memory in a repository's docs/ai/ pack. Use when Codex or Claude Code needs to create, read, update, or audit project memory (project-card, architecture, diagrams, runbook, handoff, gotchas, ADRs), install AGENTS.md memory rules, or sync a lightweight central LLM Wiki project entity for user-owned projects.

AI Project Memory

Core Rule

每个仓库的 docs/ai/ 是该项目记忆的唯一事实源;git 提交是唯一账本(change-log 类文件已于 2026-07-28 停用,历史封存于 docs/ai/history/,不得重建)。

text
docs/ai/
├── project-card.md      # 卡片:≤60 行,替换
├── architecture.md      # 架构入口:≤250 行,替换/局部更新
├── diagrams/            # README ≤60 行 + *.mmd(一图一文件)
├── runbook.md           # 操作手册:≤150 行,替换/局部更新
├── handoff.md           # 单快照:≤120 行,替换
├── gotchas.md           # 耐久陷阱:≤300 行,追加 + 定期精选
├── decisions/ADR-*.md   # 单篇 ≤80 行,新篇追加,旧篇冷存
└── history/             # 封存区,默认不读

记忆散文默认中文;命令、路径、代码标识符、config key、版本号保持英文。不写 secret 值。预算上限见上方结构图;仓库 AGENTS.md 只可声明更严(更小)的上限,不得放宽——VERIFY 硬门按固定常量执行,不识别放宽。

读取纪律(检索先行)

  • HOT(开机整读,口径 = 字节÷3):仓库 AGENTS.md、CLAUDE.md、project-card.md、handoff.md——四文件自身目标 ≤7k tokens;四文件 + 当前触发的 skill 正文合计 ≤10k。
  • WARM(按需定向,禁止整读):architecture.md、runbook.md、gotchas.md、diagrams/README.md、decisions/(现行 ADR)——用任务关键词(路径、symbol、config key、报错信息)rg 定位小节后只读该节。
  • COLD(默认不读):history/、reports/、screenshots/、learning/、旧 ADR(Status: superseded/deprecated)。仅任务明确要求追溯时才进,读到的内容必须与当前代码交叉核对后才能引用。
  • 非分层新条目:向 docs/ai/ 一级新增任何文件/目录,必须同时在仓库 AGENTS.md 声明其层级;未声明即 COLD 且属违规(VERIFY 白名单断言会拦)。

写入纪律

  1. 谁干活谁写:Codex 与 Claude Code 均可写,完成实质任务的一方负责更新。
  2. 强制署名,actor 只有两个拼法:claude-code/fable-5、codex/gpt-5.6-sol-pro。
    • handoff.md 头部两行,固定列表项形式:- updated: <ISO8601>、- updated_by: <actor>(守卫与工具用 grep -m1 '^- updated: ' 读取基线)
    • 追加条目(gotchas / ADR)末行:— by <actor> · YYYY-MM-DD
    • git 提交:Co-Authored-By trailer 对应同一 actor
  3. 状态用替换:handoff.md 永远是单快照 replace-in-place,不追加历史;追加语义仅限 gotchas 条目与新 ADR。
  4. 替换守卫(一体动作):写 handoff 前立即重读其头部(grep -m1 '^- updated: ',无匹配即中止写入,不得盲写),基线 = 最后一次实际读取的 updated 与内容;文件比基线新则先合并再写;临时文件必须建在 docs/ai/ 同目录(如 .handoff.md.tmp——跨文件系统的 mv 不原子)再 mv 替换;可用 shell 时先解析 repo 根,用绝对路径 flock <repo根>/docs/ai/.handoff.lock 包裹「重读-合并-替换」全程,禁止相对路径锁(两个 harness 共用此锁)。守卫作用于替换既有 handoff;文件尚不存在的首次创建(初始化新仓或迁移落存根)直接写入含 - updated: 头部的完整快照,不适用「无匹配即中止」。
  5. 预算写入时执行:超出上限当场裁剪,不留给下次会话。
  6. git 即账本:实质任务完成即提交,提交正文写 目标 / 验证 / 风险;禁止积压跨任务未提交改动;不把完整 diff 粘进文档。非 git 仓库(降级安装,收据 git=no):提交类条款不适用,改动以文件落盘为准并在最终回复明示「非 git 降级」;不得擅自 git init(须用户批准,见 MIGRATE)。
  7. 未提交内容不进 canonical 文档:只可写入 handoff 并标 WIP/unverified。非 git 仓库:本条以「未验证」代读「未提交」——未验证内容同样只可写入 handoff 并标 WIP/unverified。

何时更新什么

实质改动收尾时的最小集合:

  • 永远:替换 handoff.md(当前目标、已完成、进行中、阻塞、下一步、验证状态、重要 commit)。
  • 结构 / 边界 / 部署 / auth / API 变了:rg 定位后更新 architecture.md 相应小节与相关 .mmd。
  • 命令 / env / 迁移 / 部署方式变了:更新 runbook.md 相应小节。
  • 踩到耐久新坑:向 gotchas.md 追加一条(带署名尾行);发现旧条目失效顺手删除。
  • 长期架构决策:新增 decisions/ADR-xxxx.md(Context / Decision / Consequences / Status)。
  • 纯小改:只替换 handoff,并在最终回复说明其他文件无需更新。

初始化(新仓库或老仓库补记忆)

  1. 只做文档与记忆初始化,不改业务代码。
  2. 依据:README、包与运行时 manifests、框架/路由/数据库/部署/CI 配置、rg --files 源树、git log --oneline -n 30(非 git 仓库跳过)。
  3. 按上方结构与预算生成 docs/ai/;拿不准的写 inferred 或 unknown,禁止编造业务意图、外部服务、凭证。
  4. 用户要求安装持续规则时,在仓库 AGENTS.md 增补 Project Memory 节(≤40 行):HOT/WARM/COLD 文件清单、写入纪律(引用本 skill)、仓库特有实例事实(预算仅可收紧,见核心规则)。保留既有无关规则,合并不删除。
  5. 用户拥有的项目:创建或更新中央 wiki 轻量 project entity(见下节)。

中央 LLM Wiki 同步(低频)

仅当 entity 级事实变化(项目新建/归档、架构方向调整、路径或 remote 变更)时,更新中央 project entity。定位先于命名(fail-closed):先 rg -lF "<repo根>" /home/shiyi/Apps/Obsidian/vault/60-Wiki/entities/ 反查,再逐个命中页核对归属,判据唯一——页 frontmatter 的 source_paths 含本仓根才算本仓页,正文提及本仓路径不算(他项目页常引用本仓路径)。恰一页合判据:更新该页(既有页名未必是仓库名的机械变形),禁止另建同仓新页;多页合判据:停止写入并报告用户裁定(同仓多页属待合并异常);命中页全不合判据即视同查无。查无且触发器是路径变更时,先用旧根按同判据再查一遍(命中即更新该页,并把 source_paths 刷新为新根);旧根不可得则在同一 entities/ 目录 rg -ilF "<项目名>" 找候选,归属仍不可判即停止并报告。查无(路径变更场景须两路都查无)才以唯一 slug 新建 entities/<repo-slug>.md;任何情况下不覆盖他仓页。页面内容:repo 路径、docs/ai/ 路径、关键文件链接、简短摘要、重要 gap。不逐任务同步,不复制完整项目文档进中央。编辑遵循 $llm-wiki 规则(frontmatter 写 updated_by: <actor>),改后运行 lint_wiki.sh;内容变更才运行 reindex_qmd.sh llm-wiki。

收尾自检与最终回复

  • 自检:写入是否全部带署名、守预算?handoff 是否仍为单快照?是否有该提交而未提交的改动?(非 git 仓库:此问不适用,改核对最终回复已明示「非 git 降级」)
  • 最终回复列出:改了哪些 docs/ai/ 文件、跑了什么验证、是否同步中央 entity、遗留 gap 或风险。

© tudoumashu, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/ai-project-memory of tudoumashu/ai-memory-skillpack.

  • SKILL.md
  • agents/openai.yaml

Open the folder on GitHubat commit f85cdec

Compare with similar skills

AI Project Memory next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

AI Project Memory compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
AI Project Memory this skilltudoumashu/ai-memory-skillpack443—~1.1kAutomated safety check: PassMIT
Neat-Freak Knowledge CloseoutKKKKhazix/khazix-skills21k—~1.9kAutomated safety check: PassMIT
Beads Task Memorygastownhall/beads28k—~1.2kAutomated safety check: PassMIT
Session History Searchslopus/happy24k—~3.1kAutomated safety check: PassMIT
Plan Previewu-ichi/reviewable-html-workbench2981 repos~1.8kAutomated safety check: PassMIT
Ownmemgrpcer/ownmem423—~593Automated safety check: PassApache-2.0

Similar skills

  • Neat-Freak Knowledge Closeout

    KKKKhazix/khazix-skills

    Brings project docs, agent rule files, authorized memory and leftover workspace files back in line with what the code and runtime actually do at the end of a work session.

    21k GitHub stars~1.9k tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed
  • Beads Task Memory

    gastownhall/beads

    Tracks multi-session work with dependencies in the bd issue tracker so the agent can find ready tasks and recover its context after conversation compaction.

    28k GitHub stars~1.2k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Searches past Claude Code, Codex and Cursor sessions and summarizes what was worked on, tried or decided, using extraction scripts instead of reading raw logs.

    24k GitHub stars~3.1k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Plan Preview

    u-ichi/reviewable-html-workbench

    Plan Mode の <proposedplan を出す直前に、計画の段階・依存関係・検証観点を一時HTMLで視覚確認したい時に使う agent-internal skill。Use this agent-internal skill to create a temporary HTML preview for a plan just before presenting…

    298 GitHub starsUsed in 1 repo~1.8k tokens
    Agent WorkflowsAuto-check passed
  • Ownmem

    grpcer/ownmem

    Recall this repository's OwnMem local memory before changing code, and keep it healthy.

    423 GitHub stars~593 tokensUpdated 3 days ago
    Agent WorkflowsAuto-check passed
  • Watchmen Setup

    firstbatchxyz/watchmen

    Walks through installing watchmen, running its init wizard, wiring the plugin into Codex or Claude Code and checking the result with doctor.

    296 GitHub stars~1.1k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check: notes

More from tudoumashu/ai-memory-skillpack

  • Project Mastery Coach

    tudoumashu/ai-memory-skillpack

    Train strict project ownership from repo-local docs/ai memory and central LLM Wiki project entities.

    443 GitHub stars~1.8k tokensUpdated 1 mo ago
    Auto-check passed
  • LLM Wiki

    tudoumashu/ai-memory-skillpack

    Query and maintain the user's local LLM Wiki from any Codex or Claude Code conversation or project.

    443 GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Categories

Questions about AI Project Memory

What does AI Project Memory do?

Maintain bounded, durable AI project memory in a repository's docs/ai/ pack. AI Project Memory is an agent skill from tudoumashu/ai-memory-skillpack. Maintain bounded, durable AI project memory in a repository's docs/ai/ pack.

When should I use AI Project Memory?

AI Project Memory fits situations like: Claude Code needs to create; audit project memory (project-card; install AGENTS.md memory rules; sync a lightweight central LLM Wiki project entity for user-owned projects.

How do I install AI Project Memory in Claude Code?

Run `npx skills add tudoumashu/ai-memory-skillpack --skill ai-project-memory -a claude-code`. Or copy the skill folder (skills/ai-project-memory in tudoumashu/ai-memory-skillpack) into .claude/skills/ai-project-memory in your project. Claude Code loads it when a task matches its description.

How do I install AI Project Memory in Codex?

Run `npx skills add tudoumashu/ai-memory-skillpack --skill ai-project-memory -a codex`. Or copy the skill folder (skills/ai-project-memory in tudoumashu/ai-memory-skillpack) into .agents/skills/ai-project-memory in your project. Codex loads it when a task matches its description.

Can I use AI Project Memory in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tudoumashu/ai-memory-skillpack --skill ai-project-memory -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ai-project-memory, .gemini/skills/ai-project-memory, .github/skills/ai-project-memory and .opencode/skills/ai-project-memory in your project.

What does AI Project Memory need to run?

Going by SKILL.md and its folder, AI Project Memory needs the command-line tools its instructions call (rg and git).

Does AI Project Memory access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is AI Project Memory safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does AI Project Memory use?

AI Project Memory is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does AI Project Memory use?

About 1.1k tokens (SKILL.md is roughly 4.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to AI Project Memory?

Skills that share tags, products or a category with AI Project Memory: Neat-Freak Knowledge Closeout (KKKKhazix/khazix-skills, 21k stars), Beads Task Memory (gastownhall/beads, 28k stars), Session History Search (slopus/happy, 24k stars) and Plan Preview (u-ichi/reviewable-html-workbench, 298 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains AI Project Memory?

tudoumashu (a GitHub user) maintains it in tudoumashu/ai-memory-skillpack, which has 443 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on September 8, 2026.

Source: tudoumashu/ai-memory-skillpack on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.