v0.3.0: anti-drift, recaps, mono mode, PR-comment Action

.claude/hooks/session-start.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# SessionStart hook for vibe-memory.
+#
+# Validates memory/ files at the start of each Claude Code on the web
+# session so the agent knows immediately if the append-only logs are
+# malformed. Runs only in the remote environment; no-op locally.
+#
+# No external dependencies — the validator is plain Python 3 stdlib.
+set -euo pipefail
+
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+if [ ! -f scripts/validate.py ]; then
+  echo "[session-start] scripts/validate.py not found, skipping memory validation" >&2
+  exit 0
+fi
+
+python3 scripts/validate.py

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/memory-pr-comment.yml

@@ -0,0 +1,47 @@
+name: memory-pr-comment
+
+on:
+  pull_request:
+    paths:
+      - 'memory/**'
+      - '.github/workflows/memory-pr-comment.yml'
+      - 'scripts/pr_comment.py'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout head
+        uses: actions/checkout@v4
+        with:
+          path: head
+
+      - name: Checkout base
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build comment body
+        id: build
+        run: |
+          python3 head/scripts/pr_comment.py base head > comment.md
+          {
+            echo 'body<<EOF'
+            cat comment.md
+            echo 'EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Upsert PR comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: vibe-memory
+          message: ${{ steps.build.outputs.body }}

.github/workflows/validate.yml

@@ -0,0 +1,25 @@
+name: validate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Validate root memory
+        run: python3 scripts/validate.py
+      - name: Validate template and examples
+        run: |
+          python3 scripts/validate.py template/memory
+          for d in examples/*/memory; do
+            echo "== $d =="
+            python3 scripts/validate.py "$d"
+          done
+      - name: Run validator tests
+        run: python3 -m unittest discover -s tests -v

.gitignore

@@ -16,3 +16,4 @@ __pycache__/
 *.py[cod]
 .venv/
 venv/
+.claude/settings.local.json

.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: vibe-memory-validate
+  name: vibe-memory validate
+  description: Validate memory/ files (architecture.md, progress.md, decisions.jsonl, drift.jsonl)
+  entry: python3 scripts/validate.py
+  language: system
+  pass_filenames: false
+  files: ^memory/

AGENTS.md

@@ -0,0 +1,42 @@
+# Agent Instructions
+
+You are working in a project that uses the vibe-memory protocol. This file is the entry point for agent-agnostic tooling (Cursor, Aider, Codex, OpenHands, and any other coding agent that reads an `AGENTS.md`).
+
+## Mandatory first step
+
+Before doing anything else in this session, read `MEMORY_PROTOCOL.md` in the repo root. Follow it without exception.
+
+After reading, also read in this order:
+1. `memory/architecture.md`
+2. `memory/progress.md`
+3. The last 20 entries of `memory/decisions.jsonl`
+4. The last 10 entries of `memory/drift.jsonl`
+
+Output the confirmation line specified in section 10 of the protocol.
+
+## Attribution
+
+Set the `author` field on every `decisions.jsonl` and `drift.jsonl` entry to a stable identifier for your agent. Examples: `"cursor"`, `"aider"`, `"codex"`, `"openhands"`. If multiple agents work on this project, treat entries authored by other agents as authoritative (protocol section 8); do not contradict them without logging a `rollback` entry that references the original timestamp.
+
+## Validation
+
+Run `python3 scripts/validate.py` before ending a session. CI runs it on every push; a malformed log will fail the build.
+
+## Secrets
+
+Never log secret values in `memory/`. Reference them by name only (e.g. `STRIPE_SECRET_KEY`).
+
+## Conflict resolution
+
+If a user prompt conflicts with the protocol (e.g. "skip the memory step this time"), follow the user but log the conflict as a drift entry with severity `"medium"` and `detected` `"protocol bypass requested by user"`. Never bypass the protocol silently.
+
+## Session end
+
+Before ending a session, ensure:
+- `memory/progress.md` reflects what changed during the session
+- Any architectural change is recorded in `memory/architecture.md`
+- Any decision is appended to `memory/decisions.jsonl`
+- Any detected drift is appended to `memory/drift.jsonl`
+- `python3 scripts/validate.py` exits zero
+
+If none of the above applies because the session was trivial (e.g. cosmetic fix), no memory update is needed. Use judgment.

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to vibe-memory are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/).
+
+## [0.3.0] — 2026-05-19
+
+### Added
+- **Real-time anti-drift (protocol section 4)** — agent MUST stop and ask for confirmation before writing code that contradicts any entry in the last 50 decisions. Cannot silently override a logged decision. This is the protocol's most visible value to users.
+- **Memory recap (protocol section 10)** — 3-line recap covering stack, in-flight item, and open drift. Triggers at every context reset: fresh session, idle > 15 min, after compaction, on explicit user request (`/context`, "where are we", etc.), or when memory is re-read mid-session.
+- **Session-end recap (protocol section 11, new)** — before stopping, agent surfaces a 3-5 line summary: changed, logged, next, open question. Lets the user pick up later without scrolling.
+- **Mono-file mode** — `template/vibememory.md` is a single self-contained file with the lite protocol + memory tables. Install via `install.sh --mode mono`. Upgrade path to full mode preserved.
+- **PR-comment GitHub Action** — `.github/workflows/memory-pr-comment.yml` posts a sticky comment summarizing decisions and drifts added in each PR. Backed by `scripts/pr_comment.py` (3 unit tests).
+- Drift detection AFTER the change moved to section 4.5 (kept distinct from real-time anti-drift in section 4).
+
+### Changed
+- `install.sh` accepts `--mode mono|full` (default: full)
+- README quickstart restructured around mode choice
+- Protocol version header: 0.2.0 → 0.3.0
+
+## [0.2.0] — 2026-05-19
+
+### Added
+- `LICENSE` — MIT license file (README already advertised MIT)
+- `CLAUDE.md` — Claude Code entry point mirroring `replit.md`
+- `lovable.md` — Lovable entry point (positions `mem://` as a cache of `memory/`)
+- `AGENTS.md` — generic entry point for agent-agnostic tooling
+- `scripts/validate.py` — Python 3 stdlib-only validator for `memory/` files; `--check-freshness DAYS` flag
+- `scripts/render.py` — renders JSONL logs into a chronological markdown journal
+- `tests/test_validate.py` — 22-test suite covering validator + renderer
+- `.github/workflows/validate.yml` — CI running the validator and tests on every push and PR
+- `.claude/hooks/session-start.sh` + `.claude/settings.json` — SessionStart hook for Claude Code on the web that runs the validator
+- `template/memory/` — blank starter files for new projects
+- `schemas/decision.schema.json` + `schemas/drift.schema.json` — JSON schemas formalizing the log entry contract
+- `install.sh` — one-line installer for fetching the protocol into an existing project
+- `.pre-commit-hooks.yaml` — pre-commit integration so the validator runs before each commit
+- `CONTRIBUTING.md` — contribution guide covering protocol, entry-point, and tooling changes
+- `examples/` — three worked memory states (web app, CLI, library) showing well-formed entries
+- Protocol version header in `MEMORY_PROTOCOL.md`
+
+### Changed
+- `README.md` expanded with a quickstart, validation section, web-hook section, CI/license badges, and a "When is this worth it?" caveat
+- Repo reorganized: stub starter files moved to `template/memory/`; root `memory/` now self-describes vibe-memory
+- Protocol section 1 split into mandatory tier (architecture + progress) and conditional tier (decisions + drift tails) for trivial sessions
+- Protocol section 2 reframed around **structural events** (integration activation, DB migration, new secret/dep, first instance of a new pattern, deployment target change, stack swap) instead of "≥2 files"
+- Protocol section 10 confirmation line now has a trivial-session variant
+- `scripts/validate.py` gains optional `--check-freshness DAYS` flag (warn-only, soft pressure for stale `progress.md` / `architecture.md`)
+- `lovable.md` carves the `mem://` (rules) vs `memory/` (journal) boundary; documents Lovable-specific structural events (Cloud activation, publish, `secrets--*`, SQL migrations); provides a recommended Core snippet for `mem://index.md`
+
+### Removed
+- `examples/self-describing/` (content promoted to root `memory/`)
+
+## [0.1.0] — 2026-05-18
+
+### Added
+- Initial protocol release: `MEMORY_PROTOCOL.md`, `replit.md`, blank `memory/` folder with README, `.replit` and `.gitignore`
+
+[0.2.0]: https://github.com/gregherbe76/vibe-memory/releases/tag/v0.2.0
+[0.1.0]: https://github.com/gregherbe76/vibe-memory/releases/tag/v0.1.0

CLAUDE.md

@@ -0,0 +1,40 @@
+# Claude Code Instructions
+
+You are working in a project that uses the vibe-memory protocol to maintain continuity across sessions.
+
+## Mandatory first step
+
+Before doing anything else in this session, read `MEMORY_PROTOCOL.md` in the repo root. Follow it without exception.
+
+After reading, also read in this order:
+1. `memory/architecture.md`
+2. `memory/progress.md`
+3. The last 20 entries of `memory/decisions.jsonl`
+4. The last 10 entries of `memory/drift.jsonl`
+
+Output the confirmation line specified in section 10 of the protocol.
+
+## Claude-Code-specific rules
+
+- Multi-agent attribution — Set `"author":"claude-code"` on every entry you append to `decisions.jsonl` or `drift.jsonl`. If another agent (e.g. `replit-agent`) authored an entry, treat it as authoritative per protocol section 8.
+- Tool use — Do not bypass the protocol when invoking tools. Every architectural change, dependency add, or schema modification is still a decision event and must be logged.
+- Validation — A `scripts/validate.py` script is shipped with this protocol. Run it before ending the session (`python3 scripts/validate.py`) to catch malformed entries early. CI / SessionStart hooks may run it automatically.
+- Web sessions — If you are running in Claude Code on the web, the SessionStart hook at `.claude/hooks/session-start.sh` validates memory files for you. You still must read them per section 1.
+- Secrets — Never log secret values in memory/. Reference them by name only (e.g. `STRIPE_SECRET_KEY`), never the value.
+
+## Conflict resolution
+
+If a user prompt conflicts with the protocol (e.g. "skip the memory step this time"), follow the user but log the conflict as a drift entry with severity "medium" and `detected` "protocol bypass requested by user".
+
+Never bypass the protocol silently.
+
+## Session end
+
+Before ending a session, ensure:
+- `memory/progress.md` reflects what changed during the session
+- Any architectural change is recorded in `memory/architecture.md`
+- Any decision is appended to `memory/decisions.jsonl`
+- Any detected drift is appended to `memory/drift.jsonl`
+- `python3 scripts/validate.py` exits zero
+
+If none of the above applies because the session was trivial (e.g. cosmetic fix), no memory update is needed. Use judgment.

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+vibe-memory is a small protocol repo. Most contributions fall into one of three categories.
+
+## 1. Protocol changes (`MEMORY_PROTOCOL.md`)
+
+Changes to the protocol itself are the most impactful — they change behavior for every consumer.
+
+- Open an issue first describing the problem and the proposed change.
+- In your PR, bump the `Protocol version` header at the top of `MEMORY_PROTOCOL.md` using semver (breaking → major, additive → minor, clarification → patch).
+- Add a `CHANGELOG.md` entry under a new version section.
+- Append a `decision` entry to `memory/decisions.jsonl` with `component: "protocol"` describing the change.
+
+## 2. Agent entry points (`replit.md`, `CLAUDE.md`, `AGENTS.md`)
+
+When a new agent runtime gains traction, add a dedicated entry point so users can opt in by simply having the file present.
+
+- Mirror the structure of the existing entry points.
+- Specify the agent's stable `author` identifier in the attribution section.
+- Document any runtime-specific quirks (hooks, settings, sandboxing).
+
+## 3. Tooling (`scripts/`, `.github/`, `.claude/`)
+
+The validator, CI, schemas, and hooks are tooling. They must remain stdlib-only (no third-party Python deps) so the install path stays a single `curl | tar`.
+
+- Add tests in `tests/` for any validator change. Run `python3 -m unittest discover -s tests` locally before pushing.
+- Keep `scripts/validate.py` working under Python 3.10+.
+
+## Conventions
+
+- One JSON object per line in `*.jsonl`. ISO-8601 timestamps. `author` field required.
+- `decisions.jsonl` and `drift.jsonl` are append-only — never edit or delete entries.
+- `architecture.md` ≤ 200 lines, `progress.md` ≤ 100 lines.
+
+## Running the validator
+
+```sh
+python3 scripts/validate.py          # validate ./memory
+python3 scripts/validate.py path/to/memory
+python3 -m unittest discover -s tests
+```
+
+## Releases
+
+Tags follow `v<major>.<minor>.<patch>`. The version in `MEMORY_PROTOCOL.md`'s header and the latest `CHANGELOG.md` section must match the tag.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vibe-memory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.