From 3b36d8be3ec6978abde5fb720fcce3bfbd2cf4b8 Mon Sep 17 00:00:00 2001 From: Ivan Pasichnyk Date: Fri, 1 May 2026 21:40:00 -0700 Subject: [PATCH] docs(readme): Quick Start above the fold; add Glossary; pack repo link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Earlier order was: hero → Question → What It Is Not → Methodological Core → Quick Start. A new visitor had to scroll past three sections of context before seeing how to install. Reorders to: hero → Quick Start → Question → Glossary → What It Is Not → Methodology. Action first, context for those who stay. Adds a Glossary section because the docs use four terms for related things (trajectory / pack / skill / openexp-use) and readers conflate them. Three-line definition each. Adds a pointer from Quick Start to the seed pack repo (anthroos/exp-inbound-acquisition-with-free-pilot) so a fresh visitor who finishes setup.sh has a clear next step: install a real pack and try retrieval. --- README.md | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) 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: