Metadata-Version: 2.4
Name: reme-ai
Version: 0.4.0.6
Summary: Remember Me, Refine Me.
Author-email: EconML team of Alibaba Tongyi Lab <jinli.yl@alibaba-inc.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/agentscope-ai/ReMe
Project-URL: Documentation, https://reme.agentscope.io/
Project-URL: Repository, https://github.com/agentscope-ai/ReMe
Keywords: llm,memory,agent,agentscope,ai,mcp,reme
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: croniter>=2.0
Requires-Dist: fastapi>=0.135.1
Requires-Dist: fastmcp>=3.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: mistletoe>=1.5.1
Requires-Dist: numpy>=2.2.6
Requires-Dist: openai>=2.26.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.3.3
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: watchfiles>=1.1.1
Requires-Dist: zstandard>=0.23.0
Provides-Extra: core
Requires-Dist: agentscope>=2.0.2; extra == "core"
Requires-Dist: claude-agent-sdk>=0.2.91; extra == "core"
Requires-Dist: faiss-cpu>=1.13.2; extra == "core"
Requires-Dist: jieba>=0.42.1; extra == "core"
Requires-Dist: rjieba>=0.2.1; extra == "core"
Requires-Dist: neo4j>=6.2.0; extra == "core"
Requires-Dist: networkx>=3.4.2; extra == "core"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: full
Requires-Dist: reme-ai[core]; extra == "full"
Requires-Dist: reme-ai[dev]; extra == "full"
Dynamic: license-file

<p align="center">
 <img src="docs/figure/reme_logo.png" alt="ReMe Logo" width="50%">
</p>

<p align="center">
  <a href="https://pypi.org/project/reme-ai/"><img src="https://img.shields.io/badge/python-3.11+-blue" alt="Python Version"></a>
  <a href="https://pypi.org/project/reme-ai/"><img src="https://img.shields.io/pypi/v/reme-ai.svg?logo=pypi" alt="PyPI Version"></a>
  <a href="https://pepy.tech/project/reme-ai/"><img src="https://img.shields.io/pypi/dm/reme-ai" alt="PyPI Downloads"></a>
  <a href="https://github.com/agentscope-ai/ReMe"><img src="https://img.shields.io/github/commit-activity/m/agentscope-ai/ReMe?style=flat-square" alt="GitHub commit activity"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-black" alt="License"></a>
  <a href="./README.md"><img src="https://img.shields.io/badge/English-Click-yellow" alt="English"></a>
  <a href="./README_ZH.md"><img src="https://img.shields.io/badge/简体中文-点击查看-orange" alt="简体中文"></a>
  <a href="https://github.com/agentscope-ai/ReMe"><img src="https://img.shields.io/github/stars/agentscope-ai/ReMe?style=social" alt="GitHub Stars"></a>
  <a href="https://deepwiki.com/agentscope-ai/ReMe"><img src="https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg" alt="DeepWiki"></a>
</p>

<p align="center">
<a href="https://trendshift.io/repositories/20528" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20528" alt="agentscope-ai%2FReMe | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

<p align="center">
  <strong>A memory management toolkit for AI agents — Remember Me, Refine Me.</strong><br>
</p>

