[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72376":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},72376,"ReMe","agentscope-ai\u002FReMe","agentscope-ai","ReMe: Memory Management Kit for Agents - Remember Me, Refine Me.","",null,"Python",3065,259,19,3,0,16,40,139,48,29.24,"Apache License 2.0",false,"main",true,[27,28,29,30,31,32],"agent","ai-agents","memory","memoryscope","rag","reme","2026-06-12 02:03:02","\u003Cp align=\"center\">\n \u003Cimg src=\"docs\u002F_static\u002Ffigure\u002Freme_logo.png\" alt=\"ReMe Logo\" width=\"50%\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Freme-ai\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10+-blue\" alt=\"Python Version\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Freme-ai\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Freme-ai.svg?logo=pypi\" alt=\"PyPI Version\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpepy.tech\u002Fproject\u002Freme-ai\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Freme-ai\" alt=\"PyPI Downloads\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FReMe\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fm\u002Fagentscope-ai\u002FReMe?style=flat-square\" alt=\"GitHub commit activity\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\".\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache--2.0-black\" alt=\"License\">\u003C\u002Fa>\n  \u003Ca href=\".\u002FREADME.md\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FEnglish-Click-yellow\" alt=\"English\">\u003C\u002Fa>\n  \u003Ca href=\".\u002FREADME_ZH.md\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F简体中文-点击查看-orange\" alt=\"简体中文\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FReMe\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fagentscope-ai\u002FReMe?style=social\" alt=\"GitHub Stars\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdeepwiki.com\u002Fagentscope-ai\u002FReMe\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDeepWiki-Ask_Devin-navy.svg\" alt=\"DeepWiki\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F20528\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Ftrendshift.io\u002Fapi\u002Fbadge\u002Frepositories\u002F20528\" alt=\"agentscope-ai%2FReMe | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>A memory management toolkit for AI agents — Remember Me, Refine Me.\u003C\u002Fstrong>\u003Cbr>\n\u003C\u002Fp>\n\n> For the older version, please refer to the [0.2.x documentation](docs\u002FREADME_0_2_x.md).\n\n---\n\n## 📰 Latest Articles\n\n| Date       | Title                                                           |\n|------------|-----------------------------------------------------------------|\n| 2026-03-30 | [Context Management Design](docs\u002Fcopaw_context_design.md) |\n\n---\n\n🧠 ReMe is a memory management framework designed for **AI agents**, providing\nboth [file-based](#-file-based-memory-system-remelight) and [vector-based](#-vector-based-memory-system) memory systems.\n\nIt tackles two core problems of agent memory: **limited context window** (early information is truncated or lost in long\nconversations) and **stateless sessions** (new sessions cannot inherit history and always start from scratch).\n\nReMe gives agents **real memory** — old conversations are automatically compacted, important information is persistently\nstored, and relevant context is automatically recalled in future interactions.\n\nReMe achieves state-of-the-art results on the LoCoMo and HaluMem benchmarks; see the [Experimental results](#experimental-results).\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What you can do with ReMe\u003C\u002Fb>\u003C\u002Fsummary>\n\n\u003Cbr>\n\n- **Personal assistant**: Provide long-term memory for agents like [QwenPaw](https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FCoPaw),\n  remembering user preferences and conversation history.\n- **Coding assistant**: Record code style preferences and project context, maintaining a consistent development\n  experience across sessions.\n- **Customer service bot**: Track user issue history and preference settings for personalized service.\n- **Task automation**: Learn success\u002Ffailure patterns from historical tasks to continuously optimize execution\n  strategies.\n- **Knowledge Q&A**: Build a searchable knowledge base with semantic search and exact matching support.\n- **Multi-turn dialogue**: Automatically compress long conversations while retaining key information within limited\n  context windows.\n\n\u003C\u002Fdetails>\n\n---\n\n## 📁 File-based memory system (ReMeLight)\n\n> Memory as files, files as memory.\n\nTreat **memory as files** — readable, editable, and copyable.\n[QwenPaw](https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FCoPaw) integrates long-term memory and context management by inheriting from\n`ReMeLight`.\n\n| Traditional memory system | File-based ReMe      |\n|---------------------------|----------------------|\n| 🗄️ Database storage      | 📝 Markdown files    |\n| 🔒 Opaque                 | 👀 Always readable   |\n| ❌ Hard to modify          | ✏️ Directly editable |\n| 🚫 Hard to migrate        | 📦 Copy to migrate   |\n\n```\nworking_dir\u002F\n├── MEMORY.md              # Long-term memory: persistent info such as user preferences\n├── memory\u002F\n│   └── YYYY-MM-DD.md      # Daily journal: automatically written after each conversation\n├── dialog\u002F                # Raw conversation records: full dialog before compression\n│   └── YYYY-MM-DD.jsonl   # Daily conversation messages in JSONL format\n└── tool_result\u002F           # Cache for long tool outputs (auto-managed, expired entries auto-cleaned)\n    └── \u003Cuuid>.txt\n```\n\n### Core capabilities\n\n[ReMeLight](reme\u002Freme_light.py) is the core class of the file-based memory system. It provides full memory management\ncapabilities for AI agents:\n\n\u003Ctable>\n\u003Ctr>\u003Cth>Category\u003C\u002Fth>\u003Cth>Method\u003C\u002Fth>\u003Cth>Function\u003C\u002Fth>\u003Cth>Key components\u003C\u002Fth>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"4\">Context Management\u003C\u002Ftd>\u003Ctd>\u003Ccode>check_context\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>📊 Check context size\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fcontext_checker.py\">ContextChecker\u003C\u002Fa> — checks whether context exceeds thresholds and splits messages\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>compact_memory\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>📦 Compact history into summary\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fcompactor.py\">Compactor\u003C\u002Fa> — ReActAgent that generates structured context summaries\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>compact_tool_result\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>✂️ Compact long tool outputs\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Ftool_result_compactor.py\">ToolResultCompactor\u003C\u002Fa> — truncates long tool outputs and stores them in \u003Ccode>tool_result\u002F\u003C\u002Fcode> while keeping file references in messages\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>pre_reasoning_hook\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>🔄 Pre-reasoning hook\u003C\u002Ftd>\u003Ctd>\u003Ccode>compact_tool_result\u003C\u002Fcode> + \u003Ccode>check_context\u003C\u002Fcode> + \u003Ccode>compact_memory\u003C\u002Fcode> + \u003Ccode>summary_memory\u003C\u002Fcode> (async)\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"2\">Long-term Memory\u003C\u002Ftd>\u003Ctd>\u003Ccode>summary_memory\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>📝 Persist important memory to files\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fsummarizer.py\">Summarizer\u003C\u002Fa> — ReActAgent + file tools (\u003Ccode>read\u003C\u002Fcode> \u002F \u003Ccode>write\u003C\u002Fcode> \u002F \u003Ccode>edit\u003C\u002Fcode>)\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>memory_search\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>🔍 Semantic memory search\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"reme\u002Fmemory\u002Ffile_based\u002Ftools\u002Fmemory_search.py\">MemorySearch\u003C\u002Fa> — hybrid retrieval with vectors + BM25\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"2\">Session Memory\u003C\u002Ftd>\u003Ctd>\u003Ccode>get_in_memory_memory\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>💾 Create in-session memory instance\u003C\u002Ftd>\u003Ctd>Returns ReMeInMemoryMemory with dialog_path configured for persistence\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>await_summary_tasks\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>⏳ Wait for async summary tasks\u003C\u002Ftd>\u003Ctd>Block until all background summary tasks complete\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>-\u003C\u002Ftd>\u003Ctd>\u003Ccode>start\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>🚀 Start memory system\u003C\u002Ftd>\u003Ctd>Initialize file storage, file watcher, and embedding cache; clean up expired tool result files\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>-\u003C\u002Ftd>\u003Ctd>\u003Ccode>close\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>📕 Shutdown and cleanup\u003C\u002Ftd>\u003Ctd>Clean up tool result files, stop file watcher, and persist embedding cache\u003C\u002Ftd>\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n### 🚀 Quick start\n\n#### Installation\n\n**Install from source:**\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FReMe.git\ncd ReMe\npip install -e \".[light]\"\n```\n\n**Update to the latest version:**\n\n```bash\ngit pull\npip install -e \".[light]\"\n```\n\n#### Environment variables\n\n`ReMeLight` uses environment variables to configure the embedding model and storage backends:\n\n| Variable             | Description                   | Example                                             |\n|----------------------|-------------------------------|-----------------------------------------------------|\n| `LLM_API_KEY`        | LLM API key                   | `sk-xxx`                                            |\n| `LLM_BASE_URL`       | LLM base URL                  | `https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002Fv1` |\n| `EMBEDDING_API_KEY`  | Embedding API key (optional)  | `sk-xxx`                                            |\n| `EMBEDDING_BASE_URL` | Embedding base URL (optional) | `https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002Fv1` |\n\n#### Python usage\n\n```python\nimport asyncio\n\nfrom reme.reme_light import ReMeLight\n\n\nasync def main():\n    # Initialize ReMeLight\n    reme = ReMeLight(\n        default_as_llm_config={\"model_name\": \"qwen3.5-35b-a3b\"},\n        # default_embedding_model_config={\"model_name\": \"text-embedding-v4\"},\n        default_file_store_config={\"fts_enabled\": True, \"vector_enabled\": False},\n        enable_load_env=True,\n    )\n    await reme.start()\n\n    messages = [...]  # List of conversation messages\n\n    # 1. Check context size (token counting, determine if compaction is needed)\n    messages_to_compact, messages_to_keep, is_valid = await reme.check_context(\n        messages=messages,\n        memory_compact_threshold=90000,  # Threshold to trigger compaction (tokens)\n        memory_compact_reserve=10000,  # Token count to reserve for recent messages\n    )\n\n    # 2. Compact conversation history into a structured summary\n    summary = await reme.compact_memory(\n        messages=messages,\n        previous_summary=\"\",\n        max_input_length=128000,  # Model context window (tokens)\n        compact_ratio=0.7,  # Trigger compaction when exceeding max_input_length * 0.7\n        language=\"zh\",  # Summary language (e.g., \"zh\" \u002F \"\")\n    )\n\n    # 3. Compact long tool outputs (prevent tool results from blowing up context)\n    messages = await reme.compact_tool_result(messages)\n\n    # 4. Pre-reasoning hook (auto compact tool results + check context + generate summaries)\n    processed_messages, compressed_summary = await reme.pre_reasoning_hook(\n        messages=messages,\n        system_prompt=\"You are a helpful AI assistant.\",\n        compressed_summary=\"\",\n        max_input_length=128000,\n        compact_ratio=0.7,\n        memory_compact_reserve=10000,\n        enable_tool_result_compact=True,\n        tool_result_compact_keep_n=3,\n    )\n\n    # 5. Persist important memory to files (writes to memory\u002FYYYY-MM-DD.md)\n    summary_result = await reme.summary_memory(\n        messages=messages,\n        language=\"zh\",\n    )\n\n    # 6. Semantic memory search (vector + BM25 hybrid retrieval)\n    result = await reme.memory_search(query=\"Python version preference\", max_results=5)\n\n    # 7. Create in-session memory instance (manages context for one conversation)\n    memory = reme.get_in_memory_memory()  # Auto-configures dialog_path\n    for msg in messages:\n        await memory.add(msg)\n    token_stats = await memory.estimate_tokens(max_input_length=128000)\n    print(f\"Current context usage: {token_stats['context_usage_ratio']:.1f}%\")\n    print(f\"Message token count: {token_stats['messages_tokens']}\")\n    print(f\"Estimated total tokens: {token_stats['estimated_tokens']}\")\n\n    # 8. Mark messages as compressed (auto-persists to dialog\u002FYYYY-MM-DD.jsonl)\n    # await memory.mark_messages_compressed(messages_to_compact)\n\n    # Shutdown ReMeLight\n    await reme.close()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n> 📂 Full example: [test_reme_light.py](tests\u002Flight\u002Ftest_reme_light.py)\n> 📋 Sample run log: [test_reme_light_log.txt](tests\u002Flight\u002Ftest_reme_light_log.txt) (223,838 tokens → 1,105 tokens, 99.5%\n> compression)\n\n### Architecture of the file-based ReMeLight memory system\n\n#### Context data structure\n\n```mermaid\nflowchart TD\n    A[Context] --> B[compact_summary]\n    B --> C[dialog path guide + Goal\u002FConstraints\u002FProgress\u002FKeyDecisions\u002FNextSteps]\n    A --> E[messages: full dialogue history]\n    A --> F[File System Cache]\n    F --> G[dialog\u002FYYYY-MM-DD.jsonl]\n    F --> H[tool_result\u002Fuuid.txt N-day TTL]\n```\n\n---\n\n[MemoryManager](https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FCoPaw\u002Fblob\u002Fmain\u002Fsrc\u002Fcopaw\u002Fagents\u002Fmemory\u002Freme_light_memory_manager.py)\ninherits `ReMeLight` and integrates its memory capabilities into the agent reasoning loop:\n\n```mermaid\ngraph LR\n    Agent[Agent] -->|Before each reasoning step| Hook[pre_reasoning_hook]\n    Hook --> TC[compact_tool_result\u003Cbr>Compact tool outputs]\n    TC --> CC[check_context\u003Cbr>Token counting]\n    CC -->|Exceeds limit| CM[compact_memory\u003Cbr>Generate summary]\n    CC -->|Exceeds limit| SM[summary_memory\u003Cbr>Async persistence]\n    SM -->|ReAct + FileIO| Files[memory\u002F*.md]\n    CC -->|Exceeds limit| MMC[mark_messages_compressed\u003Cbr>Persist raw dialog]\n    MMC --> Dialog[dialog\u002F*.jsonl]\n    Agent -->|Explicit call| Search[memory_search\u003Cbr>Vector+BM25]\n    Agent -->|In - session| InMem[ReMeInMemoryMemory\u003Cbr>Token-aware memory]\n    InMem -->|Compress\u002FClear| Dialog\n    Files -.->|FileWatcher| Store[(FileStore\u003Cbr>Vector+FTS index)]\n    Search --> Store\n```\n\n---\n\n#### 1. `check_context` — context checking\n\n[ContextChecker](reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fcontext_checker.py) uses token counting to determine whether the\ncontext exceeds thresholds and automatically splits messages into a \"to compact\" group and a \"to keep\" group.\n\n```mermaid\ngraph LR\n    M[messages] --> H[AsMsgHandler\u003Cbr>Token counting]\n    H --> C{total > threshold?}\n    C -->|No| K[Return all messages]\n    C -->|Yes| S[Keep from tail\u003Cbr>reserve tokens]\n    S --> CP[messages_to_compact\u003Cbr>Earlier messages]\n    S --> KP[messages_to_keep\u003Cbr>Recent messages]\n    S --> V{is_valid\u003Cbr>Tool calls aligned?}\n```\n\n- **Core logic**: keep `reserve` tokens from the tail; mark the rest as messages to compact.\n- **Integrity guarantee**: preserves complete user-assistant turns and tool_use\u002Ftool_result pairs without splitting\n  them.\n\n---\n\n#### 2. `compact_memory` — conversation compaction\n\n[Compactor](reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fcompactor.py) uses a ReActAgent to compact conversation history into a *\n*structured context summary**.\n\n```mermaid\ngraph LR\n    M[messages] --> H[AsMsgHandler\u003Cbr>format_msgs_to_str]\n    H --> A[ReActAgent\u003Cbr>reme_compactor]\n    P[previous_summary] -->|Incremental update| A\n    A --> S[Structured summary\u003Cbr>Goal\u002FProgress\u002FDecisions...]\n```\n\n**Summary structure** (context checkpoints):\n\n| Field                 | Description                                                                             |\n|-----------------------|-----------------------------------------------------------------------------------------|\n| `## Goal`             | User goals                                                                              |\n| `## Constraints`      | Constraints and preferences                                                             |\n| `## Progress`         | Task progress                                                                           |\n| `## Key Decisions`    | Key decisions                                                                           |\n| `## Next Steps`       | Next step plans                                                                         |\n| `## Critical Context` | Critical data such as file paths, function names, error messages, etc.                  |\n\n- **Incremental updates**: when `previous_summary` is provided, new conversations are merged into the existing summary.\n- **Thinking enhancement**: with `add_thinking_block=True` (default), a reasoning step is added before generating the\n  summary to improve quality.\n\n---\n\n#### 3. `summary_memory` — persistent memory\n\n[Summarizer](reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Fsummarizer.py) uses a **ReAct + file tools** pattern so that the AI can\ndecide what to write and where to write it.\n\n```mermaid\ngraph LR\n    M[messages] --> A[ReActAgent\u003Cbr>reme_summarizer]\n    A -->|read| R[Read memory\u002FYYYY-MM-DD.md]\n    R --> T{Reason: how to merge?}\n    T -->|write| W[Overwrite]\n    T -->|edit| E[Edit in place]\n    W --> F[memory\u002FYYYY-MM-DD.md]\n    E --> F\n```\n\n**File tools** ([FileIO](reme\u002Fmemory\u002Ffile_based\u002Ftools\u002Ffile_io.py)):\n\n| Tool    | Function              |\n|---------|-----------------------|\n| `read`  | Read file content     |\n| `write` | Overwrite file        |\n| `edit`  | Find-and-replace edit |\n\n---\n\n#### 4. `compact_tool_result` — tool result compaction\n\n[ToolResultCompactor](reme\u002Fmemory\u002Ffile_based\u002Fcomponents\u002Ftool_result_compactor.py) addresses the problem of long tool\noutputs bloating the context. It applies two different truncation strategies depending on whether a message falls within\nthe `recent_n` window:\n\n```mermaid\ngraph LR\n    M[messages] --> B{Within recent_n?}\n    B -->|Yes - recent| C[Low truncation recent_max_bytes=100KB\u003Cbr>Save full content to tool_result\u002Fuuid.txt\u003Cbr>Hint: 'Read from line N']\n    B -->|No - old| D[High truncation old_max_bytes=3KB\u003Cbr>Reference existing file\u003Cbr>More aggressive truncation]\n    C --> E[cleanup_expired_files\u003Cbr>Delete expired files]\n    D --> E\n```\n\n| Parameter          | Default               | Description                                                                                                                   |\n|--------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------|\n| `recent_n`         | `1`                   | Minimum number of trailing consecutive tool-result messages treated as \"recent\" (use low truncation)                          |\n| `recent_max_bytes` | `100 * 1024` (100 KB) | Truncation threshold for recent messages; content beyond this is saved to `tool_result\u002F` with a file path and start-line hint |\n| `old_max_bytes`    | `3000` (3 KB)         | Truncation threshold for older messages; truncation is more aggressive                                                        |\n| `retention_days`   | `3`                   | Number of days to retain tool result files; expired files are auto-cleaned                                                    |\n\n- **Auto cleanup**: expired files (older than `retention_days`) are deleted automatically during `start` \u002F `close` \u002F\n  `compact_tool_result`.\n\n---\n\n#### 5. `memory_search` — memory retrieval\n\n[MemorySearch](reme\u002Fmemory\u002Ffile_based\u002Ftools\u002Fmemory_search.py) provides **vector + BM25 hybrid retrieval**.\n\n```mermaid\ngraph LR\n    Q[query] --> E[Embedding\u003Cbr>Vectorization]\n    E --> V[vector_search\u003Cbr>Semantic similarity]\n    Q --> B[BM25\u003Cbr>Keyword matching]\n    V -->|\" weight: 0.7 \"| M[Deduplicate + weighted merge]\n    B -->|\" weight: 0.3 \"| M\n    M --> F[min_score filter]\n    F --> R[Top-N results]\n```\n\n- **Fusion mechanism**: vector weight 0.7 + BM25 weight 0.3 — balancing semantic similarity and exact matches.\n\n---\n\n#### 6. `ReMeInMemoryMemory` — in-session memory\n\n[ReMeInMemoryMemory](reme\u002Fmemory\u002Ffile_based\u002Freme_in_memory_memory.py) extends AgentScope's `InMemoryMemory` to provide\ntoken-aware memory management and raw conversation persistence.\n\n```mermaid\ngraph LR\n    C[content] --> G[get_memory\u003Cbr>exclude_mark=COMPRESSED]\n    G --> F[Filter out compressed messages]\n    F --> P{prepend_summary?}\n    P -->|Yes| S[Prepend previous summary]\n    S --> O[Output messages]\n    P -->|No| O\n    M[mark_messages_compressed] --> D[Persist to dialog\u002FYYYY-MM-DD.jsonl]\n    D --> R[Remove from memory]\n```\n\n| Function                         | Description                                              |\n|----------------------------------|----------------------------------------------------------|\n| `get_memory`                     | Filter messages by mark and auto-append summary          |\n| `estimate_tokens`                | Estimate token usage of the context                      |\n| `state_dict` \u002F `load_state_dict` | Serialize\u002Fdeserialize state (session persistence)        |\n| `mark_messages_compressed`       | Mark messages compressed and persist to dialog directory |\n| `clear_content`                  | Persist all messages before clearing memory              |\n\n**Raw conversation persistence**: When messages are compressed or cleared, they are automatically saved to\n`{dialog_path}\u002F{date}.jsonl` with one JSON-formatted message per line.\n\n---\n\n#### 7. `pre_reasoning_hook` — pre-reasoning processing\n\nThis is a unified entry point that wires all the above components together and automatically manages context before each\nreasoning step.\n\n```mermaid\ngraph LR\n    M[messages] --> TC[compact_tool_result\u003Cbr>Compact long tool outputs]\n    TC --> CC[check_context\u003Cbr>Compute remaining space]\n    CC --> D{messages_to_compact\u003Cbr>Non-empty?}\n    D -->|No| K[Return original messages + summary]\n    D -->|Yes| V{is_valid?}\n    V -->|No| K\n    V -->|Yes| CM[compact_memory\u003Cbr>Sync summary generation]\n    V -->|Yes| SM[add_async_summary_task\u003Cbr>Async persistence]\n    CM --> R[Return messages_to_keep + new summary]\n```\n\n**Execution flow**:\n\n1. `compact_tool_result` — compact long tool outputs for all messages except the most recent\n   `tool_result_compact_keep_n`.\n2. `check_context` — check whether the context exceeds limits (remaining space = threshold minus tokens used by system\n   prompt and compressed summary).\n3. `compact_memory` — generate compact summary (sync), appended into `compact_summary`.\n4. `summary_memory` — persist memory to `memory\u002F*.md` (async in the background, non-blocking).\n\n| Key parameter                | Default | Description                                                                         |\n|------------------------------|---------|-------------------------------------------------------------------------------------|\n| `tool_result_compact_keep_n` | `3`     | Skip tool result compaction for the most recent N messages (preserve full content)  |\n| `memory_compact_reserve`     | `10000` | Token count to reserve for recent messages; messages beyond this trigger compaction |\n| `compact_ratio`              | `0.7`   | Compaction threshold ratio: `max_input_length × compact_ratio × 0.95`               |\n\n---\n\n## 🗃️ Vector-based memory system\n\n[ReMe Vector Based](reme\u002Freme.py) is the core class for the vector-based memory system. It manages three types of\nmemories:\n\n| Memory type           | Use case                                                          |\n|-----------------------|-------------------------------------------------------------------|\n| **Personal memory**   | Records user preferences and habits                               |\n| **Procedural memory** | Records task execution experience and patterns of success\u002Ffailure |\n| **Tool memory**       | Records tool usage experience and parameter tuning                |\n\n### Core capabilities\n\n| Method             | Function     | Description                                                 |\n|--------------------|--------------|-------------------------------------------------------------|\n| `summarize_memory` | 🧠 Summarize | Automatically extract and store memories from conversations |\n| `retrieve_memory`  | 🔍 Retrieve  | Retrieve related memories based on a query                  |\n| `add_memory`       | ➕ Add        | Manually add memories into the vector store                 |\n| `get_memory`       | 📖 Get       | Get a single memory by ID                                   |\n| `update_memory`    | ✏️ Update    | Update existing memory content or metadata                  |\n| `delete_memory`    | 🗑️ Delete   | Delete a specific memory                                    |\n| `list_memory`      | 📋 List      | List memories with filtering and sorting                    |\n\n### Installation and environment variables\n\nInstallation and environment configuration are the same as [ReMeLight](#installation).\nAPI keys are configured via environment variables and can be stored in a `.env` file at the project root.\n\n### Python usage\n\n```python\nimport asyncio\n\nfrom reme import ReMe\n\n\nasync def main():\n    # Initialize ReMe\n    reme = ReMe(\n        working_dir=\".reme\",\n        default_llm_config={\n            \"backend\": \"openai\",\n            \"model_name\": \"qwen3.5-plus\",\n        },\n        default_embedding_model_config={\n            \"backend\": \"openai\",\n            \"model_name\": \"text-embedding-v4\",\n            \"dimensions\": 1024,\n        },\n        default_vector_store_config={\n            \"backend\": \"local\",  # Supports local\u002Fchroma\u002Fqdrant\u002Felasticsearch\u002Fobvec\u002Fzvec\u002Fhologres\n        },\n    )\n    await reme.start()\n\n    messages = [\n        {\"role\": \"user\", \"content\": \"Help me write a Python script\", \"time_created\": \"2026-02-28 10:00:00\"},\n        {\"role\": \"assistant\", \"content\": \"Sure, I'll help you with that.\", \"time_created\": \"2026-02-28 10:00:05\"},\n    ]\n\n    # 1. Summarize memories from conversation (automatically extract user preferences, task experience, etc.)\n    result = await reme.summarize_memory(\n        messages=messages,\n        user_name=\"alice\",  # Personal memory\n        # task_name=\"code_writing\",  # Procedural memory\n    )\n    print(f\"Summary result: {result}\")\n\n    # 2. Retrieve related memories\n    memories = await reme.retrieve_memory(\n        query=\"Python programming\",\n        user_name=\"alice\",\n        # task_name=\"code_writing\",\n    )\n    print(f\"Retrieved memories: {memories}\")\n\n    # 3. Manually add a memory\n    memory_node = await reme.add_memory(\n        memory_content=\"The user prefers concise code style.\",\n        user_name=\"alice\",\n    )\n    print(f\"Added memory: {memory_node}\")\n    memory_id = memory_node.memory_id\n\n    # 4. Get a single memory by ID\n    fetched_memory = await reme.get_memory(memory_id=memory_id)\n    print(f\"Fetched memory: {fetched_memory}\")\n\n    # 5. Update memory content\n    updated_memory = await reme.update_memory(\n        memory_id=memory_id,\n        user_name=\"alice\",\n        memory_content=\"The user prefers concise code with comments.\",\n    )\n    print(f\"Updated memory: {updated_memory}\")\n\n    # 6. List all memories for the user (supports filtering and sorting)\n    all_memories = await reme.list_memory(\n        user_name=\"alice\",\n        limit=10,\n        sort_key=\"time_created\",\n        reverse=True,\n    )\n    print(f\"User memory list: {all_memories}\")\n\n    # 7. Delete a specific memory\n    await reme.delete_memory(memory_id=memory_id)\n    print(f\"Deleted memory: {memory_id}\")\n\n    # 8. Delete all memories (use with care)\n    # await reme.delete_all()\n\n    await reme.close()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### Technical architecture\n\n```mermaid\ngraph LR\n    User[User \u002F Agent] --> ReMe[Vector Based ReMe]\n    ReMe --> Summarize[Summarize memories]\n    ReMe --> Retrieve[Retrieve memories]\n    ReMe --> CRUD[CRUD operations]\n    Summarize --> PersonalSum[PersonalSummarizer]\n    Summarize --> ProceduralSum[ProceduralSummarizer]\n    Summarize --> ToolSum[ToolSummarizer]\n    Retrieve --> PersonalRet[PersonalRetriever]\n    Retrieve --> ProceduralRet[ProceduralRetriever]\n    Retrieve --> ToolRet[ToolRetriever]\n    PersonalSum --> VectorStore[Vector database]\n    ProceduralSum --> VectorStore\n    ToolSum --> VectorStore\n    PersonalRet --> VectorStore\n    ProceduralRet --> VectorStore\n    ToolRet --> VectorStore\n```\n\n### Experimental results\n\nEvaluations are conducted on two benchmarks: **LoCoMo** and **HaluMem**. Experimental settings:\n\n1. **ReMe backbone**: as specified in each table.\n2. **Evaluation protocol**: LLM-as-a-Judge following MemOS — each answer is scored by GPT-4o-mini.\n\nBaseline results are reproduced from their respective papers under aligned settings where possible.\n\n### LoCoMo\n\n| Method   | Single Hop | Multi Hop | Temporal  | Open Domain | Overall   |\n|----------|------------|-----------|-----------|-------------|-----------|\n| MemoryOS | 62.43      | 56.50     | 37.18     | 40.28       | 54.70     |\n| Mem0     | 66.71      | 58.16     | 55.45     | 40.62       | 61.00     |\n| MemU     | 72.77      | 62.41     | 33.96     | 46.88       | 61.15     |\n| MemOS    | 81.45      | 69.15     | 72.27     | 60.42       | 75.87     |\n| HiMem    | 89.22      | 70.92     | 74.77     | 54.86       | 80.71     |\n| Zep      | 88.11      | 71.99     | 74.45     | 66.67       | 81.06     |\n| TiMem    | 81.43      | 62.20     | 77.63     | 52.08       | 75.30     |\n| TSM      | 84.30      | 66.67     | 71.03     | 58.33       | 76.69     |\n| MemR3    | 89.44      | 71.39     | 76.22     | 61.11       | 81.55     |\n| **ReMe** | **89.89**  | **82.98** | **83.80** | **71.88**   | **86.23** |\n\n### HaluMem\n\n| Method      | Memory Integrity | Memory Accuracy | QA Accuracy |\n|-------------|------------------|-----------------|-------------|\n| MemoBase    | 14.55            | 92.24           | 35.53       |\n| Supermemory | 41.53            | 90.32           | 54.07       |\n| Mem0        | 42.91            | 86.26           | 53.02       |\n| ProMem      | **73.80**        | 89.47           | 62.26       |\n| **ReMe**    | 67.72            | **94.06**       | **88.78**   |\n\n---\n\n## 🧪 Procedural memory paper\n\n> Our procedural (task) memory paper is available on [arXiv](https:\u002F\u002Farxiv.org\u002Fabs\u002F2512.10696).\n\n### 🌍 [Appworld benchmark](benchmark\u002Fappworld\u002Fquickstart.md)\n\nWe evaluate ReMe on the Appworld environment using Qwen3-8B (non-thinking mode):\n\n| Method   | Avg@4               | Pass@4              |\n|----------|---------------------|---------------------|\n| w\u002Fo ReMe | 0.1497              | 0.3285              |\n| w\u002F ReMe  | 0.1706 **(+2.09%)** | 0.3631 **(+3.46%)** |\n\nPass@K measures the probability that at least one of K generated candidates successfully completes the task (score=1).\nThe current experiments use an internal AppWorld environment, which may differ slightly from the public version.\n\nFor more details on how to reproduce the experiments, see [quickstart.md](benchmark\u002Fappworld\u002Fquickstart.md).\n\n### 🔧 [BFCL-V3 benchmark](benchmark\u002Fbfcl\u002Fquickstart.md)\n\nWe evaluate ReMe on the BFCL-V3 multi-turn-base task (random split 50 train \u002F 150 val) using Qwen3-8B (thinking mode):\n\n| Method   | Avg@4               | Pass@4              |\n|----------|---------------------|---------------------|\n| w\u002Fo ReMe | 0.4033              | 0.5955              |\n| w\u002F ReMe  | 0.4450 **(+4.17%)** | 0.6577 **(+6.22%)** |\n\nFor more details on how to reproduce the experiments, see [quickstart.md](benchmark\u002Fbfcl\u002Fquickstart.md).\n\n## ⭐ Community & support\n\n- **Star & Watch**: Starring helps more agent developers discover ReMe; Watching keeps you up to date with new releases\n  and features.\n- **Share your results**: Share how ReMe empowers your agents in Issues or Discussions — we are happy to showcase great\n  community use cases.\n- **Need a new feature?** Open a feature request; we’ll evolve ReMe together with the community.\n- **Code contributions**: All forms of contributions are welcome. Please see\n  the [contribution guide](docs\u002Fcontribution.md).\n- **Acknowledgements**: We thank excellent open-source projects such as OpenClaw, Mem0, MemU, and QwenPaw for their\n  inspiration and support.\n\n### Contributors\n\nThanks to all who have contributed to ReMe:\n\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fagentscope-ai\u002FReMe\u002Fgraphs\u002Fcontributors\">\n  \u003Cimg src=\"https:\u002F\u002Fcontrib.rocks\u002Fimage?repo=agentscope-ai\u002FReMe\" alt=\"Contributors\" \u002F>\n\u003C\u002Fa>\n\n---\n\n## 📄 Citation\n\n```bibtex\n@software{AgentscopeReMe2025,\n  title = {AgentscopeReMe: Memory Management Kit for Agents},\n  author = {ReMe Team},\n  url = {https:\u002F\u002Freme.agentscope.io},\n  year = {2025}\n}\n```\n\n---\n\n## ⚖️ License\n\nThis project is open-sourced under the Apache License 2.0. See [LICENSE](.\u002FLICENSE) for details.\n\n---\n\n## 🤔 Why ReMe?\n\nReMe stands for **Remember Me** and **Refine Me**, symbolizing our goal to help AI agents \"remember\" users and \"refine\"\nthemselves through interactions. We hope ReMe is not just a cold memory module, but a partner that truly helps agents\nunderstand users, accumulate experience, and continuously evolve.\n\n---\n\n## 📈 Star history\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=agentscope-ai\u002FReMe&type=Date)](https:\u002F\u002Fwww.star-history.com\u002F#agentscope-ai\u002FReMe&Date)\n\n","ReMe 是一个专为AI代理设计的记忆管理工具包，旨在解决对话中信息丢失和会话无状态的问题。它提供了基于文件和基于向量的两种记忆系统，能够自动压缩旧对话、持久化存储重要信息，并在未来的交互中自动调用相关上下文，从而赋予AI代理真正的记忆能力。该工具包采用Python开发，支持Python 3.10及以上版本，适用于需要长期记忆支持的个人助理场景，如持续对话服务或虚拟助手等应用。",2,"2026-06-11 03:41:35","high_star"]