Resources
scripts/
validate-memory-usage.sh
references/
schemas.md
GoodVibes Memory Protocol
The memory system enables cross-session learning by capturing decisions, patterns, failures, and preferences in structured JSON files. Every agent must read memory before starting work and write to it after completing work.
Why This Matters
Without memory:
Agents repeat known failures
Proven patterns are rediscovered each session
Architectural decisions are forgotten or violated
Project-specific preferences aren't applied
With memory:
Failures are logged with prevention strategies
Patterns are reused consistently
Decisions guide future work
Preferences ensure consistency
File Structure
.goodvibes/
|-- memory/ # Structured JSON (machine-readable)
| |-- decisions.json # Architectural decisions
| |-- patterns.json # Proven approaches
| |-- failures.json # Past errors + resolutions
| |-- preferences.json # Project conventions
| +-- index.json # Index file (optional)
+-- logs/ # Markdown logs (human-readable)
|-- activity.md # Completed work log
|-- decisions.md # Decision log with context
+-- errors.md # Error log with resolution
BEFORE Starting Work (Read Phase)
Always check memory files before implementing ANY task. Use keyword-based searches to find relevant entries.
1. Check
failures.json
Purpose: Avoid repeating known failures. How :

Use precision_read to read the file

precision_read : files : - path : .goodvibes/memory/failures.json verbosity : standard

Search for keywords matching your task

Example keywords: "precision_fetch", "config", "auth", "API", "build"

What to look for

:

keywords

field matches your task (e.g., searching for "auth" finds authentication failures)

error

field describes a similar problem

context

field matches your current situation

If found

:

Read

resolution

-- how was it fixed?

Read

prevention

-- how to avoid it?

Apply the prevention strategy

2. Check

patterns.json

Purpose

Use proven approaches instead of inventing new ones.

How

:

precision_read

:

files

:

-

path

:

.goodvibes/memory/patterns.json

verbosity

:

standard

What to look for

:

keywords

matches your task type

when_to_use

describes your situation

name

suggests a relevant pattern

If found

:

Read

description

-- what's the pattern?

Check

example_files

-- where is it used?

Follow the pattern unless there's a compelling reason not to

3. Check

decisions.json

Purpose

Respect prior architectural decisions.

How

:

precision_read

:

files

:

-

path

:

.goodvibes/memory/decisions.json

verbosity

:

standard

What to look for

:

scope

includes files you'll modify

category

matches your domain (e.g., "architecture", "pattern", "library")

status

is "active" (not "superseded" or "reverted")

If found

:

Read

what

and

why

-- understand the decision

If your task conflicts with the decision: flag to orchestrator before proceeding

If your task aligns with the decision: follow it

4. Check

preferences.json

Purpose

Apply project-specific conventions.

How

:

precision_read

:

files

:

-

path

:

.goodvibes/memory/preferences.json

verbosity

:

standard

What to look for

:

key

matches your domain (e.g., "category.preference_name")

If found

:

Apply the

value

preference

Respect the

reason

rationale

Search Strategy

Manual keyword matching

Read the file and scan for keywords related to your task.
Example
:
Task: "Add authentication with Clerk"
Keywords to search:
auth
,
clerk
,
authentication
,
login
,
session
Check
failures.json
for past auth failures
Check
patterns.json
for auth patterns
Check
decisions.json
for auth library decisions
Scope filtering: Focus on entries where scope includes files you'll modify. AFTER Completing Work (Write Phase) Log to memory after completing a task, resolving an error, or making a decision. Always write to BOTH JSON (machine-readable) and Markdown (human-readable). When to Write Situation Write to Task passes review activity.md + optionally patterns.json / decisions.json Error resolved errors.md + failures.json Decision made decisions.md + decisions.json Never write Trivial fixes, no new patterns, no decisions After Task Passes Review 1. Always log to activity.md Format:

YYYY-MM-DD: [Brief Title]

Task

[What was the goal?]

Plan

[Approach taken, or N/A]

Status

COMPLETE

Completed Items

:

-

[List of what was accomplished]

Files Modified

:

-

[List of changed files with brief description]

Review Score

[X/10]
**
Commit
**: [commit SHA]

