Skip to content

Latest commit

 

History

History
250 lines (191 loc) · 8.4 KB

memory.md

File metadata and controls

250 lines (191 loc) · 8.4 KB
sidebar_position 2
title memory

atomic memory

Record durable, searchable knowledge — decisions, lessons, constraints, preferences, and context — as attestable memory records. atomic memory is the memory analogue of atomic intent: it scaffolds a memory, gates it against the canonical shapes, signs (attests) it, and renders it.

Memories keep the signal-to-noise ratio high: a durable insight from a session (why an approach was chosen, a corrective lesson, a discovered constraint) is captured once, linked to its source, and becomes queryable through the knowledge graph.

Synopsis

atomic memory new --kind <KIND> [OPTIONS]
atomic memory show <ID> [--json]
atomic memory validate <ID_OR_PATH> [--json]
atomic memory attest <ID> [--identity <IDENTITY>] [--json]
atomic memory verify <ID> [--identity <IDENTITY>]
atomic memory list [--limit <N>] [--identity <IDENTITY>] [--sort <KEY>] [-r] [--json]
atomic memory kinds [--json]
atomic memory write <NAME> [--type <TYPE>]

Memory kinds

Every canonical memory is classified into one kind from a closed vocabulary. Pick the kind that fits the insight — a single turn may yield several (a decision and a lesson), so record one memory per insight.

Kind Use for
decision A durable decision→outcome record: the chosen approach and why (typically emitted at turn end).
lesson A corrective lesson learned from something that went wrong.
constraint A rule or limitation discovered that future work must respect.
preference A durable preference (style, tooling, workflow).
context Durable background context that isn't a decision, lesson, or rule.

Run atomic memory kinds to print the vocabulary (add --json for a machine list of {"kind","description"} objects).

new vs write

Atomic offers two ways to store a memory:

  • atomic memory new — authors a canonical, attestable memory with a structured frontmatter spine and a :::memory body. Use this for durable knowledge you want gated, signed, and linked into the graph.
  • atomic memory write — the raw escape hatch. Stores arbitrary content from stdin at memory/<name>.md with simple {name,type} frontmatter. Use this for freeform notes that don't need attestation.

Recording a decision at turn end

# 1. Create the memory (non-interactive), linked to its source
ID=$(atomic memory new --kind decision \
  --text "Chose readline over a full TUI: smaller dep surface, EOF handled by close handler" \
  --derived-from urn:atomic:ac:01KYMD-ac-1,urn:atomic:intent:01KYMD \
  --json | jq -r .id)

# 2. Gate and sign it
atomic memory validate "$ID"
atomic memory attest "$ID"

--derived-from takes canonical urns (comma-separated), each becoming a wasDerivedFrom edge in the knowledge graph. Link to the most specific source the insight came from:

Source URN form
Acceptance criterion urn:atomic:ac:<UID>-ac-N
Task urn:atomic:task:<UID>-N
Todo urn:atomic:todo:<id>
Intent (fallback) urn:atomic:intent:<UID>

Once linked, the memory surfaces through graph queries such as atomic query neighbors ac:<UID>-AC-1.

Subcommands

memory new — scaffold a canonical memory

atomic memory new --kind <KIND> [OPTIONS]
Option Effect
--kind <KIND> Memory kind (see the table above). Required.
--text <TEXT> Durable memory text for a non-interactive workflow. When omitted, writes an editable :::memory scaffold instead.
--about <URNS> Module/domain urns this memory is about (comma-separated).
--derived-from <IDS> Intent/change/source-memory RDF ids this was derived from (comma-separated).
--id <ID> Explicit memory id (the filename stem). Defaults to a freshly generated lowercased ULID.
--status <STATUS> Lifecycle status: active, superseded, or retracted (default active).
--json Emit {"id":…,"file":…,"kind":…} for scripting (e.g. … --json | jq -r .id).
atomic memory new --kind constraint
atomic memory new --kind lesson --about urn:atomic:module:storage

memory show — render a read-time projection

atomic memory show <ID> [--json]

A pure read: it does not gate and does not require a proof. --json emits the canonical node as JSON-LD.

atomic memory show 01j8zc4r8t
atomic memory show 01j8zc4r8t --json

memory validate — gate against the canonical shapes

atomic memory validate <ID_OR_PATH> [--json]

An un-attested memory reports violations for the missing proof and author (attributedTo) — expected, since attest is what makes it conform. Exits non-zero if the report does not conform.

atomic memory validate 01j8zc4r8t
atomic memory validate ./note.md
atomic memory validate 01j8zc4r8t --json

memory attest — sign into a tracked attestation

atomic memory attest <ID> [--identity <IDENTITY>] [--json]

Gates the memory, fills attributedTo from the signing identity, signs the canonical node, re-gates, and writes the attested node as a tracked vault entry. The source memory is unchanged.

--json emits the attested canonical node as JSON-LD — the same document memory show --json prints, now with the proof embedded — and nothing else, so stdout stays one parseable document.

atomic memory attest 01j8zc4r8t
atomic memory attest 01j8zc4r8t --identity alice-work
atomic memory attest 01j8zc4r8t --json

memory verify — verify a signed attestation

atomic memory verify <ID> [--identity <IDENTITY>]

Confirms the attestation is fresh and verifies its content hash + Ed25519 proof. Pass --identity if the memory was attested by someone else.

atomic memory verify 01j8zc4r8t
atomic memory verify 01j8zc4r8t --identity alice-work

memory list — list memories, attestation-aware

atomic memory list [--limit <N>] [--identity <IDENTITY>] [--sort <KEY>] [-r] [--json]

Shows each memory's id (full ULID), kind, status, about-count, an attested column (fresh / stale / –) and a verifies column (✓ / ✗ / –).

--sort <KEY> picks the column to order by; ties keep id order. -r, --reverse flips the chosen order (the id tiebreak stays ascending). -n/--limit caps the output to N rows after sorting, so it returns the first N in the order you asked for (shows all when omitted).

Key Orders by
updated Last update time, newest first (default — the historical order).
id ULID, ascending.
kind Kind, A→Z.
status Status, A→Z.
about Number of about edges, fewest first.
attested Fresh, then stale, then unattested.
verifies ✓, then ✗, then –.

Sorting runs in the vault service, so a key the listing's kind doesn't have is rejected (--sort title is only valid for intent list).

atomic memory list
atomic memory list --limit 10
atomic memory list --sort kind
atomic memory list --sort updated --reverse
atomic memory list --sort about --limit 5
atomic memory list --json

memory kinds — list the allowed kinds

atomic memory kinds [--json]

Surfaces the closed memoryKind vocabulary and when to use each, so you (or an agent) can classify a session ledger before calling atomic memory new.

atomic memory kinds
atomic memory kinds --json

memory write — freeform memory from stdin

atomic memory write <NAME> [--type <TYPE>]

Stores arbitrary stdin content at memory/<name>.md. --type sets a freeform label (e.g. user, feedback, project, reference; default project).

echo "# Design" | atomic memory write design
cat notes.md | atomic memory write architecture --type reference

Persistence — additive by construction

A canonical memory is a single flat tracked vault entry at memory/<id>.md. Attestation never mutates the stored memory, its content_hash, or the manifest merkle: the attested node + proof are written as a separate tracked attestation entry.

See also