Tools
AMA
By Official code and reference implementation for AMA: Adaptive Memory via Multi-Agent Collaboration (Findings of ACL 2026), plus an OpenClaw/Harness Agent memory skill plugin.
Install
openclaw plugins install --linkREADME
# 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 reference implementation for <strong>AMA</strong>, together with an AMA-based memory skill plugin for OpenClaw and Harness Agent-style systems.
</p>
<p align="center">
<a href="docs/reproduction.md">Reproduction</a> ·
<a href="docs/openclaw.md">OpenClaw setup</a> ·
<a href="docs/architecture.md">Architecture</a>
</p>
<details>
<summary><strong>中文说明（点击在当前页面展开）</strong></summary>
### 这个仓库包含什么？
AMA（Adaptive Memory via Multi-Agent Collaboration）是一个面向 LLM Agent 长期交互的自适应记忆框架，由 **Constructor、Retriever、Judge、Refresher** 四个专门智能体协作完成记忆构建、检索、验证与更新。
本仓库包含两条相互关联、可以独立使用的内容：
| 内容 | 适合谁 | 入口 |
| --- | --- | --- |
| **AMA 论文参考实现代码** | 希望复现论文、研究多粒度记忆与长期记忆评测的研究者 | [`python/AdaptiveMemory`](python/AdaptiveMemory)、[复现说明](docs/reproduction.md) |
| **AMA Memory Skill / Plugin** | 希望为 OpenClaw、Harness Agent 类 Agent 架构安装长期记忆能力的开发者 | [`SKILL.md`](SKILL.md)、[OpenClaw 安装说明](docs/openclaw.md) |
论文主要结果：AMA 在 LoCoMo（GPT-4o-mini）上取得 **0.774** 的整体 LLM Score；在 LongMemEval<sub>s</sub> 上取得 **0.698** 的平均准确率，并在知识更新问题上达到 **0.897**。默认 `K_r=2` 时仅处理 3,613 tokens，约为 FullContext 的 19%。
### 快速开始
```bash
git clone https://github.com/Sherlockwz/AMA.git
cd AMA
corepack enable pnpm
./scripts/setup.sh
```
安装 OpenClaw 插件：
```bash
openclaw plugins install --link .
openclaw plugins enable openclaw-ama
openclaw ama doctor
```
完整中文文档仍保留在 [`README_zh-CN.md`](README_zh-CN.md)，论文复现见 [`docs/reproduction.md`](docs/reproduction.md)，插件配置见 [`docs/openclaw.md`](docs/openclaw.md)。
</details>
AMA is a long-term memory framework for LLM agents. It coordinates four specialized agents—**Constructor**, **Retriever**, **Judge**, and **Refresher**—to build multi-granular memories, route each query to the appropriate granularity, verify retrieved evidence, and keep evolving knowledge consistent.
This repository has two connected, independently usable tracks:
| Track | What it provides | Start here |
| --- | --- | --- |
| **AMA research code** | Reference implementation for the paper, evaluation entry points, and reproduction documentation. | [`python/AdaptiveMemory`](python/AdaptiveMemory), [reproduction guide](docs/reproduction.md) |
| **AMA Memory Skill / Plugin** | A deployable memory layer for OpenClaw and Harness Agent-style architectures, with automatic recall/capture, six tools, and a local SQLite/FAISS sidecar. | [`SKILL.md`](SKILL.md), [OpenClaw guide](docs/openclaw.md) |
## Overview
| Agent | Responsibility |
| --- | --- |
| Constructor | Builds raw-text, fact-knowledge, and episodic memories. |
| Retriever | Rewrites queries and adaptively routes them to the best memory granularity. |
| Judge | Checks relevance and logical consistency, requesting another retrieval round when needed. |
| Refresher | Updates or removes conflicting memories to preserve temporal consistency. |
### Multi-granular memory construction
The Constructor preserves three complementary views of a conversation:
- **Raw text** retains exact wording and fine-grained temporal details.
- **Fact knowledge** stores atomic, reusable information.
- **Episode memory** captures events and cross-turn abstractions, created when the topic shifts, the user explicitly requests consolidation, or context becomes saturated.
The Retriever rewrites the query and routes it to the appropriate memory granularity. The Judge evaluates whether the evidence is relevant and logically consistent; insufficient evidence triggers a bounded retry, while conflicts invoke the Refresher to update or delete stale memory.
## Main results
AMA is evaluated on **LoCoMo** (1,540 questions over long multi-session conversations) and **LongMemEval<sub>s</sub>** (500 questions with approximately 115K-token histories).
### LoCoMo across four backbones
| Backbone | FullContext | Nemori | **AMA** |
| --- | ---: | ---: | ---: |
| GPT-4o-mini | 0.717 | 0.740 | **0.774** |
| GPT-4.1-mini | 0.786 | 0.774 | **0.805** |
| Qwen3-30B-Instruct | 0.733 | 0.756 | **0.791** |
| Qwen3-8B-Instruct | 0.696 | 0.686 | **0.707** |
Values are overall LLM Scores reported in the paper.
### LongMemEval<sub>s</sub> by question type
| Question type | FullContext | Zep | Nemori | **AMA** |
| --- | ---: | ---: | ---: | ---: |
| Single-session preference | 0.300 | 0.533 | 0.467 | 0.467 |
| Single-session assistant | 0.818 | 0.750 | 0.839 | **0.964** |
| Temporal reasoning | 0.365 | 0.541 | **0.617** | 0.444 |
| Multi-session | 0.406 | 0.474 | 0.511 | **0.624** |
| Knowledge update | 0.769 | 0.744 | 0.615 | **0.897** |
| Single-session user | 0.814 | 0.929 | 0.886 | **0.986** |
| **Average** | 0.548 | 0.632 | 0.642 | **0.698** |
AMA achieves the strongest reported average in this comparison, with particularly large gains on assistant-side, multi-session, knowledge-update, and user-specific questions. It does not lead every category; temporal reasoning remains a clear opportunity for future work.
### Accuracy–cost trade-off
| Method | Input tokens | Latency (s) | LLM Score |
| --- | ---: | ---: | ---: |
| FullContext | 18,625 | 7.206 | 0.717 |
| Nemori | 2,925 | 3.152 | 0.740 |
| AMA (`K_r=1`) | 2,491 | 3.124 | 0.723 |
| **AMA (`K_r=2`)** | **3,613** | **3.910** | **0.774** |
At the default `K_r=2`, AMA processes about **19%** of the FullContext tokens while improving the LoCoMo LLM Score from 0.717 to 0.774.
<p align="center">
<img src="docs/assets/retrieval-rounds-locomo.png" width="32%" alt="Effect of retrieval rounds on LoCoMo">
<img src="docs/assets/retrieval-rounds-longmemeval.png" width="32%" alt="Effect of retrieval rounds on LongMemEval">
<img src="docs/assets/retrieval-cost.png" width="32%" alt="Token and latency cost by retrieval rounds">
</p>
Performance improves most in the first few retrieval rounds and then saturates, while token use and latency continue to grow approximately linearly. This motivates `K_r=2` as the default operating point.
### Case study: adapting to evolving information
The upper example shows AMA identifying conflicting device information and refreshing the older fact instead of keeping both claims. The lower example shows intent-aware routing: factual questions retrieve Fact Knowledge, while abstract summary questions use Episode Memory. Together, these examples illustrate why AMA couples retrieval with judgment and maintenance.
## Installation
### 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
### Set up the repository
```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 any provider exposing compatible chat-completions and embeddings APIs. Copy [`.env.example`](.env.example) when you need a local template.
## OpenClaw plugin
Install the local checkout during development:
```bash
openclaw plugins install --link .
openclaw plugins enable openclaw-ama
```
Then add the following to `~/.openclaw/openclaw.json`:
```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
}
}
}
}
}
```
`allowConversationAccess` is OpenClaw's explicit permission for the `agent_end` hook to read the completed turn. It is required for `autoCapture`; omit it and set `autoCapture: false` if you only want explicit tool-based writes.
Restart the OpenClaw gateway and verify the integration:
```bash
openclaw ama doctor
openclaw ama stats
openclaw ama search "What do you remember about me?"
```
See the complete [OpenClaw setup guide](docs/openclaw.md) for Git installation, manual sidecar startup, configuration options, tools, and troubleshooting.
## Research code
The original Python implementation lives in [`python/AdaptiveMemory`](python/AdaptiveMemory). For a direct sidecar 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
```
Evaluation entry points are in [`python/AdaptiveMemory/Core`](python/AdaptiveMemory/Core). Benchmark datasets are not redistributed in this repository; follow [the reproduction guide](docs/reproduction.md) to obta
... (truncated)
tools
Comments
Sign in to leave a comment