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.

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
move_note → active/ to archive/

# Bad — knowledge is lost
delete_note

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:

tasks/
  active/          # Work in progress
  completed/       # Finished work

For any entity type with a clear lifecycle:

[type]/
  active/          # Current
  [end-state]/     # Whatever "done" means for this type

Pick folder names that match your domain. The pattern matters more than the specific names.

Status Detection

When the user mentions completion or status change, extract the intent:

Signal	Status	Action
"finished", "done", "completed", "shipped"	Complete	Move to archive/completed folder
"submitted", "sent", "delivered"	Complete	Move to archive/completed folder
"missed", "passed", "skipped", "expired"	Missed	Move to archive or missed folder
"cancelled", "abandoned", "killed"	Cancelled	Move to archive folder
"paused", "on hold", "deferred"	Paused	Update frontmatter status, keep in place
"restarting", "reopening", "reviving"	Reactivate	Move back to active folder

Workflow

1. Find the Entity

Search Basic Memory with multiple variations to locate the entity:

search_notes(query="quarterly report")
search_notes(query="Q1 report")

If multiple matches come back, present options and ask which one.

If no match is found, ask for clarification — don't guess.

2. Move the File

Use move_note to relocate the entity to the appropriate status folder:

move_note(
  identifier="tasks/active/quarterly-report",
  destination_path="tasks/completed/quarterly-report.md"
)

By default the permalink stays the same after a move, so links keep resolving. Projects with update_permalinks_on_move enabled rewrite it from the new path.

3. Update Frontmatter

After moving, merge the new status (and completion date, if the type tracks one) into frontmatter with the metadata parameter. An append with empty content changes only the frontmatter:

edit_note(
  identifier="quarterly-report",
  operation="append",
  content="",
  metadata={"status": "completed", "completed": "2026-02-22"}
)

If the note also carries a - [status] observation, update it too (for example with find_replace on - [status] active).

4. Confirm

Report what was done concisely:

Marked complete: Quarterly Report
  Moved to: tasks/completed/quarterly-report.md

## Edge Cases

### Already Archived

If the entity is already in an archive/completed folder, notify the user:

> "Quarterly Report is already in tasks/completed/. Want me to update anything on it?"

### Partial Completion

Sometimes only part of an entity is done. Don't move it — instead, update observations or status notes within the entity to reflect partial progress.

### Locked Notes

A note with `locked: true` in its frontmatter still moves, and keeps its lock,
but the status edit in step 3 is refused. Report that it moved and that its
status is unchanged. Only the user can unlock it, by editing the file.

### Revert / Reactivate

If something was archived by mistake, move it back:

```python
move_note(
  identifier="tasks/completed/quarterly-report",
  destination_path="tasks/active/quarterly-report.md"
)

edit_note(
  identifier="quarterly-report",
  operation="append",
  content="",
  metadata={"status": "active"}
)