From 95587fd097dd5c609dba4c7db397d0b4a38f3415 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 19 May 2026 16:34:06 +0000 Subject: [PATCH] README: continuity-layer positioning, hero anti-drift block, FAQ --- README.md | 45 ++++++++++++++++++++++++++++++++++++++++-- memory/decisions.jsonl | 1 + 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f5c32b5..f59d0cd 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,28 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Protocol version](https://img.shields.io/badge/protocol-v0.3.0-informational)](MEMORY_PROTOCOL.md) -A memory protocol for vibe coding agents. Persistent memory for coding agents — across sessions, across agents, across months. +**A continuity layer for AI-built projects.** Persistent memory for Claude Code, Cursor, Lovable, Replit Agent — across sessions, across agents, across months. + +> Without continuity, the human becomes the project's memory system. vibe-memory takes that load off. Works with Replit Agent, Claude Code, Lovable, Cursor, Aider, Codex, OpenHands, and any agent that reads instruction files from the repo. +## The moment that pays for it + +You decided to drop Prisma a month ago. Today the agent is about to re-add it. With vibe-memory, this happens **before** the import goes in: + +``` +⚠️ Conflicting decision detected + 2026-03-12 — dependency: dropped Prisma in favor of Drizzle + Reason: serverless cold starts on Neon + Confirm reversal? (y/N) +``` + +No silent regression. No "wait why does this still use Prisma?" three weeks later. That's the protocol's most visible value — see section 4 of `MEMORY_PROTOCOL.md`. + ## How it works -The agent reads `MEMORY_PROTOCOL.md` and an entry-point file for its runtime (`replit.md`, `CLAUDE.md`, `lovable.md`, or `AGENTS.md`) at the start of every session. It logs decisions, detects drift, tracks progress. No CLI, no package, no MCP. Just files. +The agent reads `MEMORY_PROTOCOL.md` and an entry-point file for its runtime (`replit.md`, `CLAUDE.md`, `lovable.md`, or `AGENTS.md`) at the start of every session. It logs structural decisions, detects drift, tracks progress, and stops itself when about to contradict a logged choice. No CLI, no package, no MCP. Just files. ## When is this worth it? @@ -140,6 +155,32 @@ The included `.claude/settings.json` registers a SessionStart hook that runs the Each entry in `decisions.jsonl` and `drift.jsonl` carries an `author` field. When more than one agent works on a project (e.g. Claude Code reviewing what Cursor wrote), each agent treats the other's entries as authoritative and logs a `rollback` entry if it needs to reverse a prior decision. See `MEMORY_PROTOCOL.md` section 8. +## FAQ + +### Why not an MCP memory server? + +MCP servers do **retrieval** — semantic search over large context, embeddings, knowledge graphs. vibe-memory does **continuity** — making sure architectural decisions survive sessions and that the agent doesn't silently contradict them. The two are complementary: use both if you need both. vibe-memory's territory is portability, auditability, git-native, visible anti-drift, zero infra. + +### Why not just a `CLAUDE.md` / `.cursorrules`? + +Those store **rules** (preferences, conventions, "never use X"). vibe-memory stores **events** — decisions with timestamps, drift detected, progression over time. The two are complementary. On Lovable specifically the boundary is explicit: `mem://` = rules, `memory/` = journal (see `lovable.md`). + +### Is this just ADRs (Architecture Decision Records)? + +ADRs are a format written by humans, for humans, often after the fact. vibe-memory is the same idea **operationalized** for AI coding: machine-readable (JSONL + JSON Schema), written by the agent during the session, re-read by the agent at every future session. ADRs informed the design; vibe-memory is what you get when the audience changes from human reviewer to coding agent. + +### Will the agent actually follow the protocol? + +Frontier models (Claude 4.x, GPT-5, etc.) follow structured instructions reliably. The validator catches malformed entries (CI blocks, pre-commit rejects). The section 10 recap shows you in real time whether the agent read the memory. For substantive adherence to logged decisions, the loop closes when you skim the log periodically (the `--check-freshness` flag warns when you've stopped). + +### How does it scale? + +Manual compression when `decisions.jsonl` exceeds 500 lines (protocol section 7). On Lovable, that section is skipped because `chat_search` provides retrieval natively. For semantic search over a very large log, pair vibe-memory with an MCP memory server — vibe-memory writes the truth, MCP indexes it. + +### What about token cost? + +Tiered reading (protocol section 1). On a typo-fix session, the agent reads only `architecture.md` + `progress.md` (~200 tokens). On a structural session, also the tails of `decisions.jsonl` + `drift.jsonl` (~800-1500 tokens). Compared to a manual re-briefing or a regression to fix, it's negligible. + ## License MIT — see [LICENSE](LICENSE). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/memory/decisions.jsonl b/memory/decisions.jsonl index 62f745a..87c913e 100644 --- a/memory/decisions.jsonl +++ b/memory/decisions.jsonl @@ -31,3 +31,4 @@ {"timestamp":"2026-05-19T06:00:04Z","type":"dependency","component":"ci","change":"added scripts/pr_comment.py + .github/workflows/memory-pr-comment.yml posting a sticky PR comment summarizing memory changes","reason":"surfaces vibe-memory inside the normal dev workflow (PR review) without requiring users to open JSONL","impact":["scripts/pr_comment.py",".github/workflows/memory-pr-comment.yml","tests/test_validate.py"],"author":"claude-code"} {"timestamp":"2026-05-19T06:00:05Z","type":"convention","component":"versioning","change":"bumped protocol version 0.2.0 -> 0.3.0","reason":"sections 4, 10, 11 are new protocol-level features (anti-drift, session-start recap, session-end recap)","impact":["MEMORY_PROTOCOL.md","CHANGELOG.md","README.md","memory/architecture.md"],"author":"claude-code"} {"timestamp":"2026-05-19T07:00:00Z","type":"convention","component":"protocol","change":"section 10 recap triggers expanded beyond 'session start': also fires on idle > 15 min, after context compaction, on explicit user request (/context, 'where are we', 'remind me'), and when memory is re-read mid-session","reason":"recap is most valuable when the user has lost context — that happens at more moments than just a fresh session; explicit triggers prevent ambiguity","impact":["MEMORY_PROTOCOL.md","CHANGELOG.md"],"author":"claude-code"} +{"timestamp":"2026-05-19T08:00:00Z","type":"convention","component":"positioning","change":"README reframed around 'continuity layer for AI-built projects'; added business-pain line, hero anti-drift block, and FAQ (MCP=retrieval vs vibe-memory=continuity, CLAUDE.md=rules vs memory/=events, ADR comparison)","reason":"prepare repo for v0.3.0 launch: replace abstract 'persistent memory' positioning with concrete 'continuity' framing and the anti-drift moment as the hero","impact":["README.md"],"author":"claude-code"}