Skip to content
Back to search

AMA

ACL 2026 Code and Skills for “AMA: Adaptive Memory via Multi-Agent Collaboration”.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sherlockwz--ama/badge.svg)](/listings/sherlockwz--ama)

HTML

<a href="/listings/sherlockwz--ama"><img src="/api/listings/sherlockwz--ama/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- Python 3.10+ - Node.js 22.22.3+ (Node.js 24.15+ is also supported) - pnpm 11+ - an OpenAI-compatible chat-completions endpoint and embedding endpoint

git clone https://github.com/Sherlockwz/AMA.git
cd AMA
corepack enable pnpm
./scripts/setup.sh

Configure credentials in your shell. Do not commit API keys.

export AMA_LLM_API_KEY="your-api-key"
export AMA_LLM_BASE_URL="https://api.openai.com/v1/chat/completions"
export AMA_EMBEDDING_URL="https://api.openai.com/v1/embeddings"

The implementation accepts providers exposing compatible chat-completions and embeddings APIs. Copy [`.env.example`](.env.example) when you need a local template.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 75 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ama-memory
  3. description: Use AMA memory in OpenClaw to recall prior context, capture turns, inspect stored state, end sessions, or delete a user's memory when asked.
  4. metadata:
  5. openclaw:
  6. homepage: https://sherlockwz.github.io/AMA/
  7. ---
  8. # AMA Memory
  9. AMA maintains three complementary forms of memory:
  10. - raw text for exact details and wording;
  11. - fact knowledge for stable, atomic information;
  12. - episodes for high-level events and multi-turn summaries.
  13. The plugin normally recalls and captures memory automatically. Use the explicit tools when a task needs deterministic memory handling or when diagnosing an integration.
  14. ## Operating rules
  15. 1. Prefer automatic recall for ordinary conversation. Do not call retrieval repeatedly when the injected `<ama-memories>` context already answers the request.
  16. 2. Use `ama_retrieve` before answering a question that clearly depends on earlier sessions and lacks sufficient recalled context.
  17. 3. Use `ama_process_turn` only for a user turn that should become long-term memory. Use `ama_process_assistant` for the corresponding assistant response.
  18. 4. Use `ama_session_end` when a conversation, topic, or work session has clearly ended so AMA can synthesize an episode.
  19. 5. Treat `ama_memory_forget` as destructive. Only invoke it after the user explicitly asks to delete or reset stored memory, and pass the intended `userId`.
  20. 6. Never expose API keys, database paths, internal record IDs, or unrelated stored memories in an answer.
  21. ## Tools
  22. ### `ama_retrieve`
  23. Search without changing memory. Pass a concise, self-contained query. Enable strong retrieval only when the first retrieval is insufficient and multi-round verification is warranted.
  24. ### `ama_process_turn`
  25. Process and store a user turn through retrieval, judging, refreshing, and construction. Use the actual user message rather than a paraphrase when wording or temporal details matter.
  26. ### `ama_process_assistant`
  27. Store an assistant response after it has been delivered. This does not perform a second retrieval.
  28. ### `ama_memory_list`
  29. Inspect memory counts and current window size. Use it for diagnostics, not as a substitute for semantic retrieval.
  30. ### `ama_session_end`
  31. Trigger end-of-session episode generation after the final turn has been captured.
  32. ### `ama_memory_forget`
  33. Erase all AMA memory for a user. Confirm intent and identity before invoking it.
  34. ## Typical workflow
  35. ```text
  36. new user turn
  37. → auto-recall injects relevant AMA memories
  38. → answer using only relevant context
  39. → auto-capture stores the user and assistant turns
  40. → session end synthesizes episodic memory when appropriate
  41. ```
  42. If automatic hooks are disabled, perform the same sequence explicitly with `ama_retrieve`, `ama_process_turn`, `ama_process_assistant`, and `ama_session_end`.
  43. ## Diagnostics
  44. When tools are unavailable or the sidecar is unhealthy, ask the operator to run:
  45. ```bash
  46. openclaw ama doctor
  47. openclaw ama stats
  48. ```
  49. Do not invent remembered content when retrieval fails. State that memory could not be checked and continue only with context available in the current conversation.
