项目概览

NylonME 是面向 AI Agent 的单机记忆引擎。它把一条记忆建模为多股“丝” （事实、情感、时序、关系、置信、频次）的编织体，记忆节点之间以加权边构成网状图， 而不是层级树。

检索不是 top-k 相似度匹配，而是情境共振：从种子节点出发，按关联强度 × 情境匹配 × 实时张力在图上扩散激活，并受全局激活预算约束。不使用的记忆会沿张力遗忘曲线自然沉降。

当前版本 v0.4.1，已具备完整的生产化能力：REST/OpenAPI 网关与内置 Web 控制台、Python SDK、 LangChain / LlamaIndex 集成、租户隔离与 API key 鉴权、审计事件流、TLS 加密传输、 周期快照备份、Docker 与 Helm 一键部署，以及跑在 Android / iOS App 进程内的移动端 SDK。

概念：空间 / 记忆库 / 钥匙

只需要三个词，其余都是管道细节：

• 空间（tenant）——安全边界。一把 key 开一个空间，请求里写别的空间会被直接拒绝；
• 记忆库（owner）——空间里的记忆分区。同一个库的记忆互相联想、一起被共振召回， 库与库之间完全隔离。库名只是个文件夹名，不带权限——项目用项目 slug，个人跨项目用 dev-你的名字；
• 钥匙（key）——唯一凭证，没有账号密码。档位三选一 read / write / admin。把 key 贴进控制台顶栏，旁边的芯片立刻回答「我是谁」 （背后是 GET /v1/whoami）。

小团队共用一台引擎？一个空间（default）+ 每人/每项目一个库，就是设计好的用法。完整版见仓库 docs/CONCEPTS.md。

最快上手：免 Docker 安装

Windows 用户不需要 Docker，也不需要 Rust 工具链。从 GitHub Releases 下载对应平台的压缩包，解压即用：

# Windows：解压后进入目录，一条命令启动
# （数据自动落在 %USERPROFILE%\.nylonme\data，v0.4.1 起）
nylon-engine.exe serve 127.0.0.1:50051

# 浏览器打开控制台
start http://127.0.0.1:50052

# Linux / macOS 同理：
./nylon-engine serve 127.0.0.1:50051

三步：解压 → 运行 → 打开控制台。v0.4.1 起数据固定落在 ~/.nylonme/data， 换目录、升级都不会"丢记忆"。每个压缩包里都有三个程序：nylon-engine（引擎）、 nylon_cli（命令行写入/召回）、smoke_client（自检，跑完打印 SMOKE_OK）。

这一步不需要任何 key——单机默认是开放模式，console、CLI、MCP 全部直连。 key 只在团队共享引擎、开启鉴权时才用得上（见下文「多租户与鉴权」）；客户端怎么带 key， 每个示例里都有标注。想加语义召回（ollama 嵌入模型）看「运行引擎」一节。

只想给 Claude Code / Cursor / Codex 接记忆？连 serve 都省了——MCP stdio 模式引擎内嵌在进程里，一段配置直接接入，见「MCP 接入」。

Docker 一键部署

无需 Rust 工具链，一条命令启动引擎 + ollama（自动拉取 bge-m3 嵌入模型）。 首次启动需要几分钟（release 构建 + 模型下载）：

git clone https://github.com/nylon-memory/NylonME.git
cd NylonME
docker compose up -d

# 跳过本地构建，直接拉预编译镜像
docker compose -f docker-compose.prebuilt.yml up -d

启动后打开 Web 控制台 http://localhost:50052——gRPC 在 :50051，REST/OpenAPI 与控制台在同一个 HTTP 端口。数据持久化在 nylon-data 命名卷。启用 LLM 编织层前先设好 NYLON_LLM_API_KEY（默认 DeepSeek）。Kubernetes 环境可直接使用仓库内置的 Helm chart（helm/ 目录）。

MCP 接入

nylon-engine mcp 以 stdio 方式讲 Model Context Protocol，引擎内嵌在进程里， 不需要守护进程、不开端口，数据自动落到 ~/.nylonme/data。Claude Code、Cursor、 Codex、VS Code Copilot 等所有 MCP 客户端通用。本机内嵌模式同样不需要 key， 配置里没有 key 字段是正常的：

{
  "mcpServers": {
    "nylonme": {
      "command": "/path/to/nylon-engine",
      "args": ["mcp"],
      "env": { "NYLON_OWNER": "my-project" }
    }
  }
}

Codex 配置

[mcp_servers.nylonme]
command = "/path/to/nylon-engine"
args = ["mcp"]

