Commands

chamoji memory

memory.mdEdit on GitHub

Read and look after project memory. When a workstream ships or is dropped, chamoji saves a summary of it on a git ref of its own: its title, status, and its commits with their intent cards. It outlives the branch. This command lists it, shows it, searches it and shares it.

SINCE 0.11.0 CHANGES YOUR REPO --json FOR CI AND AGENTS

archive --purge removes an entry only from your clone. Run memory sync next: if origin still holds the entry, it prints the force-push that removes it there. chamoji never force-pushes for you.

CHANGES YOUR REPOchamoji memory

What it does, in order

  1. ws ship or ws drop saves an entry. On refs/chamoji/memory: the workstream’s title, emoji and status, and every commit on HEAD that names it, with its card. It’s written with git plumbing, so your working tree and index are never touched.
  2. list, show and search read it. From the ref in this clone, with no network. Search also reads every commit on HEAD, through an index kept in .git/chamoji/memory-index.json.
  3. archive hides an entry. It leaves the list, and its summary leaves search. memory show still finds it. --purge deletes it for good.
  4. sync shares it. Fetches origin’s memory, merges it with yours, and pushes only the memory ref. Two clones that remembered different workstreams keep both.

Only sync touches the network, and search --ai the TypeSafe API. Git doesn’t clone the memory ref, so a fresh clone runs init once to take in origin’s. Project memory has the whole picture.

Subcommands

  • Name
    chamoji memory list
    Description

    List the live entries: slug, status, commit count, emoji and title. A bare chamoji memory is the same. It says so when an entry is there but can’t be read, instead of calling memory empty.

  • Name
    chamoji memory show <slug>
    Description

    One entry, live or archived: its status, when it was last updated, and each commit with its card.

  • Name
    chamoji memory search <query>
    Description

    Keyword search (BM25) over every commit on HEAD, with its subject, body and card, and over the live entries. It prints up to ten matches, best first. The index rebuilds itself when HEAD or memory moves. It needs no network and no key.

  • Name
    chamoji memory reindex
    Description

    Rebuild the search index now, and say how many commits and entries, its documents, it holds.

  • Name
    chamoji memory archive <slug>
    Description

    Move an entry out of the list, and its summary out of search. The commits on HEAD still turn up in search. Its content and history stay, and it can still be shown. An entry that is already archived exits 1.

  • Name
    chamoji memory sync
    Description

    Merge origin’s memory into yours, then push the result. The push runs your pre-push hook like any other. It tries again only when it lost a race to another clone, and never forces.

Arguments

  • Name
    slug
    Type
    string · required by show and archive
    Description

    An entry’s id, as chamoji memory list shows it, such as keyboard-support. Give exactly one.

  • Name
    query
    Type
    string · required by search
    Description

    The words to look for. Several words need no quotes; a match can have any of them.

reindex and sync take no arguments, and a missing or extra argument exits 2.

Flags

  • Name
    --json
    Type
    boolean · list, show, search, sync
    Description

    Print the result as JSON on stdout. list prints an array of entries, and show one entry: version, slug, title, emoji, status, updatedAt, archived and commits. search prints the matches, each with kind (commit or workstream), id, title, card and score. sync prints fetched, merged, needsForce, entries and pushed. reindex and archive ignore it.

  • Name
    --archived
    Type
    boolean · list
    Description

    List the archived entries with the live ones. Their status says archived.

  • Name
    --purge
    Type
    boolean · archive
    Description

    Delete the entry for good instead of archiving it, live or archived. It removes the entry from your memory ref, deletes this worktree’s search index, which held its text, and leaves a marker so a later sync can’t bring it back. The slug can’t be saved to memory again, so start that workstream again under a new name. Other clones that fetched the entry keep their copy.

  • Name
    --ai
    Type
    boolean · search
    Description

    Let Jev reorder the ten best matches. Jev sees the query and, for each match, up to 300 characters of its subject and card, with emails removed. Needs TYPESAFE_API_KEY, from the environment or an untracked .env.local or .env; without one it exits 2. See Sorting with AI.

  • Name
    --no-update-check
    Type
    boolean
    Description

    Don’t check npm for a newer chamoji. See the update notice.

