Glyph

Glyph gives AI coding agents a memory that lives where it is most likely to be read again: next to the code.

When an agent learns something the hard way — a subtle invariant, a failed approach, a deliberate tradeoff, a gotcha future edits might accidentally break — Glyph teaches it to leave a small inline @agent: note beside the relevant function, class, module, or line.

Not every thought belongs in the code. Glyph is intentionally quiet by default. It is for code-bound knowledge only: the kind of context git blame, comments, tests, and type signatures often fail to explain.

What it looks like

# @agent:invariant 2026-07-24 — `ts` is exchange UTC, not local time. Converting
#   here introduces look-ahead bias in backtests. revisit-if: feed switches timezone semantics.
def align_bars(ts: int, price: Decimal) -> Bar:
    ...

The point is not to create more comments. The point is to stop agents from repeating the same expensive mistake six sessions later.

What is included

Glyph ships two repo-local skills and a lightweight Codex hook.

codebase-memory-capture

The write-side skill.

Use it while editing non-trivial code. It tells the agent when to add an inline @agent: note, when to stay silent, where to place the note, and how to keep notes from rotting.

It only allows four tags:

• lesson — tried X, it failed because Y, do Z instead.
• decision — chose X over Y because Z.
• invariant — this must hold or something silently breaks.
• gotcha — counterintuitive but correct; do not casually “fix” it.

codebase-memory-distill

The harvest-side skill.

Use it near the end of a project, or periodically in a long-lived codebase. It scans all inline @agent: notes, clusters the durable lessons, and helps promote the generalizable ones into reusable rules for future projects.

Inline notes are the raw feed. Distilled rules are the compounding payoff.

Codex hook

The hook does not paste the whole skill into every prompt. It only reminds Codex at low-frequency boundaries:

• SessionStart — when a new session begins.
• SubagentStart — when a subagent starts and might not inherit enough context.

There is intentionally no UserPromptSubmit hook. That avoids paying tokens on every prompt.

Install

Requirements:

• python3 for the Codex hook and installer merge step.
• jq only for the distill scanner script.

From inside the Glyph repo:

./install.sh /path/to/your/project

Or install into the current directory:

./install.sh

This copies:

.agents/skills/codebase-memory-capture/SKILL.md
.agents/skills/codebase-memory-distill/SKILL.md
.agents/skills/codebase-memory-distill/scripts/scan-agent-notes.sh
.codex/glyph_hook.py

It also merges these Codex hook entries into .codex/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/project/.codex/glyph_hook.py SessionStart"
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/project/.codex/glyph_hook.py SubagentStart"
          }
        ]
      }
    ]
  }
}

If your project already has Codex hooks, the installer preserves them and appends Glyph.

Codex may ask you to trust the new hook once. Approve it if the path is the .codex/glyph_hook.py file in your project.

Manual install

Copy the two skills:

mkdir -p .agents/skills
cp -R skills/codebase-memory-capture .agents/skills/
cp -R skills/codebase-memory-distill .agents/skills/

Copy the hook:

mkdir -p .codex
cp hooks/codex/glyph_hook.py .codex/glyph_hook.py
chmod +x .codex/glyph_hook.py

Then add SessionStart and SubagentStart commands to .codex/hooks.json.

Distill notes

Run the deterministic scanner:

.agents/skills/codebase-memory-distill/scripts/scan-agent-notes.sh .

It outputs JSON with every @agent: note, including:

• path
• line
• tag
• date
• text
• revisit_if

The distill skill then uses that harvest to decide which notes are project-local and which deserve promotion into reusable rules.

Philosophy

Code comments explain what the code does.

Glyph explains what the next agent should not forget.

It is small on purpose: a skill, a scanner, and a hook. No daemon. No database. No context spam.