Quickstart

Experience MemX core features in 5 minutes: install → initialize → write → retrieve → check status.

Prerequisites

Python 3.9+ · pip · Lurus API KeyAPI KeyA secret credential for accessing the API, much like a password. Each Key can have its own quota and permissions.Learn more → (how to obtain one, used for LLM refinement in hybrid mode). Estimated 5 minutes.

Choose an Integration Method

MemX offers three integration forms: Python SDK / REST / MCP. The following demonstrates "write + retrieve"; pick whichever you prefer (the parameters are aligned across all three):

The step-by-step tutorial below uses the Python SDK as an example; REST / MCP work the same way.

1. Install

   pip install git+https://github.com/UU114/memx.git
   # 完整安装：pip install "git+https://github.com/UU114/memx.git#egg=memx[all]"

   Requires Python 3.9+. On first run, the local embedding model (about 90MB) is automatically downloaded to ~/.memx/models/.

2. Initialize

   from memx import Memory
   m = Memory(config={"ace_enabled": True})   # 开启 ACE 引擎（核心功能）

   Once ACE is enabled, all writes and retrievals go through the intelligent pipeline; the default configuration is sufficient for most scenarios.

3. Write Knowledge

   Automatically extract and learn knowledge from a conversation:

   # 从一段对话中学习
   result = m.add(
       [
           {"role": "user", "content": "pytest 总是超时怎么办？"},
           {"role": "assistant", "content": "试试 pytest -x --timeout=30，逐个测试跑可以定位慢的用例"}
       ],
       user_id="developer_1",
       scope="project:my-backend"
   )
   
   print(result)
   # {
   #   "ace_ingest": {
   #     "bullets_added": 1,
   #     "bullets_merged": 0,
   #     "bullets_skipped": 0,
   #     "privacy_filtered": 0
   #   }
   # }

   You can also inject knowledge manually:

   # 手动添加一条经验
   m.add(
       "部署前必须运行 go test -race ./... 检查竞态条件",
       user_id="developer_1",
       scope="project:my-backend",
       metadata={"knowledge_type": "method", "section": "workflow"}
   )

4. Retrieve Knowledge

   results = m.search(
       "pytest 调试技巧",
       user_id="developer_1",
       scope="project:my-backend"
   )
   
   for item in results["results"]:
       print(f"[{item['score']:.2f}] {item['memory']}")
   # [0.87] pytest 超时问题：使用 -x --timeout=30 逐个运行定位慢用例

   Retrieval automatically fuses four layers of search results (exact + fuzzy + metadata + semantic), and accounts for time decay and scope matching.

5. Check Knowledge Base Status

   status = m.status(user_id="developer_1")
   print(status)
   # {
   #   "total_memories": 42,
   #   "by_section": {"debugging": 12, "workflow": 8, "tools": 6, ...},
   #   "avg_decay_weight": 0.73,
   #   "permanent_count": 5,
   #   "archive_candidates": 2
   # }

CLI Quick Tour

memx status                              # 知识库统计
memx search "pytest 调试"                # 搜索
memx learn "always use -v flag ..."      # 手动添加
memx list --scope project:my-backend     # 列出指定作用域
memx forget <memory-id>                  # 删除
memx sweep                               # 手动触发衰减计算
memx conflicts                           # 检测矛盾知识
memx export --format json > knowledge.json   # 导出
memx import knowledge.json                   # 导入

Pure mem0 Compatibility Mode

Seamless migration from mem0

When you only need basic memory features, disable ACE and the behavior is 100% consistent with mem0 (zero-overhead passthrough when ACE is off, so you can migrate first and enable features gradually).

m = Memory()  # ace_enabled 默认 False
m.add("some knowledge", user_id="user1")
results = m.search("query", user_id="user1")

Next Steps

Next steps

Core Concepts — Dive into the four core modules of the ACE engineArchitecture — The complete pipeline architecture and data flowFAQ — Running into issues?