[mcp_servers.nylonme.env]
NYLON_OWNER = "my-project"

接入后 Agent 会获得四个工具：memory_weave（沉淀事实）、 memory_resonate（回忆相关记忆）、memory_get（按 ID 读取）、 memory_feedback（失败回答反馈，驱动定向反思补全）。

零二进制：/mcp HTTP 端点

引擎作为共享守护进程运行时，HTTP 端口同时提供 Streamable HTTP MCP 端点 http://<host>:50052/mcp。支持远程 MCP 的客户端只用一个 URL 即可接入， 本机不需要二进制、不需要桥接进程：

{
  "mcpServers": {
    "nylonme": {
      "url": "http://192.168.1.5:50052/mcp",
      "headers": { "x-api-key": "nyl_..." }
    }
  }
}

端点与 gRPC/REST 共享同一个进程内引擎（同一份数据），无状态、不需要会话亲和；开启鉴权后要求 write 档位的 key，并校验 key 绑定的空间。公网部署时用 NYLON_MCP_ALLOWED_HOSTS 固定 Host 白名单。

多机共享一份记忆库时，也可以走远程桥接模式：设 NYLON_SERVER=host:50051（可选 NYLON_API_KEY），stdio MCP 调用会转发到远端引擎，本机不再内嵌引擎。仓库还内置 DSH 插件（ plugins/dsh-nylonme-memory），装上后每个 DSH 会话自动获得长期记忆。

升级指南

一条黄金法则：换二进制，不动数据目录。记忆都在数据目录里 （graph.snp + wal.log + audit.jsonl）， 不在可执行文件里。磁盘格式跨版本兼容（快照魔数校验 + WAL CRC 自愈合），升级不需要导出导入。

“升级后崩了”九成是这三个原因之一：

• 解压到了新文件夹启动——serve 模式的默认数据目录 ./nylon-data 相对于启动目录，换个地方启动就是一个空库（旧数据还在老地方，没丢）。 v0.4.1 起已在代码里根治：./nylon-data 存在才沿用， 否则落到 ~/.nylonme/data 并打印启动警告，不再静默起空库；
• 直接覆盖了正在运行的 nylon-engine.exe，或旧进程没退导致 50051/50052 端口冲突；
• 启动脚本里的环境变量（NYLON_DATA_DIR、NYLON_EMBED_URL 等）没跟过来。

正确姿势：停旧进程 → 确认数据目录位置（启动日志里的 data= 路径）→ 备份一份 → 把新二进制解压到原目录覆盖 → 启动后核对 data= 路径不变。 推荐把 NYLON_DATA_DIR 固定成绝对路径，升级从此变成纯换二进制。 完整五步清单与故障对照表见仓库 docs/UPGRADE.md。

运行引擎

预编译二进制可直接从 GitHub Releases 下载，也可以从源码构建：

git clone https://github.com/nylon-memory/NylonME.git
cd NylonME/engine
cargo build --release -p nylon-engine --example nylon_cli

# 最小运行（嵌入关闭，LLM 关闭）
NYLON_DATA_DIR=./data ./nylon-engine serve 0.0.0.0:50051

# 推荐：接入 ollama 嵌入模型，启用语义召回
ollama pull bge-m3
NYLON_DATA_DIR=./data \
NYLON_EMBED_URL=http://localhost:11434 \
NYLON_EMBED_MODEL=bge-m3 \
NYLON_EMBED_DIMS=1024 \
./nylon-engine serve 0.0.0.0:50051

# 可选：接入理解层，做 session 级事实编织
NYLON_LLM_URL=https://api.deepseek.com/v1/chat/completions \
NYLON_LLM_MODEL=deepseek-v4-flash \
NYLON_LLM_API_KEY=<your-key> \
NYLON_LLM_THINKING_OFF=1 \
./nylon-engine serve 0.0.0.0:50051

启动时引擎会探测嵌入通道的健康度，GET /v1/stats 返回的 embedder_status 为三态之一：ok / degraded （附 embed_failures 计数与 embedder_last_error）/ disabled。嵌入服务挂了不再静默退化成纯词面检索。

Windows 踩坑提示：开着系统代理时，HTTP 客户端可能把 http://127.0.0.1:11434 也走代理，ollama 返回 502 Bad Gateway—— 改用 http://localhost:11434 即可（代理绕过名单匹配的是 localhost）。

Web 控制台与 REST

引擎二进制自带零安装 Web 控制台和 REST API（默认 http://127.0.0.1:50052，NYLON_HTTP_ADDR=off 关闭）。

