github

agentscope-ai / ReMe

  • ัั€ะตะดะฐ, 4 ะผะฐั€ั‚ะฐ 2026โ€ฏะณ. ะฒ 00:00:05
https://github.com/agentscope-ai/ReMe

ReMe: Memory Management Kit for Agents - Remember Me, Refine Me.



ReMe Logo

Python Version PyPI Version PyPI Downloads GitHub commit activity

License English ็ฎ€ไฝ“ไธญๆ–‡ GitHub Stars

A memory management toolkit for AI agents โ€” Remember Me, Refine Me.

For legacy versions, see 0.2.x Documentation


๐Ÿง  ReMe is a memory management framework built for AI agents, offering both file-based and vector-based memory systems.

It addresses two core problems of agent memory: limited context windows (early information gets truncated or lost during long conversations) and stateless sessions (new conversations cannot inherit history and always start from scratch).

ReMe gives agents real memory โ€” old conversations are automatically condensed, important information is persisted, and the next conversation can recall it automatically.


๐Ÿ“ File-Based ReMe

Memory as files, files as memory

Treat memory as files โ€” readable, editable, and portable.

Traditional Memory Systems File-Based ReMe
๐Ÿ—„๏ธ Database storage ๐Ÿ“ Markdown files
๐Ÿ”’ Opaque ๐Ÿ‘€ Read anytime
โŒ Hard to modify โœ๏ธ Edit directly
๐Ÿšซ Hard to migrate ๐Ÿ“ฆ Copy to migrate
.reme/
โ”œโ”€โ”€ MEMORY.md          # Long-term memory: user preferences, project config, etc.
โ””โ”€โ”€ memory/
    โ””โ”€โ”€ YYYY-MM-DD.md  # Daily logs: work records for the day, written upon compact

Core Capabilities

ReMe File Based is the core class of the file-based memory system. It acts like an intelligent secretary, managing all memory-related operations:

Method Function Key Components
start ๐Ÿš€ Start memory system BaseFileStore (local file storage)
BaseFileWatcher (file watcher)
BaseEmbeddingModel (embedding cache)
close ๐Ÿ“• Close and save Close file store, stop file watcher, save embedding cache
context_check ๐Ÿ“ Check context limit ContextChecker
compact ๐Ÿ“ฆ Compact history to summary Compactor
summary ๐Ÿ“ Write important memory to files Summarizer
memory_search ๐Ÿ” Semantic memory search MemorySearch
memory_get ๐Ÿ“– Read specified memory file MemoryGet

๐Ÿ—ƒ๏ธ Vector-Based ReMe

ReMe Vector Based is the core class for the vector-based memory system, supporting unified management of three memory types:

Memory Type Purpose Usage Context
Personal memory User preferences, habits user_name
Task / procedural memory Task execution experience, success/failure patterns task_name
Tool memory Tool usage experience, parameter tuning tool_name

Core Capabilities

Method Function Description
summarize_memory ๐Ÿง  Summarize memory Automatically extract and store memory from conversations
retrieve_memory ๐Ÿ” Retrieve memory Retrieve relevant memory by query
add_memory โž• Add memory Manually add memory to vector store
get_memory ๐Ÿ“– Get memory Fetch a single memory by ID
update_memory โœ๏ธ Update memory Update content or metadata of existing memory
delete_memory ๐Ÿ—‘๏ธ Delete memory Delete specified memory
list_memory ๐Ÿ“‹ List memory List memories with filtering and sorting

๐Ÿ’ป ReMeCli: Terminal Assistant with File-Based Memory

้ฉฌ
ไธŠ
ๆœ‰
้’ฑ
remecli_en_1080p_3x.mp4
้ฉฌ
ๅˆฐ
ๆˆ
ๅŠŸ

When Is Memory Written?

Scenario Written to Trigger
Auto-compact when context is too long memory/YYYY-MM-DD.md Automatic in background
User runs /compact memory/YYYY-MM-DD.md Manual compact + background save
User runs /new memory/YYYY-MM-DD.md New conversation + background save
User says "remember this" MEMORY.md or log Agent writes via write tool
Agent finds important decisions/preferences MEMORY.md Agent writes proactively

Memory Retrieval Tools

Method Tool When to use Example
Semantic search memory_search Unsure where it is, fuzzy lookup "Earlier discussion about deployment"
Direct read read Know the date or file Read memory/2025-02-13.md

Search uses vector + BM25 hybrid retrieval (vector weight 0.7, BM25 weight 0.3), so queries using both natural language and exact keywords can match.

Built-in Tools

