| name | papyrus-write |
| description | Atomic — write a single new memory to a workspace |
papyrus-write
Persist one memory record. Single atomic append.
Atomicity
- (a) Indivisible: one Need → one RST directive appended → filelocked
- (b) Input: type, title, body, tags, confidence, scope, links, source, id?. Output: created need (via backend.append_need) or ValueError on duplicate id
- (c) Objective reward:
backend.find_by_id(id) is not None AND need content matches input
- (d) Reusable: every capture flow invokes this once per memory
- (e) No interference: filelock serialises writes; no shared in-memory state
Input / Output
input:
type: NeedType enum value (mem|dec|fact|pref|risk|goal|q)
title: non-empty string
body: string (default "")
tags: list[str] (topic:X / scope:Y convention)
confidence: low|medium|high (default medium)
scope: local|program|org (default local)
links: list of {type: LinkType, target: need_id}
source: string (default "")
id: optional override; else auto from title
output:
side effect: append directive to memory/<plural>.rst
stdout: "Added <id> to <scope>"
exit: 0 on success; non-zero on duplicate id or validation error
Success criterion
papyrus get <id>
Workflow
papyrus add <type> "<title>" \
--body "<body>" \
--tags "topic:X,topic:Y" \
--confidence <low|medium|high> \
--scope <local|program|org> \
--relates <other_id>
MCP tool memory_add:
{"type": "dec", "title": "...", "body": "...", "tags": [...], "confidence": "high"}
Composition examples
Authored capture (composition with shared/when-to-capture.md judgment):
- Consult when-to-capture filter → pass/skip
- If pass:
papyrus-write
Capture + link (most common flow):
papyrus-write new DEC/RISK/FACT
papyrus-link from the new id to the requirement or parent decision it's about
Capture + promote (cross-skill composition):
papyrus-write at scope=local, confidence=medium
- Verify fact
papyrus-update-metadata set confidence=high
papyrus-promote --to program
Deprecate + replace:
papyrus-write new version
papyrus-deprecate old version with by=<new_id>
See also
shared/memory-types.md — choosing type
shared/link-types.md — choosing link types and when to link during capture
shared/when-to-capture.md — subjective filter BEFORE invoking
papyrus-link — atomic skill to add a link after writing