控制台有七个视图：总览（引擎统计卡片、最新记忆、活动流、张力分布直方图）、 记忆（浏览/过滤，实时张力）、图谱（零依赖力导向记忆网络图，可按张力或 owner 着色）、共振（调试查询：种子、分数、自适应深度，带一键回答质量反馈条， 反馈驱动空闲反思）、编织（单条 + 会话批量）、审计、 Team（签发 / 吊销 key、按成员看活动）。 节点抽屉内置遗忘操作（DELETE /v1/nodes/{id} 打墓碑）。 与 gRPC/MCP 同一个引擎、同一条写路径，内置深色/浅色主题和中英文界面切换。

REST 端点与 gRPC 契约一一对应，OpenAPI 规范见仓库 docs/api/openapi.json。

Python SDK 与集成

nylon-sdk 把 gRPC 契约封装成同步 + 异步客户端：

pip install ./sdk/python    # 从本仓库安装

from nylon_sdk import NylonClient

with NylonClient("127.0.0.1:50051", owner="alice") as client:
    client.weave("Alice prefers window seats on business trips")
    for node in client.resonate("flight seat preference").activated:
        print(node.filaments.fact)

LangChain / LlamaIndex

pip install "nylonme-integrations[langchain]"   # 或 [llamaindex]

from nylonme_integrations.langchain import NylonMeRetriever

retriever = NylonMeRetriever(target="127.0.0.1:50051", owner="alice")
docs = retriever.invoke("flight seat preference")

移动端 SDK（Android / iOS，端上运行）

nylon-mobile 是进程内引擎的 UniFFI 绑定：不开端口、不走 gRPC、 无网络请求，记忆数据完全留在 App 沙箱里。它只依赖四个纯 Rust 核心库 （nylon-core / nylon-graph / nylon-storage / nylon-embed），编织、共振、 检索与服务端共享同一份 nylon-service 实现——两端行为一致，包括 CJK 查询分词。Kotlin / Swift 绑定由 UniFFI 生成，release 按 tag 产出 .so / xcframework 与绑定包。

生命周期挂接（Kotlin）

// Application.onCreate 里用 ProcessLifecycleOwner 挂接一次
class MemoryEngineHolder(context: Context) : DefaultLifecycleObserver {
    private var engine: MobileEngine? = null

    @Synchronized
    fun engine(): MobileEngine = engine ?: MobileEngine(
        MobileConfig(
            dataDir = File(appContext.filesDir, "nylon/db").absolutePath,
            owner = "me",                // 端上单用户，固定即可
            embedModelPath = model,      // 不要语义通道就和 vocab 一起传 null
            embedVocabPath = vocab,
        )
    ).also { engine = it }

    override fun onStop(owner: LifecycleOwner) { engine?.checkpoint() } // 退后台
    fun destroy() { engine?.shutdown(); engine = null }                 // 主动释放
}

数据安全契约

WAL-first 写入（组提交 + fsync）保证写成功即已持久；进程被杀后下次启动自动重放恢复。 自动 checkpoint 默认每 32 次写或 300s（脏时）触发，可用 autoCheckpointWrites / autoCheckpointSecs 调整。 checkpoint 只影响恢复速度，不影响正确性。

真机跑分（荣耀 NTH-AN00 / aarch64）

词面通道：20 条中英混合记忆、WAL 跨进程恢复后，8 个中文查询全部 top-1 命中， 单次共振约 55µs。端上语义通道（bge-small-zh 量化模型 24MB，tract 纯 Rust 推理）：10 个查询全部 top-1，包括零字面重叠的纯语义探针；单次共振约 0.3–1.2s（含查询嵌入，骁龙 778G 级 CPU）。模型须先剥 value_info（仓库 scripts/prepare_onnx_model.py），部署与 iOS 接入细节见仓库 engine/crates/nylon-mobile/ 的 README 与 INTEGRATION.md。

多租户与鉴权

引擎支持租户隔离与 API key 鉴权，三档权限 read < write < admin：

• 未配置任何 key：开放模式（单机默认），行为与历史版本一致；
• 设 NYLON_API_KEYS_FILE（或内联 NYLON_API_KEYS）后启用鉴权： HTTP 请求带 x-api-key 头或 Authorization: Bearer， gRPC 带 x-api-key metadata；
• 每把 key 绑定一个租户，租户不匹配直接拒绝；admin 可用通配 * 租户。

# 首次启动生成一把 admin key 并打印一次
# 之后给同事发 key（key 表热加载，无需重启）
nylon-engine keys add --tenant prod --scope write --name alice   # -> nyl_...（仅显示一次）
nylon-engine keys list        # 掩码列表，带成员别名
nylon-engine keys revoke nyl_aaa    # 按完整 key 或唯一前缀吊销

