membrane-cli 0.4.0

Schema-optional, file-based project memory system
membrane-cli-0.4.0 is not a library.

Membrane is a schema-optional, file-based project memory system.

It lets you name projects, attach arbitrary keys, and observe how language emerges across your work — without enforcing structure, schemas, or workflows.

Membrane is not a task manager, calendar, or ticketing system.
It sits above those tools, acting as a lightweight semantic layer over your projects.

Why Membrane?

Most project tools fail in one of two ways:

  • They are too rigid (fixed fields, schemas, workflows)
  • Or too vague (notes with no structure at all)

Membrane takes a different approach:

  • Projects are files
  • Keys are language artifacts
  • Structure is allowed to emerge organically
  • Metadata exists, but stays out of the way

You decide what matters. Membrane just remembers it.

Core Concepts

  • Workspace-based (globally staged)
    A Membrane workspace ("brane") lives in a .membrane/ directory and can be staged globally for use from anywhere on your system.

  • Global workspace registry
    Membrane maintains a lightweight global index of known workspaces and tracks which one is currently active.

  • Explicit workspace switching
    Commands operate on the active workspace, not the current directory.

  • Projects are YAML files
    Each project is a single, human-readable YAML file.

  • Schema-less by design
    Projects can contain any keys. No required fields.

  • Stable project identity
    Each project is assigned a unique internal ID, allowing projects to be referenced by name or by ID prefix.

  • Keys are first-class
    Keys can be added, renamed, deleted, and inspected across projects.

  • Metadata is explicit
    Reserved keys (prefixed with _) track creation and update times without polluting user-defined structure.

Installation

cargo install membrane-cli

This installs the me command.

Getting Started

Initialize a workspace

me init

Creates a .membrane/ directory in the current folder and assigns it a stable workspace ID.

Register and inspect workspaces

me brane

Lists all known Membrane workspaces ("Branes") on your system. The active workspace is marked with *.

Switch active workspace

me checkout <id-prefix>

Switches the active workspace using a leading ID prefix (similar to git checkout).

Once switched, all commands operate on the active workspace regardless of your current directory.

Working with Projects

Create a project

me add my-project

Creates a new project file with basic metadata.

List projects

me show

Displays all projects in the active workspace.

Each project is shown with its short ID for quick reference.

Filtered and printable views

me show --sort status
me show --sort status --only
  • --sort <key> orders projects by a given key
  • --only hides projects that do not define the sorted key

This allows focused views without placeholder entries.

Show a project

me show my-project
me show a43b21

Displays all keys and values for the project. Projects can be referenced by name or by ID prefix.

Metadata keys (prefixed with _) are visually dimmed.

Sort projects by a key

me show --sort status
me show --sort _updated --desc

When sorting is enabled, the selected key and its value are shown inline for each project (when present).

Export project views (printable)

me show --printed
me show --sort status --only --printed

  • --printed exports the current view to a clean markdown file

  • Output is written to BRANE_<id>.md

  • The export includes:

    • Active workspace context
    • Project index (respecting --sort and --only)
    • Full contents of each listed project

Printed output is ANSI-free and suitable for version control or sharing.

Set a key

me set my-project description "Initial prototype"

Values are parsed as YAML scalars when possible.

Set a multi-line value (interactive)

me set my-project notes

You’ll be prompted to paste or type content directly into the terminal. Finish with Ctrl+D (Linux/macOS) or Ctrl+Z + Enter (Windows).

Push a project from YAML

me push roadmap.yaml

Or interactively:

me push

Paste YAML content directly into the terminal to create a project. An ID is automatically assigned if one is not present.

Inspect keys across projects

me keys

Lists all keys and how frequently they appear.

me keys --similar

Highlights near-duplicate keys (e.g. created_at vs created-at).

Rename a key

me keys rename old_key new_key
me keys rename status phase --project my-project

Delete a project (safe)

me rm my-project

You’ll be asked to confirm by typing the project name.

Philosophy

Membrane is intentionally minimal.

It does not:

  • enforce schemas
  • impose workflows
  • sync to the cloud
  • track tasks or deadlines
  • automate decisions

Instead, it provides a durable, inspectable memory layer that you can reason about over time.

Versioning

Membrane follows semantic versioning.

  • 0.1.x establishes the conceptual and architectural core.
  • 0.2.x adds inspection, mutation, and sorting capabilities.
  • 0.3.x introduces globally staged workspaces and explicit workspace switching.
  • 0.4.x adds printable views and key-aware filtering.
  • Future versions will extend views and navigation

License

MIT