Proposal: repo-scoped experience compiler hooks for memory, evals, briefs, and skills

Proposal

I built an OSS companion tool called WorkGraph:

https://github.com/ranausmanai/agent-workgraph

WorkGraph watches local Codex and Claude coding sessions and compiles them into repo-scoped engineering intelligence:

• project journey / milestones
• learned repo rules
• known traps and repeated failure patterns
• eval/check candidates
• reusable skills and task patterns
• future-agent briefs
• AGENTS.md-style instruction suggestions
• a local UI for inspecting the compiled work graph

This is related to memory, but the focus is not raw memory storage. The focus is experience compilation: turning human-agent work into durable, inspectable repo intelligence that future agent sessions can reuse.

Why this matters

Codex sessions generate high-value experience:

• what the user asked
• what the agent tried
• what failed
• what the human corrected
• which files were involved
• which tests or checks proved the fix
• what future agents should avoid

Today much of that disappears into chat history, compaction summaries, or broad memory. Repo-scoped, inspectable compiled memory would reduce repeated mistakes and repeated context explanation, especially for users who work across many repositories.

This also overlaps with existing memory discussions, especially scoped/project memory. The distinction I want to highlight is that the useful unit is often not a single memory note, but a compiled work episode: task → attempts → correction → verification → reusable lesson/eval.

Current reference implementation

WorkGraph is currently an external local-first tool. It works by reading local session artifacts and writing repo-local outputs under .workgraph/.

Current surfaces include:

• CLI: workgraph start, workgraph stop, workgraph brief, workgraph reuse
• Codex skill install: users can ask Codex to start WorkGraph from inside a session
• Claude Code slash command install: /workgraph
• local web UI at http://127.0.0.1:8787
• repo artifacts such as journey.md, workgraph.md, known_traps.md, generated_evals.jsonl, repo_rules.md, agent_instructions.md, and task_templates.md
• cross-project reusable skills stored under ~/.workgraph/skills/
• local default compiler, with optional model-backed providers only when explicitly enabled

The goal is not to make Codex depend on WorkGraph. The goal is to explore whether Codex should expose a clean interface so external tools can safely interoperate with Codex around repo-scoped memory and experience compilation.

Requested Codex integration points

I am not opening a PR because the contributing guide says external PRs are invitation-only.

Instead, I would like feedback on whether Codex would consider lightweight extension points for external experience compilers, such as:

1. A documented local session transcript/event export path
2. A lifecycle hook after session turns, stop, or compaction
3. A project-scoped startup brief file that Codex can choose to read
4. A way for external tools to provide a relevant repo brief before a new session starts
5. A documented schema for repo memory / eval / trap / skill artifacts
6. Optional controls for users to inspect, disable, or clear repo-scoped compiled memory

Example output

For a future task, WorkGraph can produce a brief like:

Relevant repo memory:
1. Similar checkout timeout issue was caused by token refresh, not retry count.
2. paymentClient.ts has hidden coupling with auth/session.ts.
3. Always run npm run test:payments after touching checkout.
4. Avoid changing global timeout constants; that caused flaky CI twice.

Related issues

This seems related to long-term and scoped memory discussions, but may be a slightly different surface area because it focuses on compiled session experience and repo-local artifacts rather than only memory storage.

If this direction aligns with the Codex roadmap, I am happy to provide implementation notes, failure cases, schema examples, or a narrower design proposal.