microsoft/amplifier-bundle-memory

microsoft/amplifier-bundle-memory

Description: Memory bundle for the Amplifier project

Language: Python

License: MIT

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-09-07T14:13:51Z

Pushed: 2026-09-09T05:10:16Z

Default branch: main

Fork: no

Archived: no

README:

amplifier-bundle-memory

Say a standing preference once. See it saved. Never say it again.

The bundle gives every Amplifier session on this device a small, always-loaded file of how you work (~/.amplifier-memory/MEMORY.md), saved to the moment you correct the assistant, undone with one command, explained by git log. No database, no daemon, nothing at session end.

Read in this order: [docs/VISION.v2.md](docs/VISION.v2.md), then the contracts in [contracts/](contracts/) — store.v3 (the files), session.v4 (what happens in a session), cli.v3 (the command), suggestions.v2 (Phase 2, the daily inbox).

The store is an instance: a directory of plain text, its own git repository. Which one a session uses is resolved in order — an explicit home from the caller (the modules' config: home:, or --home), else $AMPLIFIER_MEMORY_HOME, else the default ~/.amplifier-memory (store.v3 §1). A store made before v3 lives at ~/.amplifier/memory, and while that is the only one on the device it stays the default, so nothing moves until init offers to move it. Beside the memories the instance carries two files that are plumbing, not memory — never injected, never suggested, never cited (§2): config.yaml, its own configuration, and sessions.jsonl, one line per session seen. Set enabled: false in config.yaml and the instance goes inert: nothing is injected, no tool is offered, no timer runs, and every writer refuses in one line (§11).

Install

# 1. Session plane (load + save + /remember and /memory), composed into all sessions.
# Point --app at the behavior file, not at the root bundle: the root bundle includes
# this same behavior, so an --app install of it is a self-include the loader skips
# ("Circular Include Skipped"), leaving a session with no hook and no memory tool.
amplifier bundle add 'git+https://github.com/microsoft/amplifier-bundle-memory@main#subdirectory=behaviors/memory-session.yaml' --app

# 2. The CLI (`amplifier-memory`, a thin click wrapper over the `amplifier_memory`
# library: init · status · review · why · format_why · doctor · update_check ·
# update_plan · service_status · run_suggest · pending/accept/decline/skip —
# cli.py adds only parsing, printing and exit codes):
uv tool install git+https://github.com/microsoft/amplifier-bundle-memory@main

# 3. Create the store (a git repo at ~/.amplifier-memory) and install the daily
# suggestion timer. This is the only setup step; `--no-timer` skips the timer.
amplifier-memory init

# 4. Verify:
amplifier-memory doctor

Step 3 asks one question — *What kinds of things should I remember for you?* — offering a default answer you can accept with Enter, and saves your answer as m-001. It is your own words, verbatim: nothing is invented for you, and with no terminal attached it takes the default and says so. It then prints what it installed, how to turn it off (amplifier-memory service uninstall --home ) and where to steer what it costs (config.yaml inside the instance — [which model the judge uses](#which-model-the-judge-uses)). Running it again reports store exists · timer installed and changes nothing; once you have uninstalled the timer, init leaves it uninstalled.

If you already had a store at the older ~/.amplifier/memory, step 3 offers to move it to the default and prints what it did. It never moves it silently, and a no leaves it exactly where it is (with the mv you would run yourself).

--home: more than one instance

Every verb acts on one instance, and --home names it — before or after the verb, whichever reads better:

amplifier-memory status --home ~/work-memory
amplifier-memory --home ~/work-memory status # the same command

Without it the instance resolves as $AMPLIFIER_MEMORY_HOME, else ~/.amplifier-memory. Each instance is an independent git repository with its own config.yaml, its own inbox — and its own daily timer, whose unit name carries the instance, so two instances never collide and neither can uninstall the other's:

amplifier-memory service status # lists every instance timer on this device
amplifier-memory service uninstall --home ~/work-memory

doctor exits 0 when the store is healthy, and nonzero before step 3 has run. To see the session plane itself working, start a session and say a standing preference: it is saved in that turn and announced with its id and its undo.

To remove all of it:

amplifier bundle remove 'git+https://github.com/microsoft/amplifier-bundle-memory@main#subdirectory=behaviors/memory-session.yaml' --app
uv tool uninstall amplifier-memory
rm -rf ~/.amplifier-memory # deletes your memories

The daily suggestion inbox (Phase 2, below) needs nothing further: step 3 installed its timer. To turn it off, or to put it back afterwards:

amplifier-memory service uninstall # no more daily pass; the store is untouched
amplifier-memory service install # what `init` already did — run it to undo an uninstall

Both act on the instance --home resolves to. amplifier-memory service status lists every installed instance timer, not only that one, so a timer you set up for another instance is never invisible.

On a device set up before per-instance timers existed there is one un-instanced amplifier-memory-suggest.timer, which runs whichever instance resolves as the default. init and service install replace it with that instance's own timer — disabling and removing the old pair, so exactly one timer serves the instance — and print what they replaced. For any *other* instance it is left alone, and named as serving the default only. Every unit name these commands print is a file in the unit directory at the moment they print it.

Use

In any session:

/remember never use tabs in YAML; two-space indentation
/memory
/memory forget m-017
/memory help

Where an Amplifier CLI offers slash-command argument discovery, Tab after /memory can show these first-word choices. This is an optional display hint: bare /memory remains the overview and typed arguments keep their current behavior.

Or just correct the assistant — it saves and the receipt reads:

saved m-017 —...