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.
Badge for your README
Markdown
[](/listings/sherlockwz--ama)HTML
<a href="/listings/sherlockwz--ama"><img src="/api/listings/sherlockwz--ama/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- ---
- name: ama-memory
- 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.
- metadata:
- openclaw:
- homepage: https://sherlockwz.github.io/AMA/
- ---
- # AMA Memory
- AMA maintains three complementary forms of memory:
- - raw text for exact details and wording;
- - fact knowledge for stable, atomic information;
- - episodes for high-level events and multi-turn summaries.
- The plugin normally recalls and captures memory automatically. Use the explicit tools when a task needs deterministic memory handling or when diagnosing an integration.
- ## Operating rules
- 1. Prefer automatic recall for ordinary conversation. Do not call retrieval repeatedly when the injected `<ama-memories>` context already answers the request.
- 2. Use `ama_retrieve` before answering a question that clearly depends on earlier sessions and lacks sufficient recalled context.
- 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.
- 4. Use `ama_session_end` when a conversation, topic, or work session has clearly ended so AMA can synthesize an episode.
- 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`.
- 6. Never expose API keys, database paths, internal record IDs, or unrelated stored memories in an answer.
- ## Tools
- ### `ama_retrieve`
- 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.
- ### `ama_process_turn`
- 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.
- ### `ama_process_assistant`
- Store an assistant response after it has been delivered. This does not perform a second retrieval.
- ### `ama_memory_list`
- Inspect memory counts and current window size. Use it for diagnostics, not as a substitute for semantic retrieval.
- ### `ama_session_end`
- Trigger end-of-session episode generation after the final turn has been captured.
- ### `ama_memory_forget`
- Erase all AMA memory for a user. Confirm intent and identity before invoking it.
- ## Typical workflow
- ```text
- new user turn
- → auto-recall injects relevant AMA memories
- → answer using only relevant context
- → auto-capture stores the user and assistant turns
- → session end synthesizes episodic memory when appropriate
- ```
- If automatic hooks are disabled, perform the same sequence explicitly with `ama_retrieve`, `ama_process_turn`, `ama_process_assistant`, and `ama_session_end`.
- ## Diagnostics
- When tools are unavailable or the sidecar is unhealthy, ask the operator to run:
- ```bash
- openclaw ama doctor
- openclaw ama stats
- ```
- 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)
- # AMA: Adaptive Memory via Multi-Agent Collaboration
- <p align="center">
- <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>
- <a href="https://arxiv.org/abs/2601.20352"><img src="https://img.shields.io/badge/arXiv-2601.20352-b31b1b" alt="arXiv"></a>
- <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>
- <a href="https://sherlockwz.github.io/AMA/"><img src="https://img.shields.io/badge/Project%20Page-AMA-2563eb" alt="Project page"></a>
- <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>
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-green" alt="Apache-2.0 license"></a>
- </p>
- <p align="center">
- Official code and reusable memory skills for <strong>AMA</strong> (Findings of ACL 2026).
- </p>
- <p align="center">
- <a href="README_zh-CN.md">中文说明</a> ·
- <a href="docs/reproduction.md">Reproduction</a> ·
- <a href="docs/architecture.md">Architecture</a> ·
- <a href="docs/openclaw.md">OpenClaw adapter</a> ·
- <a href="https://sherlockwz.github.io/AMA/">Project Page</a>
- </p>
- ## News
- - **2026-08-22:** We released the AMA research code, project page, and reusable memory skill with an OpenClaw reference adapter.
- ## Table of contents
- - [Overview](#overview)
- - [How AMA works](#how-ama-works)
- - [Two ways to use this repository](#two-ways-to-use-this-repository)
- - [Headline results](#headline-results)
- - [Repository layout](#repository-layout)
- - [Setup](#setup)
- - [Research code](#research-code)
- - [Memory skill for Harness Agents](#memory-skill-for-harness-agents)
- - [Citation](#citation)
- ## Overview
- 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.
- AMA addresses this problem through four collaborating agents and three complementary memory granularities:
- 
- | Agent | Responsibility |
- | --- | --- |
- | **Constructor** | Builds traceable raw-text memory, atomic fact knowledge, and event-level episode memory. |
- | **Retriever** | Rewrites the current query and routes it to the memory granularity that best matches its intent. |
- | **Judge** | Checks relevance and logical consistency, and requests another bounded retrieval round when evidence is insufficient. |
- | **Refresher** | Updates or removes conflicting memories so that stored knowledge follows the latest valid user state. |
- | Memory form | What it preserves | Best suited for |
- | --- | --- | --- |
- | **Raw Text** | Exact wording, conversational traces, and fine-grained temporal details | Questions requiring precise evidence |
- | **Fact Knowledge** | Atomic and reusable information extracted from dialogue | Direct factual recall and user attributes |
- | **Episode Memory** | Events and abstractions synthesized across multiple turns | Summaries and higher-level reasoning |
- ## How AMA works
- For each incoming turn, AMA executes a coordinated memory lifecycle:
- 1. **Retrieve:** rewrite the query, infer its information need, and search the appropriate memory granularity.
- 2. **Judge:** filter irrelevant evidence and decide whether to pass, retry retrieval, or refresh conflicting memory.
- 3. **Refresh:** update stale information or delete it only when the user explicitly asks to forget it or a conflicting record has expired.
- 4. **Construct:** preserve the validated interaction as raw text, fact knowledge, and—when appropriate—an episode.
- This loop separates memory construction, retrieval, verification, and maintenance into explicit roles while keeping the number of retrieval rounds bounded.
- ## Two ways to use this repository
- | Path | When to use it | Start here |
- | --- | --- | --- |
- | **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) |
- | **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) |
- ## Headline results
- | Evaluation | AMA | Reference point |
- | --- | ---: | ---: |
- | LoCoMo overall LLM Score (GPT-4o-mini) | **0.774** | Nemori 0.740; FullContext 0.717 |
- | LongMemEval`_s` average accuracy | **0.698** | Nemori 0.642 |
- | LongMemEval`_s` knowledge-update accuracy | **0.897** | AMA without Refresher 0.568 |
- | LoCoMo input tokens at `K_r=2` | **3,613** | FullContext 18,625 |
- 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.
- ## Repository layout
- ```text
- AMA/
- ├── python/AdaptiveMemory/ # paper reference implementation and evaluation code
- ├── python/server.py # local AMA HTTP sidecar
- ├── backend/ # runtime ↔ sidecar adapter
- ├── tools/ # six agent-callable AMA memory operations
- ├── skills/ama-memory/ # distributable memory skill
- ├── docs/ # project page and technical guides
- ├── tests/ # TypeScript and Python tests
- ├── index.ts # OpenClaw reference-adapter entry point
- ├── openclaw.plugin.json # OpenClaw plugin manifest
- └── SKILL.md # portable agent operating policy
- ```
- ## Setup
- ### 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
- ```bash
- 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.
- ```bash
- 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.
- ## Research code
- 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.
- Run the local sidecar for a direct smoke test:
- ```bash
- .venv/bin/python -m uvicorn python.server:app --host 127.0.0.1 --port 8321
- curl http://127.0.0.1:8321/health
- ```
- ## Memory skill for Harness Agents
- [`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.
- The repository also includes a complete **OpenClaw reference adapter** with automatic recall/capture hooks, CLI commands, and a managed SQLite/FAISS sidecar:
- ```bash
- openclaw plugins install --link .
- openclaw plugins enable openclaw-ama
- openclaw ama doctor
- ```
- <details>
- <summary><strong>Minimal OpenClaw configuration</strong></summary>
- ```json5
- {
- plugins: {
- slots: { memory: "openclaw-ama" },
- allow: ["openclaw-ama"],
- entries: {
- "openclaw-ama": {
- enabled: true,
- hooks: { allowConversationAccess: true },
- config: {
- llmApiKey: "${AMA_LLM_API_KEY}",
- llmBaseUrl: "${AMA_LLM_BASE_URL}",
- embeddingApiUrl: "${AMA_EMBEDDING_URL}",
- dataDir: "./ama-data",
- sidecarAutoStart: true,
- autoRecall: true,
- autoCapture: true
- }
- }
- }
- }
- }
- ```
- </details>
- See the [OpenClaw adapter guide](docs/openclaw.md) for Git installation, configuration options, tool definitions, permissions, and troubleshooting.
- ## Validation
- ```bash
- ./scripts/check.sh
- ```
- This runs strict TypeScript checks, Vitest, Python unit tests, bytecode compilation, and the production bundle.
- ## Citation
- If AMA helps your work, please cite:
- ```bibtex
- @inproceedings{huang-etal-2026-ama,
- title = {{AMA}: Adaptive Memory via Multi-Agent Collaboration},
- 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},
- booktitle = {Findings of the Association for Computational Linguistics: ACL 2026},
- year = {2026},
- pages = {3099--3120},
- doi = {10.18653/v1/2026.findings-acl.152},
- url = {https://aclanthology.org/2026.findings-acl.152/}
- }
- ```
- Machine-readable citation files are available as [`CITATION.cff`](CITATION.cff) and [`CITATION.bib`](CITATION.bib).
- ## Contributing
- Bug reports, reproducibility notes, documentation improvements, and integrations are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and use the issue templates.
- ## License
- Released under the [Apache License 2.0](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.