Common combinations

chamoji memory

What shipped and dropped workstreams left behind.

chamoji memory search focus

Find the commits and workstreams that mention it, cards included.

chamoji memory show keyboard-support

One workstream’s commits, with the reason behind each.

chamoji memory sync

Share what you remembered, and take in what your team did.

chamoji memory archive dark-mode --purge

Remove an entry for good, then run memory sync.

Output

These are from real runs in a small repo called widgets, with one workstream shipped and one dropped:

chamoji memory

dark-mode         dropped  2 commits  🌙 Dark mode
keyboard-support  shipped  3 commits  ⌨️ Keyboard support

chamoji memory show keyboard-support

⌨️ Keyboard support (keyboard-support)
shipped, updated 2026-11-05, 3 commits

7ab921a 🐛 Trap focus inside the dialog, 2026-11-05
  Why: Tab moved focus to the page behind the open dialog
  Constraint: the dialog must still close on Escape

f8b510b ✨ Move between days with the arrow keys, 2026-11-05

630bd60 🔧 Start keyboard support, 2026-11-05

Search finds the commit and the workstream that holds it:

chamoji memory search escape dialog

7ab921a 🐛 Trap focus inside the dialog
  Why: Tab moved focus to the page behind the open dialog
  Constraint: the dialog must still close on Escape
workstream keyboard-support Keyboard support
  Why: Tab moved focus to the page behind the open dialog
  Constraint: the dialog must still close on Escape
a33fd19 💄 Add dark colours to the picker
  Follow-up: the dialog still uses the light shadow
workstream dark-mode Dark mode
  Follow-up: the dialog still uses the light shadow

chamoji memory search shadow --json

[
  {
    "kind": "commit",
    "id": "a33fd1915e9b4e419d0d3b3d379c723859f6b55e",
    "title": "💄 Add dark colours to the picker",
    "card": {
      "why": [],
      "constraint": [],
      "gotcha": [],
      "followUp": [
        "the dialog still uses the light shadow"
      ]
    },
    "score": 2.5064509441245146
  },
  …
]

Search and the index

$ chamoji memory search zebra
Nothing in memory matches "zebra".

Archiving hides an entry, and --archived brings it back into the list:

Archive

$ chamoji memory archive dark-mode
Archived dark-mode. It stays in memory, out of the list; chamoji memory show dark-mode still finds it.

Sync

$ chamoji memory sync
Synced memory with origin: 2 entries.

A purge, after dark-mode was synced. The sync merges origin’s memory first, then names the force-push that would remove the entry there:

chamoji memory archive dark-mode --purge

Purged dark-mode from local memory. If it was ever synced, origin still has it. Run chamoji memory sync: it merges origin's memory into yours first, and says what to do if origin then needs replacing.

chamoji memory sync

Merged memory here: 1 entry. A purged entry is still on origin, so nothing was pushed. Origin's memory is merged into yours already. To remove the entry there, replace origin's memory with yours. This overwrites origin's history, and drops anything pushed there since this sync: git push --force origin refs/chamoji/memory

Errors

$ chamoji memory frob
chamoji: memory needs list, show, search, reindex, archive or sync, not "frob"

Exit codes

  • Name
    0
    Description
    It worked, including a search with no matches.
  • Name
    2
    Description

    It was used wrongly: an unknown subcommand, a missing slug or query, more than one slug, or an argument to reindex or sync. Also search --ai with no TypeSafe key.

  • Name
    1
    Description

    Anything else, such as an entry that doesn’t exist or is already archived, sync with no origin or a failed fetch or push, or outside a git repo.

Exit codes has every command’s codes.

Project memory

Intent cards, the memory ref, and who can change it.

Read more

ws

Ship or drop a workstream, which saves it to memory.

Read more

init

Share memory through origin in a fresh clone.

Read more

mcp

Let your coding agent search memory.

Read more

Was this page helpful?