Optionally add to patterns.json (if a reusable pattern emerged) Only add if: The approach is reusable across multiple files/tasks It's non-obvious (not standard practice) It solves a specific problem well Schema: { "id" : "pat_YYYYMMDD_HHMMSS" , "name" : "PatternNameInPascalCase" , "description" : "What the pattern does and why it works" , "when_to_use" : "Situation where this pattern applies" , "example_files" : [ "path/to/file.ts" , "another/example.ts" ] , "keywords" : [ "searchable" , "terms" ] }
Optionally add to decisions.json (if an architectural decision was made) Only add if: A choice was made between multiple approaches The decision affects future work It has scope beyond this single task Schema: { "id" : "dec_YYYYMMDD_HHMMSS" , "date" : "YYYY-MM-DDTHH:MM:SSZ" , "category" : "library|architecture|pattern|convention" , "what" : "What was decided" , "why" : "Rationale for the decision" , "scope" : [ "files/directories affected" ] , "confidence" : "high | medium | low" , "status" : "active|superseded|reverted" } After Error Resolved
Always log to errors.md Format:

YYYY-MM-DD HH:MM - [ERROR_CATEGORY]

Error

[Brief description]

Context

:

-

Task: [What were you doing?]

-

Agent: [Which agent encountered it?]

-

File(s): [Affected files]

Root Cause

[Why did it happen?]

Resolution

[How was it fixed? Or UNRESOLVED]

Prevention

[How to avoid it in the future?]
**
Status
**: RESOLVED | UNRESOLVED

Always add to failures.json (with full context) Schema: { "id" : "fail_YYYYMMDD_HHMMSS" , "date" : "YYYY-MM-DDTHH:MM:SSZ" , "error" : "Brief error description" , "context" : "What task was being performed" , "root_cause" : "Technical explanation of why it failed" , "resolution" : "How it was fixed (or UNRESOLVED)" , "prevention" : "How to avoid this failure in the future" , "keywords" : [ "searchable" , "error-related" , "terms" ] } Error categories (for errors.md ): TOOL_FAILURE -- Precision tool or native tool failed AGENT_FAILURE -- Agent crashed or failed to complete task BUILD_ERROR -- TypeScript compilation, build step failed TEST_FAILURE -- Test suite failed VALIDATION_ERROR -- Validation, linting, or format checking failed EXTERNAL_ERROR -- API, network, dependency issue UNKNOWN -- Error category could not be determined After Decision Made
Always log to decisions.md Format:

YYYY-MM-DD: [Decision Title]

Context

[What situation required a decision?]

Options Considered

:

1.

[Option A]

[Description + trade-offs]

2.

[Option B]

[Description + trade-offs]

Decision

[What was chosen]

Rationale

[Why this option was best]
**
Implications
**: [What this means for future work]

Always add to

decisions.json

See schema in "After Task Passes Review" section above.

ID Format

Use timestamp-based IDs to avoid needing to read existing entries before writing:

dec_YYYYMMDD_HHMMSS # Decisions

pat_YYYYMMDD_HHMMSS # Patterns

fail_YYYYMMDD_HHMMSS # Failures

pref_YYYYMMDD_HHMMSS # Preferences

Example

:

dec_20260215_143022

for a decision made on 2026-02-15 at 14:30:22

Collision risk

Negligible unless two agents write to the same file in the same second. The timestamp provides sufficient uniqueness. First Write Check Before first write to any memory/log file, check if it exists: For JSON files If file doesn't exist, create with bare array: [ ] For Markdown files If file doesn't exist, create with header:

[File Name] Log of [description].

Use precision_read first : precision_read : files : - path : .goodvibes/memory/decisions.json verbosity : count_only

Just check existence

If exists: false , create the file before appending. Common Mistakes Don't Do This Don't skip reading memory -- You'll repeat failures and violate decisions Don't write for trivial work -- Only log meaningful patterns/decisions/failures Don't use random IDs -- Use timestamp-based IDs (no need to read existing entries) Don't forget prevention field -- Failures without prevention strategies aren't useful Don't log to JSON only -- Always write to BOTH JSON and Markdown Don't create duplicate entries -- Search keywords first to check if pattern/failure already exists Do This Do read failures.json first -- Check for known issues before starting Do search by keywords -- Manual keyword matching is fast and effective Do include full context -- Root cause + resolution + prevention for failures Do use timestamp IDs -- No collision risk, no need to read existing entries Do log to both formats -- JSON for machines, Markdown for humans Do update last_updated -- Update timestamp when modifying index.json Validation Use the scripts/validate-memory-usage.sh script to verify compliance:

Validate memory protocol usage

bash plugins/goodvibes/skills/protocol/goodvibes-memory/scripts/validate-memory-usage.sh \ session-transcript.jsonl \ .goodvibes/memory/

Exit code 0 = compliant

Exit code 1 = violations found