README.md · README · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AMA: Adaptive Memory via Multi-Agent Collaboration
  2. <p align="center">
  3. <a href="https://aclanthology.org/2026.findings-acl.152/"><img src="https://img.shields.io/badge/Paper-Findings%20of%20ACL%202026-4b5563" alt="ACL paper"></a>
  4. <a href="https://arxiv.org/abs/2601.20352"><img src="https://img.shields.io/badge/arXiv-2601.20352-b31b1b" alt="arXiv"></a>
  5. <a href="https://huggingface.co/papers/2601.20352"><img src="https://img.shields.io/badge/🤗%20Daily%20Paper-Hugging%20Face-ffcc4d" alt="Hugging Face paper"></a>
  6. <a href="https://sherlockwz.github.io/AMA/"><img src="https://img.shields.io/badge/Project%20Page-AMA-2563eb" alt="Project page"></a>
  7. <a href="https://github.com/Sherlockwz/AMA/actions/workflows/ci.yml"><img src="https://github.com/Sherlockwz/AMA/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  8. <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-green" alt="Apache-2.0 license"></a>
  9. </p>
  10. <p align="center">
  11. Official code and reusable memory skills for <strong>AMA</strong> (Findings of ACL 2026).
  12. </p>
  13. <p align="center">
  14. <a href="README_zh-CN.md">中文说明</a> ·
  15. <a href="docs/reproduction.md">Reproduction</a> ·
  16. <a href="docs/architecture.md">Architecture</a> ·
  17. <a href="docs/openclaw.md">OpenClaw adapter</a> ·
  18. <a href="https://sherlockwz.github.io/AMA/">Project Page</a>
  19. </p>
  20. ## News
  21. - **2026-08-22:** We released the AMA research code, project page, and reusable memory skill with an OpenClaw reference adapter.
  22. ## Table of contents
  23. - [Overview](#overview)
  24. - [How AMA works](#how-ama-works)
  25. - [Two ways to use this repository](#two-ways-to-use-this-repository)
  26. - [Headline results](#headline-results)
  27. - [Repository layout](#repository-layout)
  28. - [Setup](#setup)
  29. - [Research code](#research-code)
  30. - [Memory skill for Harness Agents](#memory-skill-for-harness-agents)
  31. - [Citation](#citation)
  32. ## Overview
  33. Long-term agent memory is more than storing and retrieving old messages. Different questions require different levels of detail, and user information can change over time. A useful memory system must therefore select the right representation, verify whether retrieved evidence is sufficient, and repair outdated knowledge instead of continually accumulating contradictions.
  34. AMA addresses this problem through four collaborating agents and three complementary memory granularities:
  35. ![AMA framework](docs/assets/ama-framework.png)
  36. | Agent | Responsibility |
  37. | --- | --- |
  38. | **Constructor** | Builds traceable raw-text memory, atomic fact knowledge, and event-level episode memory. |
  39. | **Retriever** | Rewrites the current query and routes it to the memory granularity that best matches its intent. |
  40. | **Judge** | Checks relevance and logical consistency, and requests another bounded retrieval round when evidence is insufficient. |
  41. | **Refresher** | Updates or removes conflicting memories so that stored knowledge follows the latest valid user state. |
  42. | Memory form | What it preserves | Best suited for |
  43. | --- | --- | --- |
  44. | **Raw Text** | Exact wording, conversational traces, and fine-grained temporal details | Questions requiring precise evidence |
  45. | **Fact Knowledge** | Atomic and reusable information extracted from dialogue | Direct factual recall and user attributes |
  46. | **Episode Memory** | Events and abstractions synthesized across multiple turns | Summaries and higher-level reasoning |
  47. ## How AMA works
  48. For each incoming turn, AMA executes a coordinated memory lifecycle:
  49. 1. **Retrieve:** rewrite the query, infer its information need, and search the appropriate memory granularity.
  50. 2. **Judge:** filter irrelevant evidence and decide whether to pass, retry retrieval, or refresh conflicting memory.
  51. 3. **Refresh:** update stale information or delete it only when the user explicitly asks to forget it or a conflicting record has expired.
  52. 4. **Construct:** preserve the validated interaction as raw text, fact knowledge, and—when appropriate—an episode.
  53. This loop separates memory construction, retrieval, verification, and maintenance into explicit roles while keeping the number of retrieval rounds bounded.
  54. ## Two ways to use this repository
  55. | Path | When to use it | Start here |
  56. | --- | --- | --- |
  57. | **Research reference implementation** | Study AMA, inspect the original Python pipeline, or reproduce the LoCoMo and LongMemEval`_s` experiments | [`python/AdaptiveMemory`](python/AdaptiveMemory), [reproduction guide](docs/reproduction.md) |
  58. | **Harness Agent memory skill** | Add AMA-style long-term memory behavior to an agent harness; use the included OpenClaw plugin as a complete reference adapter | [`SKILL.md`](SKILL.md), [architecture guide](docs/architecture.md), [OpenClaw adapter](docs/openclaw.md) |
  59. ## Headline results
  60. | Evaluation | AMA | Reference point |
  61. | --- | ---: | ---: |
  62. | LoCoMo overall LLM Score (GPT-4o-mini) | **0.774** | Nemori 0.740; FullContext 0.717 |
  63. | LongMemEval`_s` average accuracy | **0.698** | Nemori 0.642 |
  64. | LongMemEval`_s` knowledge-update accuracy | **0.897** | AMA without Refresher 0.568 |
  65. | LoCoMo input tokens at `K_r=2` | **3,613** | FullContext 18,625 |
  66. AMA achieves the highest reported overall LoCoMo LLM Score across all four tested backbones. On LongMemEval`_s`, the strongest gains appear in assistant-side recall, multi-session reasoning, knowledge updates, and user-specific information. Temporal reasoning remains a limitation: Nemori outperforms AMA in that category. See the [project page](https://sherlockwz.github.io/AMA/) for the complete result tables, efficiency analysis, retrieval-round study, ablations, and case study.
  67. ## Repository layout
  68. ```text
  69. AMA/
  70. ├── python/AdaptiveMemory/ # paper reference implementation and evaluation code
  71. ├── python/server.py # local AMA HTTP sidecar
  72. ├── backend/ # runtime ↔ sidecar adapter
  73. ├── tools/ # six agent-callable AMA memory operations
  74. ├── skills/ama-memory/ # distributable memory skill
  75. ├── docs/ # project page and technical guides
  76. ├── tests/ # TypeScript and Python tests
  77. ├── index.ts # OpenClaw reference-adapter entry point
  78. ├── openclaw.plugin.json # OpenClaw plugin manifest
  79. └── SKILL.md # portable agent operating policy
  80. ```
  81. ## Setup
  82. ### Requirements
  83. - Python 3.10+
  84. - Node.js 22.22.3+ (Node.js 24.15+ is also supported)
  85. - pnpm 11+
  86. - an OpenAI-compatible chat-completions endpoint and embedding endpoint
  87. ```bash
  88. git clone https://github.com/Sherlockwz/AMA.git
  89. cd AMA
  90. corepack enable pnpm
  91. ./scripts/setup.sh
  92. ```
  93. Configure credentials in your shell. Do not commit API keys.
  94. ```bash
  95. export AMA_LLM_API_KEY="your-api-key"
  96. export AMA_LLM_BASE_URL="https://api.openai.com/v1/chat/completions"
  97. export AMA_EMBEDDING_URL="https://api.openai.com/v1/embeddings"
  98. ```
  99. The implementation accepts providers exposing compatible chat-completions and embeddings APIs. Copy [`.env.example`](.env.example) when you need a local template.
  100. ## Research code
  101. The original Python implementation lives in [`python/AdaptiveMemory`](python/AdaptiveMemory). Evaluation entry points are under [`python/AdaptiveMemory/Core`](python/AdaptiveMemory/Core). Benchmark datasets are not redistributed; follow the [reproduction guide](docs/reproduction.md) to obtain and place them.
  102. Run the local sidecar for a direct smoke test:
  103. ```bash
  104. .venv/bin/python -m uvicorn python.server:app --host 127.0.0.1 --port 8321
  105. curl http://127.0.0.1:8321/health
  106. ```
  107. ## Memory skill for Harness Agents
  108. [`SKILL.md`](SKILL.md) expresses AMA as a portable operating policy for agent-harness architectures. It describes when an agent should retrieve prior context, capture user and assistant turns, synthesize episodes, inspect state, and honor explicit deletion requests. A harness can load this policy and bind the six AMA operations through its own tool interface.
  109. The repository also includes a complete **OpenClaw reference adapter** with automatic recall/capture hooks, CLI commands, and a managed SQLite/FAISS sidecar:
  110. ```bash
  111. openclaw plugins install --link .
  112. openclaw plugins enable openclaw-ama
  113. openclaw ama doctor
  114. ```
  115. <details>
  116. <summary><strong>Minimal OpenClaw configuration</strong></summary>
  117. ```json5
  118. {
  119. plugins: {
  120. slots: { memory: "openclaw-ama" },
  121. allow: ["openclaw-ama"],
  122. entries: {
  123. "openclaw-ama": {
  124. enabled: true,
  125. hooks: { allowConversationAccess: true },
  126. config: {
  127. llmApiKey: "${AMA_LLM_API_KEY}",
  128. llmBaseUrl: "${AMA_LLM_BASE_URL}",
  129. embeddingApiUrl: "${AMA_EMBEDDING_URL}",
  130. dataDir: "./ama-data",
  131. sidecarAutoStart: true,
  132. autoRecall: true,
  133. autoCapture: true
  134. }
  135. }
  136. }
  137. }
  138. }
  139. ```
  140. </details>
  141. See the [OpenClaw adapter guide](docs/openclaw.md) for Git installation, configuration options, tool definitions, permissions, and troubleshooting.
  142. ## Validation
  143. ```bash
  144. ./scripts/check.sh
  145. ```
  146. This runs strict TypeScript checks, Vitest, Python unit tests, bytecode compilation, and the production bundle.
  147. ## Citation
  148. If AMA helps your work, please cite:
  149. ```bibtex
  150. @inproceedings{huang-etal-2026-ama,
  151. title = {{AMA}: Adaptive Memory via Multi-Agent Collaboration},
  152. author = {Huang, Weiquan and Wang, Zixuan and Lin, Hehai and Wang, Sudong and Xu, Bo and Li, Qian and Zhu, Beier and Yang, Linyi and Qin, Chengwei},
  153. booktitle = {Findings of the Association for Computational Linguistics: ACL 2026},
  154. year = {2026},
  155. pages = {3099--3120},
  156. doi = {10.18653/v1/2026.findings-acl.152},
  157. url = {https://aclanthology.org/2026.findings-acl.152/}
  158. }
  159. ```
  160. Machine-readable citation files are available as [`CITATION.cff`](CITATION.cff) and [`CITATION.bib`](CITATION.bib).
  161. ## Contributing
  162. Bug reports, reproducibility notes, documentation improvements, and integrations are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and use the issue templates.
  163. ## License
  164. Released under the [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.