Vibe Memory

Vibe Memory stores shared project memory in a neutral .memory/ directory and serves it through both a CLI and an MCP server. The canonical source of truth is a set of Markdown cards with YAML frontmatter. Agent-specific files are generated views under .memory/dist/. End-of-task memory maintenance happens through proposal batches under .memory/proposals/.

Requires Python 3.11 or newer.

Install once globally, then use it in any repository root, similar to how you use git. The target repository does not need to be a Python project.

Why

• Keep architecture notes, patterns, commands, pitfalls, and conventions portable.
• Generate Codex, Claude Code, Cursor, and OpenCode-friendly outputs from one model.
• Offer a read-only MCP surface for tools that can fetch context dynamically.

Canonical Layout

.memory/
  memory.yaml
  cards/
    architecture.md
    ...
  index.sqlite
  proposals/
  dist/

Each card is a Markdown document with YAML frontmatter:

---
id: architecture-overview
title: Architecture overview
kind: architecture
summary: High-level system shape
paths: []
tags: [architecture, backend]
priority: 100
updated_at: 2026-03-07T00:00:00Z
targets: [codex, claude, cursor, opencode, generic]
status: active
supersedes: []
---
The API server is the source of truth for writes.

Commands

memory init
memory bootstrap --workspace-id my-project
memory add "Architecture overview" --kind architecture --summary "High-level notes" --body "..."
memory validate
memory list
memory search architecture
memory render codex
memory render claude --format dist
memory suggest-updates --changed-paths "src/api/routes.py" --task-summary "API validation" --implementation-summary "Validate before DB writes"
memory proposals list
memory proposals show <proposal-id>
memory proposals apply <proposal-id>
memory proposals reject <proposal-id>
memory curate --changed-paths "src/api/routes.py" --task-summary "API validation" --implementation-summary "Validate before DB writes" --confirm-apply
memory serve-mcp
memory doctor

Install And Use

Global install is the primary workflow:

pipx install vibe-memory

or:

uv tool install vibe-memory

Then in any repository:

cd /path/to/any-repo
memory init --workspace-id my-project

This works for:

• Python projects
• Node/TypeScript projects
• Go/Rust/Java projects
• mixed or non-Python repos

The only requirement is that the machine running memory has Python available, because distribution is still Python-package based today.

Project-local install is still supported when a team wants per-repo version pinning:

cd /path/to/repo
uv add vibe-memory
uv run memory init --workspace-id my-project

For MCP clients:

• if vibe-memory is installed in the current project, register uv run --project "$PROJECT_ROOT" memory serve-mcp --root "$PROJECT_ROOT"
• if vibe-memory is installed globally, register memory serve-mcp --root "$PROJECT_ROOT"
• do not register a repo-local launcher script unless that script exists in the target project

Indexed Query Model

The official indexed query surfaces are:

• CLI: memory search, memory list, memory show
• MCP: memory.search, memory.list_cards, memory.get_card, memory.get_context

These use .memory/index.sqlite as a derived query engine for fast retrieval. The canonical durable memory still lives in .memory/cards/*.md.

Examples:

memory search "validation"
memory search "database" --paths "src/api/routes.py"
memory list --path "src/api/routes.py"
memory show architecture-overview

MCP examples:

• memory.search(query="validation", paths=["src/api/routes.py"])
• memory.list_cards(path="src/api/routes.py", view="short")
• memory.get_card(card_id="architecture-overview")
• memory.get_context(paths=["src/api/routes.py"])

Release Automation

GitHub Actions workflows live under .github/workflows/:

• ci.yml runs tests and builds distributions on pushes to main and pull requests.
• publish-testpypi.yml publishes to TestPyPI when triggered manually from GitHub Actions.
• publish-pypi.yml publishes to PyPI when a GitHub Release is published.

These publish workflows are configured for trusted publishing. Before the first release, register this GitHub repository as a trusted publisher in both PyPI and TestPyPI for the vibe-memory project and create matching GitHub Environments named pypi and testpypi.

Notes

• .memory/index.sqlite is rebuildable and should not be treated as source of truth.
• .memory/index.sqlite is the derived search/query index used by both CLI and MCP retrieval surfaces.
• .memory/proposals/*.yaml stores pending/applied/rejected/expired proposal batches.
• Native files such as AGENTS.md, CLAUDE.md, and Cursor rules should stay thin and procedural. They should tell agents when to fetch memory, not duplicate the full memory corpus.
• Use memory init for a new/blank project and memory bootstrap for an existing repo with docs or agent rule files.
• v1 writes generated outputs only under .memory/dist/.
• Root files like AGENTS.md, CLAUDE.md, .cursor/rules, and .opencode/* are never modified automatically.
• Deprecated cards remain in canonical memory for history but are hidden from search, list, and render output by default.
• Proposal application now includes revision checks, so stale approvals cannot overwrite cards that changed after proposal creation.
• See docs/DESIGN_CRITIQUE.md for the recommended precedence model between native tool files, MCP retrieval, and canonical cards.