The script checks: Memory files read at task start Activity logged after task completion Failures logged when errors resolved Patterns logged when reusable approaches discovered Quick Reference Read Phase Checklist Read failures.json -- keyword search for similar errors Read patterns.json -- keyword search for proven approaches Read decisions.json -- scope search for relevant decisions Read preferences.json -- apply project conventions Write Phase Checklist Log to activity.md after task completion Add to patterns.json if reusable pattern discovered Add to decisions.json if architectural decision made Log to errors.md + failures.json if error resolved Log to decisions.md + decisions.json if choice made Update last_updated timestamp in JSON files Use timestamp-based IDs (no collisions) Examples Example: Reading Failures Before Starting Auth Task

Step 1: Read failures.json

precision_read : files : - path : .goodvibes/memory/failures.json verbosity : standard

Step 2: Manually search for keywords

Keywords: "auth", "authentication", "clerk", "oauth", "token"

Found: fail_20260210_160000 - "Service registry reads empty services"

Context: OAuth token configuration issue

Prevention: "Always use nested config format for services"

Step 3: Apply prevention strategy

Use nested format when configuring auth service

Example: Writing Pattern After Implementing Feature

Step 1: Check if file exists

precision_read : files : - path : .goodvibes/memory/patterns.json verbosity : count_only

Step 2: Read existing patterns to avoid duplicates

precision_read : files : - path : .goodvibes/memory/patterns.json verbosity : standard

Step 3: Add new pattern (if not duplicate)

precision_edit : files : - path : .goodvibes/memory/patterns.json operations : - type : insert search : '"patterns": [' content : | { "id": "pat_20260215_143022", "name": "AuthServiceNesting", "description": "Auth services require nested config structure", "when_to_use": "When configuring auth providers in goodvibes.json", "example_files": [".goodvibes/goodvibes.json"], "keywords": ["auth", "config", "nested", "services"] }, Example: Logging Error Resolution

Step 1: Log to errors.md

precision_edit : files : - path : .goodvibes/logs/errors.md operations : - type : insert_at_line line : 1 content : |

2026-02-15 14:30 - BUILD_ERROR

Error: TypeScript compilation failed with "Cannot find module 'clerk'" Context: - Task : Add Clerk authentication - Agent : Engineer - File(s) : src/auth/clerk.ts Root Cause : Missing @clerk/nextjs package in dependencies Resolution: RESOLVED - Added package with npm install @clerk/nextjs Prevention: Always check package.json before importing new libraries Status: RESOLVED

Step 2: Add to failures.json

precision_edit

:

files

:

-

path

:

.goodvibes/memory/failures.json

operations

:

-

type

:

insert

search

:

'['

content

:

|

{

"id": "fail_20260215_143022",

"date": "2026-02-15T14:30:22Z",

"error": "TypeScript compilation failed - Cannot find module 'clerk'",

"context": "Adding Clerk authentication to Next.js app",

"root_cause": "Missing @clerk/nextjs package in package.json dependencies",

"resolution": "RESOLVED - Installed package with npm install @clerk/nextjs",

"prevention": "Before importing from a new package, verify it exists in package.json. Use precision_read to check package.json before adding imports.",

"keywords": ["typescript", "clerk", "module", "dependency", "package.json", "build-error"]

},

Integration with Other Skills

precision-mastery

Use precision_read/precision_edit for memory file operations

error-recovery

Check failures.json as first step in error recovery

gather-plan-apply

Include memory read in discovery phase
review-scoring: Reviewers check if memory was consulted before work started File Location All memory files are relative to project root: .goodvibes/ |-- memory/ | |-- decisions.json | |-- patterns.json | |-- failures.json | +-- preferences.json +-- logs/ |-- activity.md |-- decisions.md +-- errors.md Always use .goodvibes/memory/ and .goodvibes/logs/ as paths (relative to project root).

安装

Use precision_read to read the file

Search for keywords matching your task

Example keywords: "precision_fetch", "config", "auth", "API", "build"

Just check existence

Validate memory protocol usage

Exit code 0 = compliant

Exit code 1 = violations found

Step 1: Read failures.json

Step 2: Manually search for keywords

Keywords: "auth", "authentication", "clerk", "oauth", "token"

Found: fail_20260210_160000 - "Service registry reads empty services"

Context: OAuth token configuration issue

Prevention: "Always use nested config format for services"

Step 3: Apply prevention strategy

Use nested format when configuring auth service

Step 1: Check if file exists

Step 2: Read existing patterns to avoid duplicates

Step 3: Add new pattern (if not duplicate)

Step 1: Log to errors.md

2026-02-15 14:30 - BUILD_ERROR

Step 2: Add to failures.json