--name 别名给 key 挂上成员身份：开启 NYLON_AUDIT 后每条审计事件都带 actor=alice，GET /v1/audit?actor=alice 就能按人看活动。 管理员也可以走 REST——GET /v1/keys（掩码列表）、POST /v1/keys （完整 key 仅返回一次）、DELETE /v1/keys/{prefix}——控制台 Team 视图就是这套接口的可视化封装。MCP 桥接和 CLI 会自动转发 NYLON_API_KEY。

TLS 加密传输

默认明文（只监听回环时可接受）。设两个环境变量，gRPC 端口和 HTTP/UI 网关同时切 TLS， 不需要在前面架 nginx/Caddy；只设一个是启动错误，不存在半加密状态：

# 两个变量必须成对设置，gRPC 与 HTTP/UI 双端口同时切 TLS
export NYLON_TLS_CERT=/etc/nylonme/tls/server.pem   # PEM 证书链
export NYLON_TLS_KEY=/etc/nylonme/tls/server.key    # PEM 私钥
nylon-engine serve 0.0.0.0:50051
# -> gRPC listening on 0.0.0.0:50051 (grpcs, ...)
# -> HTTP/UI listening on https://0.0.0.0:50052 (TLS)

# 局域网快速自签名：
openssl req -x509 -newkey rsa:2048 -nodes -days 825 \
  -keyout server.key -out server.pem \
  -subj "/CN=192.168.1.5" -addext "subjectAltName=IP:192.168.1.5,DNS:nylonme.lan"

# 客户端用 https:// URL 接入；自签名时信任 CA：
export NYLON_SERVER="https://192.168.1.5:50051"
export NYLON_TLS_CA=/path/to/server.pem

Web 控制台直接用 https://host:50052 打开（自签名证书接受一次警告即可）。 DSH 插件用同一个 https:// 地址；如果 Node 不认自签名 CA，把 CA 装进系统信任库或设 NODE_EXTRA_CA_CERTS。明文客户端连 TLS 端口会在握手阶段失败（设计如此），反之亦然。 静态加密（at-rest）在路线图上（L2.6），诚实安全模型见仓库 SECURITY.md。

备份与恢复

RocksDB 支持周期快照 + WAL 截断（NYLON_CHECKPOINT_SECS，默认 600 秒）， 也可 POST /v1/checkpoint 手动触发，便于热备份。完整步骤见仓库 docs/BACKUP_RESTORE.md。

CLI 快速开始

--owner 用来隔离记忆命名空间，--tenant 默认是 codex。

export NYLON_SERVER=http://127.0.0.1:50051
export NYLON_API_KEY=nyl_...   # 仅当引擎开启鉴权时需要；单机开放模式不用设

# 写入第一条记忆
./nylon_cli weave --owner alice --task travel \
  --fact "Alice prefers window seats on business trips"
# -> NODE_ID=0

# 召回相关记忆
./nylon_cli resonate --owner alice \
  --query "flight seat preference" --budget 5
# -> ACTIVATED=1
# -> 0  0.812  Alice prefers window seats on business trips

好的事实应当是包含名字、数字和路径的自包含句子。永远不要把密钥、密码等敏感信息写入记忆。

调参旋钮

仓库结构

NylonME/
├── proto/            # nylon/v1 gRPC 契约
├── engine/           # Rust workspace（9 个 crate）
├── sdk/python/       # Python SDK（nylon-sdk）
├── integrations/     # LangChain / LlamaIndex 适配器
├── plugins/          # DSH 等 Agent 平台插件
├── docs/             # 指南与 API 规范
└── helm/             # Kubernetes 部署

路线图

• 已完成：双层写入引擎（WeaveSession）、词面 + 向量混合种子、自适应联想深度、 查询向量重排、异步常识反思、HNSW、RocksDB 持久化、gRPC 服务化、 LoCoMo 召回 86.0% / 问答 82.9%、LongMemEval-S any-hit 99% / 端到端 83.0%、 REST/OpenAPI 网关 + Web 控制台（七视图 + 图谱 + 反馈条 + Team key 管理）、Python SDK、 LangChain/LlamaIndex 集成、租户隔离、API key 鉴权（CLI/REST/控制台三入口热加载）、 审计事件流、TLS 加密传输、周期快照与备份、Docker 一键部署、Helm chart、DSH 插件。
• 下一步：静态加密（at-rest，L2.6）、交叉编码器 reranker、百万节点内存 profiling、论文与博客系列。