Tool Function Details
memory_search Search memory Vector + BM25 hybrid search over MEMORY.md and memory/*.md
bash Run commands Execute bash commands with timeout and output truncation
ls List directory Show directory structure
read Read file Text and images supported, with segmented reading
edit Edit file Replace after exact text match
write Write file Create or overwrite, auto-create directories
execute_code Run Python Execute code snippets
web_search Web search Search via Tavily

๐Ÿš€ Quick Start

Installation

pip install -U reme-ai

Environment Variables

API keys are set via environment variables; you can put them in a .env file in the project root:

Variable Description Example
REME_LLM_API_KEY LLM API key sk-xxx
REME_LLM_BASE_URL LLM base URL https://dashscope.aliyuncs.com/compatible-mode/v1
REME_EMBEDDING_API_KEY Embedding API key sk-xxx
REME_EMBEDDING_BASE_URL Embedding base URL https://dashscope.aliyuncs.com/compatible-mode/v1
TAVILY_API_KEY Tavily search API key (optional) tvly-xxx

Using ReMeCli

Start ReMeCli

remecli config=cli

ReMeCli System Commands

Year of the Horse easter egg: /horse โ€” fireworks, galloping animation, and random horse-year blessings.

Commands starting with / control session state:

Command Description Waits for response
/compact Manually compact current conversation and save to long-term memory Yes
/new Start new conversation; history saved to long-term memory No
/clear Clear everything, without saving No
/history View uncompressed messages in current conversation No
/help Show command list No
/exit Exit No

Difference between the three commands

Command Compact summary Long-term memory Message history
/compact New summary Saved Keep recent
/new Cleared Saved Cleared
/clear Cleared Not saved Cleared

/clear permanently deletes; nothing is persisted anywhere.

Using the ReMe Package

File-Based ReMe

import asyncio

from reme import ReMeFb


async def main():
    # Initialize and start
    reme = ReMeFb(
        default_llm_config={
            "backend": "openai",  # Backend type, OpenAI-compatible API
            "model_name": "qwen3.5-plus",  # Model name
        },
        default_file_store_config={
            "backend": "chroma",  # Store backend: sqlite/chroma/local
            "fts_enabled": True,  # Enable full-text search
            "vector_enabled": False,  # Enable vector search (set False if no embedding service)
        },
        context_window_tokens=128000,  # Model context window size (tokens)
        reserve_tokens=36000,  # Tokens reserved for output
        keep_recent_tokens=20000,  # Tokens to keep for recent messages
        vector_weight=0.7,  # Vector search weight (0โ€“1) for hybrid search
        candidate_multiplier=3.0,  # Candidate multiplier for recall
    )
    await reme.start()

    messages = [
        {"role": "user", "content": "I prefer Python 3.12"},
        {"role": "assistant", "content": "Noted, you prefer Python 3.12"},
    ]

    # Check if context exceeds limit
    result = await reme.context_check(messages)
    print(f"Compact result: {result}")

    # Compact conversation to summary
    summary = await reme.compact(messages_to_summarize=messages)
    print(f"Summary: {summary}")

    # Write important memory to files (ReAct Agent does this automatically)
    await reme.summary(messages=messages, date="2026-02-28")

    # Semantic search over memory
    results = await reme.memory_search(query="Python version preference", max_results=5)
    print(f"Search results: {results}")

    # Read specified memory file
    content = await reme.memory_get(path="MEMORY.md")
    print(f"Memory content: {content}")

    # Close (save embedding cache, stop file watcher)
    await reme.close()


if __name__ == "__main__":
    asyncio.run(main())

Vector-Based ReMe

import asyncio
from reme import ReMe


async def main():
    # Initialize ReMe
    reme = ReMe(
        working_dir=".reme",
        default_llm_config={
            "backend": "openai",
            "model_name": "qwen3-30b-a3b-thinking-2507",
        },
        default_embedding_model_config={
            "backend": "openai",
            "model_name": "text-embedding-v4",
            "dimensions": 1024,
        },
        default_vector_store_config={
            "backend": "local",  # Supports local/chroma/qdrant/elasticsearch
        },
    )
    await reme.start()

    messages = [
        {"role": "user", "content": "Help me write a Python script", "time_created": "2026-02-28 10:00:00"},
        {"role": "assistant", "content": "Sure, I'll help you write it", "time_created": "2026-02-28 10:00:05"},
    ]

    # 1. Summarize memory from conversation (auto-extract user preferences, task experience, etc.)
    result = await reme.summarize_memory(
        messages=messages,
        user_name="alice",  # Personal memory
        # task_name="code_writing",  # Task memory
    )
    print(f"Summarize result: {result}")

    # 2. Retrieve relevant memory
    memories = await reme.retrieve_memory(
        query="Python programming",
        # user_name="alice",
    )
    print(f"Retrieve result: {memories}")

    # 3. Manually add memory
    memory_node = await reme.add_memory(
        memory_content="User prefers concise code style",
        user_name="alice",
    )
    print(f"Added memory: {memory_node}")
    memory_id = memory_node.memory_id

    # 4. Get single memory by ID
    fetched_memory = await reme.get_memory(memory_id=memory_id)
    print(f"Fetched memory: {fetched_memory}")

    # 5. Update memory content
    updated_memory = await reme.update_memory(
        memory_id=memory_id,
        user_name="alice",
        memory_content="User prefers concise, well-commented code style",
    )
    print(f"Updated memory: {updated_memory}")

    # 6. List all memories for user (with filtering and sorting)
    all_memories = await reme.list_memory(
        user_name="alice",
        limit=10,
        sort_key="time_created",
        reverse=True,
    )
    print(f"User memory list: {all_memories}")

    # 7. Delete specified memory
    await reme.delete_memory(memory_id=memory_id)
    print(f"Deleted memory: {memory_id}")

    # 8. Delete all memories (use with caution)
    # await reme.delete_all()

    await reme.close()


if __name__ == "__main__":
    asyncio.run(main())

๐Ÿ›๏ธ Technical Architecture

File-Based ReMe Core Architecture

graph TB
    User[User / Agent] --> ReMeFb[File based ReMe]
    ReMeFb --> ContextCheck[Context Check]
    ReMeFb --> Compact[Context Compact]
    ReMeFb --> Summary[Memory Summary]
    ReMeFb --> Search[Memory Retrieval]
    ContextCheck --> FbContextChecker[Check Token Limit]
    Compact --> FbCompactor[Compact History to Summary]
    Summary --> FbSummarizer[ReAct Agent + File Tools]
    Search --> MemorySearch[Vector + BM25 Hybrid Search]
    FbSummarizer --> FileTools[read / write / edit]
    FileTools --> MemoryFiles[memory/*.md]
    MemoryFiles -.->|File change| FileWatcher[Async File Watcher]
    FileWatcher -->|Update index| FileStore[Local DB]
    MemorySearch --> FileStore
Loading

Memory Summary: ReAct + File Tools

Summarizer is the core component for memory summarization. It uses the ReAct + file tools pattern.

graph LR
    A[Receive conversation] --> B{Think: What's worth recording?}
    B --> C[Act: read memory/YYYY-MM-DD.md]
    C --> D{Think: How to merge with existing content?}
    D --> E[Act: edit to update file]
    E --> F{Think: Anything missing?}
    F -->|Yes| B
    F -->|No| G[Done]
Loading

File Tool Set

Summarizer is equipped with file operation tools so the AI can work directly on memory files:

Tool Function Use case
read Read file content View existing memory, avoid duplicates
write Overwrite file Create new memory file or major rewrite
edit Edit part of file Append or modify specific sections

Context Compaction

When a conversation gets too long, Compactor compresses history into a concise summary โ€” like meeting minutes, turning long discussion into key points.

graph LR
    A[Messages 1..N] --> B[๐Ÿ“ฆ Compact summary]
C[Recent messages] --> D[Keep as-is]
B --> E[New context]
D --> E
Loading

The compact summary includes whatโ€™s needed to continue:

Content Description
๐ŸŽฏ Goals What the user wants to accomplish
โš™๏ธ Constraints Requirements and preferences mentioned
๐Ÿ“ˆ Progress Completed / in progress / blocked tasks
๐Ÿ”‘ Decisions Decisions made and reasons
๐Ÿ“Œ Context Key data such as file paths, function names

Memory Retrieval

MemorySearch provides vector + BM25 hybrid retrieval. The two methods complement each other:

Retrieval Strength Weakness
Vector semantic Captures similar meaning with different wording Weaker on exact token match
BM25 full-text Strong exact token match No synonym or paraphrase understanding

Fusion: Both retrieval paths are used; results are combined by weighted sum (vector 0.7 + BM25 0.3), so both natural-language queries and exact lookups get reliable results.

graph LR
    Q[Search query] --> V[Vector search ร— 0.7]
Q --> B[BM25 ร— 0.3]
V --> M[Dedupe + weighted merge]
B --> M
M --> R[Top-N results]
Loading

Vector-Based ReMe Core Architecture

graph TB
    User[User / Agent] --> ReMe[Vector Based ReMe]
    ReMe --> Summarize[Memory Summarize]
    ReMe --> Retrieve[Memory Retrieve]
    ReMe --> CRUD[CRUD]
    Summarize --> PersonalSum[PersonalSummarizer]
    Summarize --> ProceduralSum[ProceduralSummarizer]
    Summarize --> ToolSum[ToolSummarizer]
    Retrieve --> PersonalRet[PersonalRetriever]
    Retrieve --> ProceduralRet[ProceduralRetriever]
    Retrieve --> ToolRet[ToolRetriever]
    PersonalSum --> VectorStore[Vector DB]
    ProceduralSum --> VectorStore
    ToolSum --> VectorStore
    PersonalRet --> VectorStore
    ProceduralRet --> VectorStore
    ToolRet --> VectorStore
Loading

โญ Community & Support

  • Star & Watch: Star helps more agent developers discover ReMe; Watch keeps you updated on new releases and features.
  • Share your work: In Issues or Discussions, share what ReMe unlocks for your agents โ€” weโ€™re happy to highlight great community examples.
  • Need a new feature? Open a Feature Request; weโ€™ll iterate with the community.
  • Code contributions: All forms of code contribution are welcome. See the Contribution Guide.
  • Acknowledgments: Thanks to OpenClaw, Mem0, MemU, CoPaw, and other open-source projects for inspiration and support.

๐Ÿ“„ Citation

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

โš–๏ธ License

This project is open source under the Apache License 2.0. See the LICENSE file for details.


๐Ÿ“ˆ Star History

Star History Chart