# Memory Lifecycle

Manage note status transitions in Basic Memory: archive completed work, move notes...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Writing
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add basicmachines-co/basic-memory --skill memory-lifecycle -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill memory-lifecycle -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill memory-lifecycle -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill memory-lifecycle -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

Manage note status transitions in Basic Memory: archive completed work, move notes between status folders, update frontmatter. Use when marking items complete or archiving entities.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Memory Lifecycle

Manage how entities move through status stages in Basic Memory. The core principle: **archive, never delete.** Completed work is valuable context, move it out of the active view, but keep it in the knowledge graph.

## Project scope

If the project is unknown, discover it with `bm_project(command="list")`.
Pass a nonempty `project` on every note, folder, context and schema call, even
with one project or a qualified `memory://` URL. Use the chosen project's name,
`workspace/project`, or external ID; `<project>` below is a placeholder for it.
Recent activity also requires `project`. Search accepts `project` for one
project, `projects` for selected projects, or `all_projects=True` explicitly.
Discovery and bundled manuals need no project. Keep the same scope when following
returned paths, paginating, or recovering from a refusal.

## When to Use

- User says something is "done", "finished", "completed", "submitted", "missed", or "cancelled"
- Moving entities between status folders (active → archive, pipeline → active, etc.)
- Reverting a mistaken completion
- Periodic cleanup of stale active items

## Core Principle: Archive, Never Delete

Deleting a note removes it from the knowledge graph, its observations and relations disappear, and links to it from other notes become unresolved links. Archiving preserves everything while signaling the entity is no longer active.

```
# Good, entity stays in the knowledge graph
bm_move → active/ to archive/

# Bad, knowledge is lost
bm_delete
```

The only exception: notes created by mistake (typos, true duplicates) can be deleted.

## Folder Conventions

Organize entities by status using folders. The exact folder names depend on your domain, but follow a consistent pattern:

```
entities/
  active/          # Currently relevant, in-progress
  archive/         # Completed, no longer active, but worth keeping
  pipeline/        # Future items, not yet started
```

For tasks specifically:

The rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/skills/memory-lifecycle/SKILL.md