viberr 0.2.0

Lightweight local memory for vibe coding: prompts, edits, conflicts, decisions, AI feedback

Viberr

Lightweight local memory for vibe coding. Cursor hooks write prompts, edits, conflicts, decisions, tool calls, and test outcomes to a single readable log. A small CLI helps you browse, search, recap, and feed that memory back to the AI.

No server. No dashboard. No accounts.

What it solves

• Prompt amnesia — every prompt, response preview, and AI tool call — timestamped
• File-change provenance — which prompt caused which edit (with diff, language, hunks)
• AI vs manual — edits you make yourself are tagged source: manual
• Conflicting AI edits — overlapping line ranges from different prompts
• Decision tracking — extracts "use X", "never Y" and flags contradictions
• Session recap — viberr recap → markdown summary of everything that happened
• Full-text search — viberr search "JWT" across prompts, diffs, and commands
• Feeding memory back — viberr context | pbcopy → paste into next chat; viberr rules sync → auto-update Cursor rules

Requirements

• Python 3.10+
• Git (a git repo is required — viberr init will tell you if one is missing)
• Cursor IDE with hooks enabled (Settings → Features → Hooks)
  • Minimum Cursor version: any build that ships hooks.json support (≥ 0.42)

Other editors (experimental): Adapter stubs for Claude Code, Aider, Cline, and Windsurf are included. See docs/adapters.md for setup.

Quick start

# Recommended: global install via pipx
pipx install viberr

# Or per-project:
pip install viberr

cd your-git-repo
viberr init

Use Cursor in that workspace. Events append to .viberr/events.ndjson automatically.

Feeding memory back to the AI

The key workflow viberr enables is a memory loop:

# Before your next chat session — paste into Cursor:
viberr context | pbcopy

# Auto-sync decisions to .cursor/rules/:
viberr rules sync

# Generate AGENTS.md from observed conventions:
viberr agents-md > AGENTS.md

Commands

Command	Description
viberr init [--editor cursor|claude-code|aider]	Git check, .viberr/, merge hooks, .gitignore
viberr status	Active session, branch, today's counts, last test result
viberr log [--format pretty|json]	Print events (--type, --tail, --since 1h)
viberr show <id>	Full event JSON
viberr diff <id>	Pretty-print diff from an edit event
viberr search <query>	Search events (--regex, --type, --file, --since)
viberr recap [--full] [--include-diffs]	Markdown session summary
viberr conflicts	List conflict events
viberr decisions	List decision events
viberr tail [--type edit]	Follow the log live
viberr export	Export session (--format md|json|ndjson)
viberr doctor	Verify git, hooks, interpreter path, log size
viberr blame <file>:<line>	Which prompt last touched this line?
viberr file <path>	Full timeline for a single file
viberr today	What did you do today?
viberr stats	Global numbers + Unicode sparklines
viberr open <id>	Open file from event in $EDITOR
viberr context [--since 7d] [--file src/auth.py]	Paste-ready memory block
viberr rules sync [--watch]	Sync decisions to .cursor/rules/viberr.mdc
viberr agents-md	Generate AGENTS.md from observed conventions
viberr report [--open]	HTML dashboard in .viberr/report.html
viberr learn [--llm ollama]	Heuristic distillation → .viberr/memory.md
viberr config get|set <key> <value>	Read/write config values
viberr prune [--before 30d]	Remove old events (archives first)
viberr uninstall [--remove-data]	Remove hooks, optionally data
viberr scrub --check <file>	Dry-run scrubber on a file
viberr privacy-report	Report on all redactions in the log
viberr pr-summary	Generate PR body from current work session
viberr install-git-hook	Install prepare-commit-msg trailer hook

What you'll see in viberr status

Events file:        /your/project/.viberr/events.ndjson (42 KB)
Total events:       142
Active conversation:sess_a1b2c3
Branch:             feature/auth-refactor (dirty)
Latest work session:work_3 (2 conversation(s))
Last AI activity:   2026-05-20 08:30:11 UTC
Today's prompts:    7
Today's decisions:  3
Open conflicts:     1
Last test run:      pytest PASS (12 passed, 0 failed)

How it works

flowchart LR
    Cursor[Cursor IDE] -->|hooks| Hook[viberr.hook]
    Hook --> Log[".viberr/events.ndjson"]
    Hook --> State[".viberr/state.json"]
    Hook --> Parsers["shell parsers\n(tests/lint/git)"]

    Log --> CLI[viberr CLI]
    Log --> Context["viberr context"]
    Log --> Rules[".cursor/rules/viberr.mdc"]
    Log --> Report[".viberr/report.html"]
    Log --> MCP["viberr-mcp"]

    Context --> Cursor
    Rules --> Cursor
    MCP --> Cursor

See docs/schema.md for the full event format and docs/how-to-use.md for a complete walkthrough of every command.

Privacy

All data stays on your machine under .viberr/. viberr init adds .viberr/ to .gitignore.

Secret scrubbing is on by default. Common credential patterns (API keys, tokens, passwords) are redacted with [REDACTED] before reaching disk. See docs/privacy.md for full details.

Disable in .viberr/config.json:

{ "privacy": { "scrub_secrets": false } }

Custom scrub patterns and per-path exclusions:

{
  "privacy": {
    "custom_patterns": ["my-corp-token-[A-Z0-9]{16}"],
    "exclude_paths": [".env", "**/secrets/**"]
  }
}

Configuration

{
  "decisions": { "enabled": true, "scan_responses": false },
  "work_session": { "idle_minutes": 30 },
  "privacy": { "scrub_secrets": true, "custom_patterns": [], "exclude_paths": [] },
  "rules": { "auto_sync": false }
}

Or use the CLI:

viberr config set rules.auto_sync true
viberr config set work_session.idle_minutes 45

MCP server (optional)

pip install "viberr[mcp]"

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "viberr": { "command": "viberr-mcp" } } }

Tools: get_decisions, get_recent_edits, get_conflicts, search, recap, context.

Development

pip install -e ".[dev]"
pytest -q
ruff check viberr/ tests/
ruff format --check viberr/ tests/

History

Earlier internal prototypes used a FastAPI daemon, SQLite, and a VS Code extension. v0.1 stripped all of that back to a zero-dependency, hooks-only design. v0.2 adds the memory feedback loop: viberr context, viberr rules sync, viberr agents-md, an MCP server, richer event captures (tool calls, test/lint/git parsing), and a full CLI expansion.

License

MIT