AI Memory Protocol integration

May 24, 2026 ยท View on GitHub

AI Memory Protocol support is beta.

tokenjuice install ai-memory-protocol writes a Sphinx-Needs RST preference memory to .memories/memory/preferences.rst. AI Memory Protocol stores memories as RST directives, rebuilds a searchable needs.json index with memory rebuild, and can expose recall/update tools over MCP.

Install

memory init .memories --name "My Project" --install
tokenjuice install ai-memory-protocol
MEMORY_DIR=.memories memory rebuild
tokenjuice doctor ai-memory-protocol
tokenjuice uninstall ai-memory-protocol

By default tokenjuice targets <current-working-directory>/.memories. Initialize that workspace with memory init first; tokenjuice refuses to create a partial memory workspace because memory rebuild needs the Sphinx config and memory indexes generated by AI Memory Protocol. Set AI_MEMORY_PROTOCOL_DIR=/path/to/.memories to target another initialized memory workspace; MEMORY_DIR is also honored when AI_MEMORY_PROTOCOL_DIR is not set.

Behavior

  • The memory is a pref entry with a stable PREF_TOKENJUICE_TERMINAL_OUTPUT_COMPACTION id.
  • The entry is installed as draft so the default AI Memory Protocol isolated-memory quality gate does not reject a standalone tokenjuice preference during memory rebuild; link or promote it if you curate the graph further.
  • The preference tells AI Memory Protocol-backed agents to prefer tokenjuice wrap -- <command> for commands likely to produce long output.
  • The only documented escape hatch is tokenjuice wrap --raw -- <command>.
  • Existing memory content is backed up before install and preserved around the tokenjuice block.
  • Incomplete workspaces are reported by tokenjuice doctor ai-memory-protocol with the missing AI Memory Protocol files.
  • Run MEMORY_DIR=.memories memory rebuild after install so memory recall and MCP tools see the new preference from the project-local workspace.
  • Run the same rebuild command after uninstall so memory recall and MCP tools drop the removed preference from needs.json.

The managed markers are RST comments:

.. tokenjuice:ai-memory-protocol begin
...
.. tokenjuice:ai-memory-protocol end

Current beta caveat

AI Memory Protocol is a memory and MCP recall layer, not a shell hook. This integration does not intercept command output or execute commands; it records a durable preference that agents can recall before choosing how to run noisy terminal commands.