diff --git a/README.md b/README.md index 00428d6..6008d47 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,39 @@ --- +## Quick Start + +```bash +git clone https://github.com/anthroos/openexp.git +cd openexp +./setup.sh +``` + +That installs the four hooks into Claude Code, brings up Qdrant in Docker, and registers the MCP server. + +**Prerequisites:** Python 3.11+, Docker, jq. + +No API key required for core functionality. Embeddings run locally via FastEmbed. An Anthropic API key is optional and only powers the two-prompt pipeline (anonymize + extract experience) when you publish. + +To install the seed pack (a real 57-day B2B sales arc, anonymized) and try retrieval against a worked example, see [`exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot) — install instructions in its README. + +--- + ## The Question When you close a deal, ship a feature, or lose a client — *how did it happen*? Which decisions, in what order, against which context, on which hypotheses? Today's AI agents can't answer that. They follow skills and instructions perfectly, but they don't accumulate grounded knowledge about how outcomes actually arrived. OpenExp captures every human-AI decision as a step in a trajectory, links those steps into coherent journeys, and grades each journey retroactively when reality returns its verdict — a deal closes, a sprint ships, a payment lands. The result is a continuously growing labeled dataset of decisions tied to outcomes, ready to train domain-specific intuition. +## Glossary + +A few terms repeat throughout. Settling them up front: + +- **Trajectory** — an ordered timeline of decisions a human and AI made together over the life of one closed arc (a deal, a feature, an incident). The unit of data. +- **Pack** — a published, anonymized trajectory plus its `meta.yaml`. The unit of distribution. Lives in its own GitHub repo. +- **Skill** — how Claude Code installs and invokes a pack. Naming convention: `openexp::`. +- **`openexp-use`** — the universal applier skill that, given an installed pack, reads its trajectory and answers your situation with a cited day. + ## What It Is Not - **Not a Q-learning memory system.** We tried Q-values for 8 months. Mean Q-value across 27,000 memories was 0.006; 90% of memories never received any reward signal. Removed on 2026-04-26. @@ -50,20 +77,6 @@ Steps are stored raw. Authors annotate their own intent, hypotheses, and decisio Casual analogy: kids in school don't get annotations on every homework problem. They turn in work, get a grade at the end of the term, and develop intuition over hundreds of grades. -## Quick Start - -```bash -git clone https://github.com/anthroos/openexp.git -cd openexp -./setup.sh -``` - -That installs the four hooks into Claude Code, brings up Qdrant in Docker, and registers the MCP server. - -**Prerequisites:** Python 3.11+, Docker, jq. - -No API key required for core functionality. Embeddings run locally via FastEmbed. An Anthropic API key is optional and only powers the two-prompt pipeline (anonymize + extract experience) when you publish. - ## How It Works Four hooks run automatically inside Claude Code: