Metadata-Version: 2.4
Name: vibe-memory
Version: 0.1.2
Summary: Portable project memory for coding agents across Codex, Claude Code, Cursor, OpenCode, and MCP clients.
Requires-Python: >=3.11
Requires-Dist: mcp[cli]<2,>=1
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.16
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

Each card is a Markdown document with YAML frontmatter:

```md
---
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

```bash
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:

```bash
pipx install vibe-memory
```

or:

```bash
uv tool install vibe-memory
```

Then in any repository:

```bash
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:

```bash
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:

```bash
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.