> Previous versions: [0.3.x](https://github.com/agentscope-ai/ReMe/tree/reme_v3) ·
> [0.2.x](https://github.com/agentscope-ai/ReMe/tree/v0.2.0.6) ·
> [MemoryScope](https://github.com/agentscope-ai/ReMe/tree/memoryscope_branch)

🧠 ReMe is a memory management toolkit for **AI agents**. It turns conversations and resources into readable, editable,
and searchable file-based long-term memory.

## ✨ Core Ideas

- **Memory as File**: Markdown files with frontmatter and wikilinks serve as memory nodes that both users and agents can
  read and write directly.
- **Self-evolving knowledge base**: Auto Memory, Auto Resource, and Auto Dream progressively transform conversations and
  resources into long-term memories, while automatically building wikilink relationships.
- **Progressive hybrid search**: ReMe combines wikilinks, BM25, and embeddings for hybrid retrieval across keyword
  matching, semantic recall, and relationship expansion.
- **Agent-friendly integration**: SKILL.md + CLI integration makes it easy for different agents to read, write,
  maintain, and reuse memory.

<p align="center">
  <img src="docs/figure/design-philosophy.svg" alt="ReMe Design Philosophy" width="92%">
</p>

<details>
<summary><b>Use Cases</b></summary>

<br>

- **Personal assistants**: Provide long-term memory for agents such
  as [QwenPaw](https://github.com/agentscope-ai/QwenPaw).
- **Coding assistants**: Preserve coding style, project background, and workflow experience across sessions.
- **Knowledge QA**: Progressively transform resources and conversations into a searchable, traceable, and linked
  Markdown knowledge base.
- **Task automation**: Reuse successful paths, lessons from failures, and operating procedures from past tasks.

</details>

## 📰 News

- Our paper [Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution](https://aclanthology.org/2026.findings-acl.829/) has been accepted to Findings of ACL 2026.

## 🚀 Quick Start

### Installation

ReMe requires Python 3.11+.

Install from pip:

```bash
pip install "reme-ai[core]"
```

Install from source:

```bash
git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install -e ".[core]"
```

### Environment Variables

Configure environment variables:

```bash
cat > .env <<'EOF'
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EOF
```

### Start the Service

```bash
reme start
```

The default service address is `127.0.0.1:2333`. If the port is occupied, specify another port:

```bash
reme start service.port=8181
# reme start workspace_dir=/tmp/reme-demo service.port=8181
```

After startup, check the service status. If you use a custom port, replace `2333` in the URL below with that port.

```bash
reme version
curl -s http://127.0.0.1:2333/version -H 'Content-Type: application/json' -d '{}'
```

### Agent Integration

ReMe runs as a service and exposes memory through CLI / MCP jobs. Agents can adopt it in whichever way fits them: deep
SDK integration, plugin integration, or a lightweight Skill + CLI integration. They can wire `auto_memory` / `proactive`
into their lifecycle so conversations are consolidated into memory and surfaced at the right time. Indexing (
`auto_index`) and resource processing (`auto_resource`) run automatically through file watching, and `auto_dream`
consolidates daily memories into long-term digests on a schedule.

<p align="center"><b>QwenPaw Auto Memory / Auto Dream demo</b></p>

<table>
  <tr>
    <td width="50%" align="center"><b>Auto Memory</b></td>
    <td width="50%" align="center"><b>Auto Dream</b></td>
  </tr>
  <tr>
    <td width="50%">
      <img src="docs/figure/qwenpaw-auto-memory.gif" alt="QwenPaw Auto Memory demo" width="100%">
    </td>
    <td width="50%">
      <img src="docs/figure/qwenpaw-auto-dream.gif" alt="QwenPaw Auto Dream demo" width="100%">
    </td>
  </tr>
</table>

Integration status across agents:

| Agent                                               | Status      | How it integrates                                                                                                                                                                                                                                                                             |
|-----------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [QwenPaw](https://github.com/agentscope-ai/QwenPaw) | ✅ Available | [Deep SDK integration](https://github.com/agentscope-ai/QwenPaw/blob/main/src/qwenpaw/agents/memory/reme_light_memory_manager.py) — embeds the ReMe app in-process, drives `search` / `auto_memory` / `auto_dream` jobs via `run_job`, and reuses the agent's own model (no separate server). |
| [Claude Code](plugins/reme)                         | ✅ Available | Plugin: HTTP MCP server for recall, a `reme-memory` skill, and a Stop hook that records each session via `auto_memory_cc`.                                                                                                                                                                    |
| Skill + CLI integration                            | ✅ Available | [Skill + CLI](skills/reme_memory/SKILL.md): install or copy the `reme_memory` skill, then use `reme version` to check the version and `reme search query="xxx" limit=5` to search memory.                                                                                                      |

For more details, see the [Quick Start](docs/zh/quick_start.md).

## 📁 Memory System

> Memory as File, File as Memory.

ReMe treats **memory as files**, progressively processing raw conversations and external resources from `session/` and
`resource/` into `daily/`, then consolidating them into reusable long-term knowledge nodes under `digest/`.

### Directory Structure

```text
<workspace_dir>/
├── metadata/       # Persistent system state such as indexes, graphs, and catalogs
├── session/        # Raw conversations and agent sessions
│   ├── dialog/
│   │   └── <session_id>.jsonl
│   ├── agentscope/
│   └── claude_code/
├── resource/            # External raw materials
│   └── YYYY-MM-DD/
│       └── <resource>.<ext>
├── daily/               # Lightly processed memory: daily facts, conversation summaries, resource readings
│   ├── YYYY-MM-DD.md
│   └── YYYY-MM-DD/
│       ├── <session_event>.md
│       ├── <resource_stem>.md
│       └── interests.yaml
└── digest/              # Long-term memory: personal facts, procedural experience, knowledge nodes
    ├── personal/
    │   └── {topic/event}.md
    ├── procedure/
    │   └── {topic/event}.md
    └── wiki/
        └── {topic/event}.md
```

<p align="center">
  <img src="docs/figure/reme-overview.svg" alt="ReMe file-based memory system overview" width="92%">
</p>

### Automatic Memory Flow

ReMe's automatic memory flow gradually turns raw conversations and resources into searchable, traceable, and reusable
file-based memory. During normal operation, background watchers maintain indexes and process resources, agent hooks
trigger conversation memory, and long-term consolidation plus proactive reminders run through scheduled tasks or
on-demand calls.

| Capability                                  | How it runs                                                           | Purpose                                                                                                                                                               | Main parameters                                                          |
|---------------------------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| [`auto_index`](docs/zh/memory_search.md)    | Background maintenance via `index_update_loop`                        | Scans on startup and continuously watches Markdown/JSONL changes in `daily/`, `digest/`, and `resource/`; updates chunk, BM25, embedding, and wikilink graph indexes. | Config: `watch_dirs`, `watch_suffixes`                                   |
| [`auto_memory`](docs/zh/auto_memory.md)     | Agent after-reply hook; also callable on demand                       | Saves raw conversation text and turns long-term valuable information into `daily/<date>/<session_id>.md` memory cards.                                                | Required: `messages`; optional: `session_id`, `memory_hint`              |
| [`auto_resource`](docs/zh/auto_resource.md) | Automatically triggered by resource watching; also callable on demand | Reads resource changes under `resource/<date>/` and creates or updates LLM-named daily resource cards linked by `source_resource`.                                    | Required: `changes`; each item may include `path`, `file_path`, `change` |
| [`auto_dream`](docs/zh/auto_dream.md)       | Scheduled by `dream_cron`; also callable on demand                    | Scans daily input for a given date, extracts long-term memory units, integrates them into `digest/`, and writes `daily/<date>/interests.yaml`.                        | `date`, `hint`, `topic_count`, `topic_diversity_days`                    |
| [`proactive`](docs/zh/proactive.md)         | Read on demand before agent proactive reminders                       | Reads `interests.yaml` generated by `auto_dream` and exposes topics worth attention to the upper-level agent; the caller decides whether to remind the user.          | `date`, `include_content`                                                |

<table>
  <tr>
    <td align="center" width="50%">
      <img src="docs/figure/memory-as-file.svg" alt="Memory as File" width="92%">
    </td>
    <td align="center" width="50%">
      <img src="docs/figure/auto-memory-resource.svg" alt="Auto Memory and Resource" width="92%">
    </td>
  </tr>
  <tr>
    <td align="center" width="50%">
      <img src="docs/figure/auto-dream-and-proactive.svg" alt="Auto Dream and Proactive" width="92%">
    </td>
    <td align="center" width="50%">
      <img src="docs/figure/auto-index-and-memory-search.svg" alt="Auto Index and Memory Search" width="92%">
    </td>
  </tr>
</table>

### ReMe Operations

ReMe operates the workspace through a unified CLI / Service Job interface. Agents usually only need retrieval, reading,
writing, editing, and automatic memory commands. Lower-level indexing, frontmatter, and file operation commands are
mainly for maintenance, debugging, or advanced integration.

| Category       | Command                                         | Description                                                                                                                       | Parameters                                                               |
|----------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| System status  | `reme version`                                  | Returns the ReMe package version.                                                                                                 | None                                                                     |
| System status  | `reme health_check`                             | Returns a health-check summary for ReMe components.                                                                               | None                                                                     |
| System status  | `reme help`                                     | Lists registered jobs and their metadata.                                                                                         | None                                                                     |
| Retrieval/read | [`reme search`](docs/zh/memory_search.md)       | Performs hybrid retrieval in the workspace with vector recall, BM25, and RRF fusion.                                              | Required: `query`; optional: `limit`, `min_score`                        |
| Retrieval/read | `reme node_search`                              | Recalls similar digest nodes by candidate abstraction name and description, mainly for `auto_dream` deduplication or association. | Required: `query`; optional: `limit`                                     |
| Retrieval/read | `reme traverse`                                 | Traverses the wikilink graph from a specified path.                                                                               | Required: `path`; optional: `depth`, `direction`                         |
| Retrieval/read | `reme read`                                     | Reads a Markdown file under the workspace.                                                                                        | Required: `path`; optional: `start_line`, `end_line`                     |
| Retrieval/read | `reme read_image`                               | Reads an image file under the workspace and returns base64.                                                                       | Required: `path`                                                         |
| Index          | `reme reindex`                                  | Clears file-store indexes and rebuilds indexes from existing files.                                                               | Config: `watch_dirs`, `watch_suffixes`                                   |
| Daily          | `reme daily_list`                               | Lists notes for a day.                                                                                                            | `date`                                                                   |
| Daily          | `reme daily_reindex`                            | Rebuilds the day-index page `daily/<date>.md`.                                                                                    | `date`                                                                   |
| Metadata       | `reme frontmatter_read`                         | Reads file frontmatter.                                                                                                           | Required: `path`                                                         |
| Metadata       | `reme frontmatter_update`                       | Merges key-values into file frontmatter.                                                                                          | Required: `path`, `metadata`                                             |
| Metadata       | `reme frontmatter_delete`                       | Deletes specified keys from file frontmatter.                                                                                     | Required: `path`, `keys`                                                 |
| File operation | `reme stat`                                     | Gets workspace path status, including size, mtime, existence, and file/directory type.                                            | Required: `path`                                                         |
| File operation | `reme list`                                     | Lists files under a workspace path.                                                                                               | `path`, `recursive`, `limit`                                             |
| File operation | `reme write`                                    | Creates or overwrites a Markdown file and writes name/description frontmatter.                                                    | Required: `path`, `name`, `description`, `content`; optional: `metadata` |
| File operation | `reme edit`                                     | Performs full-text find-and-replace on a Markdown file.                                                                           | Required: `path`, `old`, `new`                                           |
| File operation | `reme move`                                     | Moves or renames a workspace file and rewrites inbound wikilinks by default.                                                      | Required: `src_path`, `dst_path`; optional: `overwrite`, `retarget`      |
| File operation | `reme delete`                                   | Deletes a workspace file or folder and returns inbound wikilinks that still exist.                                                | Required: `path`                                                         |

## 🤝 Community and Support

- **Issues and requests**: Check [Open Issues](https://github.com/agentscope-ai/ReMe/issues) first. If there is no
  related discussion, open a new issue with background, expected behavior, and impact scope.
- **Code contributions**: Before making changes, read the [contribution guide](docs/zh/contributing.md)
  and [code framework](docs/zh/framework.md), and follow the CLI / Service / Application / Job / Step / Component
  layering.
- **Documentation contributions**: For user-visible installation, configuration, invocation, or behavior changes, update
  `docs/zh/` or `README.md` accordingly.
- **Commit convention**: Conventional Commits are recommended, for example `feat(search): add link expansion option` or
  `docs(zh): update quick start`.
- **Pre-submit checks**: Before submitting a PR, try to run `pre-commit run --all-files` and `pytest`. If tests that
  depend on LLMs, embeddings, or external services cannot run, explain that in the PR.
- **Get help**: Use [GitHub Issues](https://github.com/agentscope-ai/ReMe/issues) for bugs and feature requests. Project
  documentation is available at [https://reme.agentscope.io/](https://reme.agentscope.io/).

### Contributors

Thanks to everyone who has contributed to ReMe:

<a href="https://github.com/agentscope-ai/ReMe/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=agentscope-ai/ReMe" alt="Contributors" />
</a>

## 📄 Citation

```bibtex
@software{AgentscopeReMe2026,
  title = {AgentscopeReMe: Memory Management Kit for Agents},
  author = {ReMe Team},
  url = {https://reme.agentscope.io},
  year = {2026}
}

@inproceedings{cao-etal-2026-remember,
  title = "Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution",
  author = "Cao, Zouying  and
    Deng, Jiaji  and
    Yu, Li  and
    Zhou, Weikang  and
    Liu, Zhaoyang  and
    Ding, Bolin  and
    Zhao, Hai",
  booktitle = "Findings of the {A}ssociation for {C}omputational {L}inguistics: {ACL} 2026",
  year = "2026",
  publisher = "Association for Computational Linguistics",
  url = "https://aclanthology.org/2026.findings-acl.829/",
  pages = "16803--16822"
}
```

## ⚖️ License

This project is open source under the Apache License 2.0. See [LICENSE](./LICENSE) for details.

## 📈 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date)
