v0.3.0: anti-drift, recaps, mono mode, PR-comment Action#1
Merged
Conversation
- Add MIT LICENSE (README advertised it but file was missing) - Add CLAUDE.md as a Claude Code entry point alongside replit.md - Add scripts/validate.py — stdlib-only JSON / line-count checker - Add .claude/ SessionStart hook that runs the validator on web sessions - Reorganize: stub starter files moved to template/memory/; root memory/ now self-describes vibe-memory so the repo eats its own dog food - Expand README with a quickstart, structure, validation, and web hook sections
A — CI + tests - .github/workflows/validate.yml runs validator on root, template, and every example, plus the 16-case unittest suite - tests/test_validate.py covers bad JSON, wrong type, missing fields, bad timestamps, line caps, archive entries, blank-line skipping - README adds CI, license, and protocol-version badges - scripts/validate.py refactored to accept a memory_dir positional arg B — Lifecycle & contribution docs - AGENTS.md as generic entry point (Cursor, Aider, Codex, OpenHands) - CONTRIBUTING.md covers protocol, entry-point, and tooling change flows - CHANGELOG.md starts at 0.1.0 -> 0.2.0 - Protocol version header in MEMORY_PROTOCOL.md C — Distribution polish - install.sh one-line installer with --ref pinning - .pre-commit-hooks.yaml exposes vibe-memory-validate hook - schemas/decision.schema.json + schemas/drift.schema.json formalize the JSON contract independently of the Python validator D — Filled example states - examples/web-app — Next.js + Postgres SaaS mid-checkout-migration - examples/cli — Rust CLI with shipped release + feature in flight - examples/library — Python library with deprecation in progress
gregherbe76
changed the title
…eats In response to Lovable's review of the repo: - lovable.md: position mem:// as a cache; memory/ wins on conflict. Avoids duplication and lock-in; memory/ is portable across runtimes. - MEMORY_PROTOCOL.md section 1: split into mandatory tier (architecture + progress) and conditional tier (decisions + drift tails) for trivial sessions. Section 10 confirmation line gains a trivial-session variant. Stops wasting tokens on typo-fix sessions. - scripts/validate.py: optional --check-freshness DAYS flag, warn-only. Soft pressure against the append-only-log decay failure mode (logs that aren't maintained degrade silently). 4 new tests bring the suite to 20. - README.md: 'When is this worth it?' section. Prevents over-application on weekend prototypes, which discredits the approach when memory/ files don't reflect reality after two weeks.
A — lovable.md expanded - Explicit boundary: mem:// = rules (applied automatically), memory/ = journal (audit log). memory/ wins on conflict; mem:// is a cache. - Skip protocol section 7 (compression) on Lovable — chat_search covers retrieval; rollback entries reserved for architectural reversals (Lovable checkpoints cover code-level reverts). - Lovable-specific structural events to log: integration activation, Cloud activation (frontend->fullstack bascule), secrets--*, publish, lovable_sql migrations. - mem://~user/ precedence rules. - Recommended Core snippet for mem://index.md (short, imperative). B — MEMORY_PROTOCOL.md section 2 rewritten Replaced "any change affecting >=2 files" with an explicit list of structural events: integration activation, DB migration, new secret, new runtime dependency, first instance of a new pattern, deployment target change, stack swap, architectural reversal. Explicitly excludes content pages, buttons, colour changes, typo fixes. Stops noise on platforms where most prompts touch multiple files. C — scripts/render.py Renders decisions.jsonl + drift.jsonl into a chronological markdown journal grouped by date. JSONL stays source of truth; this is a derived view for human reading. 2 new tests bring the suite to 22. Also rejected the "branch per runtime" idea (logged as decision): portability is the core value prop; runtime-specific behavior is absorbed via entry-point files (replit.md, CLAUDE.md, lovable.md, AGENTS.md), not by forking the protocol.
…ent Action Five changes aimed at making vibe-memory visible to actual users — the gap between "the agent has a memory" and "the user sees the memory working". 1. Real-time anti-drift (protocol section 4). Agent MUST stop and ask for explicit confirmation before writing code that contradicts any entry in the last 50 decisions. This is the killer demo: the moment that proves the protocol is doing something useful. Drift detection AFTER the change kept as section 4.5. 2. Session-start recap (protocol section 10). First reply is a 3-line recap: memory marker + stack/conventions + in-flight item + open drift. Free in tokens, transforms perceived value. 3. Session-end recap (protocol section 11, new). Before stopping, surface 3-5 lines: changed / logged / next / open question. What the user sees first when they return — more useful than scrolling the diff. 4. Mono-file mode. template/vibememory.md is a single self-contained file (lite protocol + memory tables). install.sh --mode mono drops that one file. Reduces entry cost for solo / MVP / weekend projects; upgrade path to full mode preserved. 5. PR-comment GitHub Action. .github/workflows/memory-pr-comment.yml posts a sticky comment on each PR summarizing decisions and drifts added. Surfaces vibe-memory in the normal dev workflow without requiring users to open JSONL. Backed by scripts/pr_comment.py (3 new tests, 25 total). Protocol version bumped 0.2.0 -> 0.3.0.
🧠 vibe-memory changes in this PR32 new decision(s):
Posted by the vibe-memory PR-comment workflow. Edit decisions/drift entries before merging if needed. |
…ontext, compaction)
gregherbe76
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings vibe-memory from a docs-only protocol sketch to a verifiable, installable, multi-agent-aware v0.3.0 with real-time anti-drift, session recaps, mono-file mode, and PR-comment automation.
What's in this PR
Protocol (
MEMORY_PROTOCOL.md)Protocol version: 0.3.0)architecture.md+progress.mdalways;decisions.jsonl/drift.jsonltails only for structural sessions/context/ "where are we" / "remind me", or when memory is re-read mid-sessionEntry points
replit.md— Replit Agent (was already present, kept)CLAUDE.md— Claude Code (new)lovable.md— Lovable (new) — carves themem://(rules) vsmemory/(journal) boundary; documents Cloud activation / publish /secrets--*/lovable_sqlas Lovable-specific structural events; provides recommended Core snippet formem://index.mdAGENTS.md— generic entry point for Cursor / Aider / Codex / OpenHands (new)Verification
scripts/validate.py— Python 3 stdlib-only validator with--check-freshness DAYSflag (warn-only)scripts/render.py— renders JSONL logs into a chronological markdown journal (JSONL stays source of truth)scripts/pr_comment.py— diffs memory between two refs, produces a markdown PR commenttests/test_validate.py— 25 unittest cases covering validator, renderer, and pr_commentschemas/decision.schema.json+schemas/drift.schema.json— JSON Schema Draft 2020-12.github/workflows/validate.yml— CI runs validator + tests on root, template, and every example.github/workflows/memory-pr-comment.yml— sticky PR comment summarizing decisions/drifts added (live since this PR's last push).claude/hooks/session-start.sh+.claude/settings.json— SessionStart hook for Claude Code on the webDistribution
install.sh— one-line installer, supports--mode full|monoand--refpinning, idempotenttemplate/memory/— blank starter files (full mode)template/vibememory.md— single self-contained file (mono mode) — lite protocol + memory tables in one place; upgrade path to full mode preserved.pre-commit-hooks.yaml— exposesvibe-memory-validatefor downstream projectsReorganization
template/memory/memory/self-describes vibe-memory (eat your own dog food)examples/contains three worked memory states:web-app(Next.js + Postgres SaaS),cli(Rust),library(Python)Lifecycle docs
LICENSE(MIT, was already advertised in README)CHANGELOG.md(0.1.0 → 0.2.0 → 0.3.0)CONTRIBUTING.mdwith separate flows for protocol / entry-point / tooling changesREADME
--mode mono | fullchoiceValidation matrix (all green)
memory/— 33 decisions, 0 driftstemplate/memory/— empty, validexamples/web-app/memory/— 5 decisions, 2 driftsexamples/cli/memory/— 4 decisions, 1 driftexamples/library/memory/— 4 decisions, 1 driftinstall.shpassesbash -nin both modesTest plan
validateandmemory-pr-commentworkflows)v0.3.0and create the GitHub release (unlocksinstall.sh --ref v0.3.0and therev: v0.3.0pre-commit pin)Commits
49ad563Harden vibe-memory: license, validator, hook, CLAUDE.md, reorganizedda9d0bv0.2.0 polish: CI, tests, schemas, examples, install.sh, AGENTS.md51f87b4README: reframe tagline around memory longevity433d96fAdd lovable.md entry point for Lovable projects26b5f47Lovable round 1: tiered reading, freshness check, caveatsecde4a4Lovable round 2: structural-event triggers, mem:// boundary, render.py3fa6af5lovable.md: document the validation surfaced4da072v0.3.0: real-time anti-drift, session recaps, mono-file mode, PR-comment Actionf374242Protocol §10: explicit triggers for the memory recap (idle, /context, compaction)