Oh My Experience

Stop teaching your agent the same lesson twice.

A local prompt-time recall layer for reviewed coding-agent lessons.

English · Chinese · Documentation

Oh My Experience is a local-first experience layer for AI coding agents. It
turns real Codex and Claude corrections into reviewed experience cards, then
can recall a relevant approved lesson at prompt time before the agent repeats
the same kind of mistake.

Quick Try

npx oh-my-experience@latest init

Then send a real task to your agent:

Create a goal and start now: in /tmp/ome-todo-demo, build a small single-page Todo app with plain HTML, CSS, and JavaScript.
It should let me add tasks, mark tasks complete, delete tasks, clear completed tasks, show the remaining count, persist tasks in localStorage, and look usable on a narrow mobile viewport.
Verify it through the real browser entry before reporting completion.
After finishing, guide me through the OME lifecycle: scan this full run, summarize reusable lessons, review the generated drafts with me, and only add approved drafts to the experience library.

The installed hook handles recall automatically. For troubleshooting, ask your
agent to inspect recall; users should not need a separate search command for
the first successful run.

Why OME

AGENTS.md and CLAUDE.md are good for stable project maps and always-on
rules. Skills package repeatable workflows. Memory stores facts and long-term
context.

OME stores a different thing: execution judgment from real work.

Rules are always-on. OME is conditional memory for execution judgment.

OME is not a replacement for memory, AGENTS.md, CLAUDE.md, or skills. It
recalls reviewed execution lessons only when the current task needs them.

Most hard-won lessons are conditional: they matter for UI validation, release
work, Git safety, review, or one specific project. OME keeps those lessons out
of always-on context and recalls them only when the current task is likely to
need them.

An experience card can also remind the agent which skill, guide, checklist, or
project convention mattered last time. OME still stores the lesson as a reviewed
card; how the agent uses that reminder stays part of the workflow.

What You Get

• Local-first recall: no network calls on the prompt-time path.
• Draft approval before recall: candidate -> draft -> active -> archived.
• Codex and Claude hooks using the same local runtime.
• Native Codex/Claude user-only evidence indexing for deep retrospectives.
• Global libraries plus optional project libraries at .oh-my-experience/.
• Explainable matching with scores, reasons, and compact injected context.
• Evaluation fixtures for checking missed or noisy recall before release.

Local By Default

• No cloud service or account.
• No embedding API.
• No LLM call on the hook path.
• Raw prompt logging is opt-in.
• Hook failures fail open so your agent is not blocked.

Example

When you use Codex with a /goal-style request:

Create a goal and start now: in /tmp/ome-todo-demo, build a small single-page
Todo app. It should support add, complete, delete, clear completed, remaining
count, localStorage persistence, and browser verification.

OME can recall the approved card Enter full-closure delivery mode when a goal starts before Codex starts. The useful part is not the underlying command; it
is that the agent sees the right execution judgment before acting.

The recalled card tells the agent:

When the user says `/goal`, `create a goal`, `use goal`, `start now`,
`start executing the goal`, `run a long task`, or asks to move a set of
requirements into goal execution, treat it as an execution startup protocol,
not as ordinary goal copy. Default execution rules:

1. Before starting, clarify the goal, scope, non-scope, real completion
   criteria, and itemized acceptance checklist. If the goal is cut too small,
   call out the scope risk and include the user-confirmed requirements in the
   same goal.
2. Execute systematically from the full plan, anchored to the source of truth,
   story, roadmap, design plan, or user wording. Do not drift in direction or
   stop after the first visible slice.
3. Close every planned feature end to end. Do not ship half-finished work, happy
   paths only, UI shells, partial APIs, placeholders, fake routes, hidden test
   entries, in-memory substitutes, fake external actions, or fallbacks that
   create two versions of the truth.
4. Keep implementation maintainable, extensible, robust, and resilient. Split
   modules on real boundaries, keep responsibilities clear, and clean directly
   related dead or dirty logic when needed. Do not add abstract layers for an
   imagined future.
5. Validate through real entries and real user paths. Commands, features,
   states, docs, and evidence must cover the checklist. A successful command,
   local smoke test, or finished code change is not completion by itself.
6. For complex or high-risk goals, run a self-review after implementation. When
   needed, dispatch an external model or review flow to check direction drift,
   feature completeness, real usability, architecture quality, and
   maintainability.
7. Completion must fail closed. If any planned feature is unfinished,
   acceptance evidence is missing, validation failed, environment blockers are
   unexplained, or risks are not stated, do not mark the goal complete. Continue
   fixing it or clearly mark it blocked.
8. Final delivery should explain the user-facing change, verified evidence,
   risks or limits, and open confirmations.

The key point is timing: this rule is not always loaded. It appears when the
task actually looks like goal execution, and stays out of the prompt when the
user is only discussing docs, OKRs, or what /goal means. See the walkthrough in
Examples.

How It Works

real session -> reflect scan -> draft approval -> confirmed active card -> prompt-time recall -> stats -> refinement

1. Build native user-only evidence from Codex/Claude sessions, optionally supplemented by Spool.
2. Turn repeated corrections into experience drafts.
3. Approve, merge, rewrite, or reject drafts before activation.
4. Confirm what becomes active, then let hooks recall active cards when a matching task appears.

Only active cards are recalled. OME does not silently turn AI-generated notes
into permanent rules.

Documentation

For local development from source:

git clone https://github.com/rennzhang/oh-my-experience.git
cd oh-my-experience
npm install
npm run build
node bin/ome.js init

• Quickstart
• First Experience Card
• Examples
• Setup
• Source Scan
• Global and project libraries
• CLI Reference
• Retrieval Engine
• Chinese documentation

Contributing And Security

• Contributing
• Security policy
• Changelog

License

MIT