Memo Extension

Memos are notes stored as commits on the gitmsg/memo branch, with the core protocol only (GITMSG.md); each memo is at one of five tiers and has labels.

Tiers · Initialize · Write and promote · Sessions · Inherit · Labels · Workflows · Reference

Tiers

Order	Tier	Repository	Remote	In memo list by default
1	session	~/.cache/gitsocial/memo/session/<id>/	its own remote, when one is set	the current session only
2	personal	~/.config/gitsocial/personal/, shared with settings	the personal remote	yes
3	project	the workspace, refs/gitmsg/memo	the project remote	yes
4	inherited	followed repositories declared with memo inherit add	none	yes
5	external	other followed repositories with a memo branch	none	no; --include-external or --tier external

memo list reads the tiers in this order, the most local tier first. When two memos contradict, the priority/ labels decide which memo has priority, not the tier.

Initialize

gitsocial memo project init
gitsocial memo personal init
gitsocial personal init --remote <url>     # once per machine, so personal memos and settings sync
gitsocial personal sync [--push-only | --fetch-only]

GitSocial creates a session at its first memo. When two machines write memos between two syncs, the push or the fetch merges them automatically, and the merge commit is not a memo.

Write and promote

gitsocial memo create "Cache writes use ExecLocked" --labels kind/policy,priority/high,topic/cache [--body ...] [--scope session|personal|project]
gitsocial memo edit <ref> [--subject ...] [--body ...] [--labels ...]
gitsocial memo retract <ref>
gitsocial memo promote <ref> --to project|personal|session
gitsocial memo list | show <ref>

• The default tier is the session.
• promote writes a copy of the memo to the tier that --to names, as a new commit with no reference to the source. The source stays until you retract it or gc deletes its session.
• Project memos travel with gitsocial push and gitsocial fetch.

Sessions

gitsocial memo session init [<id>]            # create or resume; prints the id
gitsocial memo session list
gitsocial memo session sync <id> [--push-only | --fetch-only]
gitsocial memo session gc <id> | --older-than 30d
gitsocial memo list --include-sessions all|<id>

• The id comes from MEMO_SESSION_ID, or is <YYYYMMDD>-<8 hex> when it is not set. All strings are valid ids: daily, task-auth-bug.
• A session stays until gc deletes its repository and all its memos that are not promoted.

Inherit

gitsocial memo inherit add <url>
gitsocial memo inherit list
gitsocial memo inherit remove <url>
gitsocial memo list --tier inherited | --tier external | --include-external

inherit add records the repository at refs/gitmsg/memo/inherits/<urlHash> and adds it, with all branches, to the social list memo-inherits, which GitSocial manages. Each fetch then gets its memo branch. inherit remove reverses both steps.

Labels

Labels are the core <scope>/<value> field (GITMSG.md §1.7).

Scope	Values
kind/	policy, guideline, fact, reference, context, decision
priority/	low, normal, high, critical
expires/	YYYY-MM-DD, or full ISO 8601
topic/, area/, workflow/, compliance/, audience/	free
vocab/<name>	declares a taxonomy whose terms follow as <name>/<term>

Workflows

• Solo. Write to the session as you work; at the end of the day, run memo list and promote --to project the memos to keep.
• Team. Run memo create --scope project --labels priority/critical,kind/policy, then gitsocial push. Teammates run fetch and memo list --tier project. Comment on a memo only when it is on its final tier: a promotion does not move the comments to the new commit.
• Organization. Run memo inherit add https://github.com/org/policies, fetch and memo list --tier inherited. An inherited priority/critical policy has priority over a local priority/low memo.
• Several machines. On each machine, run gitsocial personal init --remote <url> and memo personal init. Write with memo create --scope personal, then run gitsocial personal sync on both machines.
• Agents. Sessions with different ids are in different repositories.
  1. Set MEMO_SESSION_ID=task-auth-bug; a run with the same id continues the session.
  2. Write memos with memo create.
  3. Examine them with memo list --include-sessions task-auth-bug --json.
  4. Promote the memos to keep.
  5. Run memo session gc task-auth-bug, or gc --older-than 30d from cron.

Reference

• Versions follow GITMSG.md §1.5 and labels §1.7.
• memo list sorts by tier, then by priority/ rank, then newest first. It excludes these memos:

Excluded	Show them with
retracted memos
expired memos	--include-expired, or --expired for only these
memos of other sessions	--include-sessions
memos on the external tier	--include-external
stale commits (ARCHITECTURE.md)

• A comment on a memo you authored, and a priority/critical memo on an inherited repository, create notifications.
• gitsocial search --type memo applies the same defaults, and --tier limits it to one tier.
• GITSOCIAL_PERSONAL_REPO overrides the personal repository, MEMO_SESSION_DIR the sessions directory and MEMO_SESSION_ID the session, all from the environment only (SETTINGS.md).
• In the TUI, M opens memos, grouped by tier (TUI-KEYS.md).