https://github.com/NeoLi00/memX
memX: self-learning, self-maintaining memory for AI agents
https://github.com/NeoLi00/memX
agent agent-memory embeddings graph-memory long-term-memory openclaw
Last synced: 10 days ago
JSON representation
memX: self-learning, self-maintaining memory for AI agents
- Host: GitHub
- URL: https://github.com/NeoLi00/memX
- Owner: NeoLi00
- Created: 2026-05-08T08:27:34.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-20T06:40:08.000Z (23 days ago)
- Last Synced: 2026-05-20T06:59:20.655Z (23 days ago)
- Topics: agent, agent-memory, embeddings, graph-memory, long-term-memory, openclaw
- Language: TypeScript
- Homepage:
- Size: 2.48 MB
- Stars: 69
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README-ch.md
Awesome Lists containing this project
README
---
memX 把完成后的工作 turn 编译成结构化、可检索、可维护的长期记忆，并只把当前 query 需要的证据注入 prompt。
它原生适配 Codex、Claude Code、OpenClaw，也能通过同一层本地记忆接入任何支持 MCP 的 client。
## Benchmark
测试集
范围
R@3 成功率
LongMemEval-S
长上下文记忆召回
94.2%
真实工程 case
30 个 case，每个 20+ turns
100%
## 架构
## Agent 支持
Codex
原生 hooks，默认隐藏 MCP
Claude Code
原生 hooks，默认隐藏 MCP
OpenClaw
原生 + hooks
MCP
MCP clients
任何兼容 MCP 的 client
## 快速启动
依赖：Node.js 22.14+ 或 Node 24。OpenClaw 安装需要 OpenClaw 2026.3.25+。只有使用默认本地
embedding 运行时时才需要 Python 3。
README 命令默认使用 GitHub package spec。每次全新执行都会拉取 GitHub 当前代码，因此安装流程
不需要等待 npm publish。以后如果明确要用 npm 发布通道，再把 `github:NeoLi00/memX`
换成 `@neoli00/memx`。
先把下面这些值填好，再运行对应命令：
- `--llm-provider`：memX 要调用的 LLM provider adapter。可选 `openai-compatible`、
`anthropic`、`google` 或 `ollama`。
- `--llm-base-url`：provider 的 base URL。例如 `https://api.openai.com/v1`、
`https://api.anthropic.com/v1`、`https://generativelanguage.googleapis.com/v1beta`，或者
Ollama 的 `http://127.0.0.1:11434`。
- `--llm-model`：memX 用来做记忆编译、召回规划和维护的模型。建议选速度快、成本低、JSON 输出
稳定的模型。
- `--llm-api-key`：provider API key。如果不想写明文，用
`--llm-api-key-env PROVIDER_API_KEY`，配置里会保存环境变量引用。本地 Ollama 可以不传 key。
默认 embedding 是本地 `sentence-transformers-local`，模型 `intfloat/multilingual-e5-small`。
只有想覆盖默认值时才需要额外传 `--embedding-provider` 和 `--embedding-model`。使用 `--dry-run`
可以先预览会写入哪些文件、会执行哪些 exec-form 命令。
对 Codex 和 Claude Code，native hooks 是默认生命周期入口，自动负责召回和 turn 捕获。Quickstart
会一次性安装 native plugin、写入共享 memX 配置、启动或刷新 managed local memX service，并默认用
`--mcp-tools none` 隐藏 MCP 记忆工具。这样既避免重复召回/重复写入，也避免 agent 把 audit 数据当作
旁路记忆读取。只有明确希望 agent 看见完整 MCP 工具集时，才加 `--mcp-tools full`。通用 MCP
quickstart 默认仍是 `full`，因为它没有 native lifecycle hooks。默认 native 记忆也会按 host
隔离，所以 Codex 和 Claude Code 不会共用同一个本地数据库，除非你主动覆盖 database path 和
actor 设置。
如果 `http://127.0.0.1:3878` 已经被一个不受当前 quickstart 管理的 memX-compatible service 占用，
quickstart 会停止并提示冲突，而不是静默复用旧服务。你可以先停掉旧服务，或传一个空闲本地地址，
例如 `--memx-url http://127.0.0.1:3888`。
### Claude Code
这条命令会一次性写入共享 memX 配置、生成本地 Claude Code plugin marketplace、安装 native
生命周期 hooks，并启动 managed local memX service。
```bash
npx -y -p github:NeoLi00/memX memx quickstart claude-code \
--llm-provider openai-compatible \
--llm-base-url https://llm.example.com/v1 \
--llm-model fast-memory-model \
--llm-api-key sk-your-provider-key
```
### Codex
这条命令会一次性写入共享 memX 配置、生成本地 Codex plugin marketplace、安装 native 生命周期
hooks，并启动 managed local memX service。
```bash
npx -y -p github:NeoLi00/memX memx quickstart codex \
--llm-provider openai-compatible \
--llm-base-url https://llm.example.com/v1 \
--llm-model fast-memory-model \
--llm-api-key sk-your-provider-key
```
### OpenClaw
```bash
npx -y -p github:NeoLi00/memX memx quickstart openclaw \
--llm-provider openai-compatible \
--llm-base-url https://llm.example.com/v1 \
--llm-model fast-memory-model \
--llm-api-key sk-your-provider-key
```
### 通用 MCP
这个路径用于没有 memX native lifecycle adapter 的 MCP client。Quickstart 会写入共享 memX
配置、启动 managed local memX service，并输出可以放进 MCP client 的 server 配置。
```bash
npx -y -p github:NeoLi00/memX memx quickstart mcp \
--llm-provider openai-compatible \
--llm-base-url https://llm.example.com/v1 \
--llm-model fast-memory-model \
--llm-api-key sk-your-provider-key
```
### Service 管理
```bash
npx -y -p github:NeoLi00/memX memx service status
npx -y -p github:NeoLi00/memX memx service restart
npx -y -p github:NeoLi00/memX memx service stop
```
如果 quickstart 时用了非默认路径或端口，管理 service 时也传同样的 `--home`、`--memx-url` 和
`--memx-secret`。
## 干净卸载
每个卸载命令都会先备份目标配置文件，然后只删除 memX 自己写入的条目。Claude Code 和 Codex
清理会同时停止 managed local service、卸载 native plugin、移除本地 marketplace，并删除生成的
marketplace snapshot。
OpenClaw 清理会额外删掉残留的 `memx` / `memory-memx` slot、allow 和 entry 引用，并在
OpenClaw 仍能识别插件时 best-effort 删除当前和旧版插件文件。
```bash
npx -y -p github:NeoLi00/memX memx uninstall openclaw
npx -y -p github:NeoLi00/memX memx uninstall codex
npx -y -p github:NeoLi00/memX memx uninstall claude-code
```
加 `--dry-run` 可以预览；如果使用非默认配置路径，加 `--config /path/to/config`。
## memX 能做什么
- **长期记住工作上下文**：项目决策、用户偏好、任务状态、长 source segments 和原始证据都能
保留来源关系。
- **连接相关对象**：项目、仓库、工具、文件、资源、卡点和结果可以形成实体与关系边。
- **学习协作模式**：重复出现的证据可以变成可复用建议，同时保留支撑来源。
- **自动维护记忆**：纠错可以替代旧事实，稳定证据可以提升，过期任务状态不会长期压过当前状态。
- **紧凑召回证据**：事实、事件、状态、片段、关系、资源和已学习模式一起参与召回，再压成小段
evidence 注入。