★ FEATURED ARTICLE 人工智能AI AgentAgent 记忆RAGMCP 服务【免费下载链接】agent-memoryMemory 是一款面向 AI 智能体的长期记忆模块为运行在 openJiuwen 框架上的智能体提供记忆提取、存储、检索与迁移能力。项目地址https://gitcode.com/openJiuwen/agent-memory点击查看免费下载本篇基于 agent-memoryopenJiuwen 智能体长期记忆模块官方文档梳理其部署体系先厘清「容器化部署」与「SDK 部署」两类运行形态及各自的可选项再给出按需求选型的对照表最后深入默认内存栈、HTTP 与MemoryAPI的对齐规则、HTTP 服务安全边界等能力边界并结合仓库内 Docker Compose 配置与源码实现给出可直接复制的启动、验证与排障操作。读完本篇你可以为开发联调、内嵌集成或常驻服务场景选对部署形态并安全地拉起、验证一套 agent-memory 记忆服务。1. 部署形态总览agent-memory 的部署方式可以归为两大类容器化部署与SDK 部署。整体拓扑如下agent-memory ├── 容器化部署 │ ├── 远程嵌入/精排模型 Redis / Milvus / Elasticsearch │ ├── 本地嵌入/精排模型 Redis / Milvus / Elasticsearch │ └── 远程嵌入/精排模型 PostgreSQL / pgvector / Elasticsearch └── SDK 部署Python 进程运行内核 ├── 存储进程内内存 / Docker 后端存储 └── 调用直接调用 MemoryAPI / 启动本地 HTTP 服务1.1 容器化部署容器化部署使用 Docker Compose 同时运行 agent-memory HTTP 服务与所需存储后端。应用、连接配置和后端依赖被组织在同一个 Compose profile 中适合希望快速得到一套完整服务、并尽量减少宿主机 Python 环境差异的场景。当前仓库在 deploy/docker 下提供三套相互独立的完整 Compose profileProfile模型形态真源与索引后端对外形态onlineLLM、嵌入、精排均调用远程服务Redis Milvus ElasticsearchHTTP默认端口8137local嵌入、精排在应用容器内加载本地 BGE 模型LLM 默认仍为远程 DashScopeRedis Milvus ElasticsearchHTTP默认端口8137postgresLLM、嵌入、精排均调用远程服务PostgreSQL KV pgvector ElasticsearchHTTP默认端口8137两个容易误解的点需要注意文档中的“本地模型”仅指嵌入与精排模型本地运行当前localprofile 没有内置本地 LLMPostgreSQL 是存储选型与模型形态是两个正交维度仓库当前没有提供“本地嵌入/精排 PostgreSQL”的现成组合 profile。从 deploy/docker/README.md 的选型表还能看到各角色实现角色实现形态LLMDashScope OpenAI-compatible API默认关闭思考外部凭LLM_API_KEY嵌入bge-m31024 维在线模式HTTP/v1/embeddings本地模式进程内 FlagEmbedding精排bge-reranker-v2-m3在线模式HTTP/rerank本地模式进程内 FlagEmbedding向量召回Milvuspostgresprofile 改用 pgvector容器关键词召回ElasticsearchBM25容器真源Redispostgresprofile 改用 PostgreSQL KVStore容器召回采用「向量 关键词」双通道图召回关闭。HTTP 以POST /v1/MemoryAPI method一一暴露全部公开方法单个内核实例随进程生命周期常驻、跨请求保持状态。1.2 SDK 部署SDK 部署是指由使用方的 Python 进程安装并装配jiuwen_memory内核可以直接调用MemoryAPI也可以在该进程内启动仓库提供的本地 HTTP 服务。当前jiuwen_memory_entry/sdk还没有独立封装的 SDK 客户端或启动器。因此“SDK 部署”是对Python 包直接集成方式的统称稳定入口是 jiuwen_memory/api/memory_api_impl/assembly.py 中jiuwen_memory.api.assemble()返回的MemoryAPI。从源码看assemble()的签名接受policies、kv与config三个可选参数不传任何参数即落入内置离线配置见第 4.1 节传入配置字典或Config对象后可在同一 Python 进程内把存储路由到 PostgreSQL/pgvector/Elasticsearch 等真实后端。SDK 部署有两个独立的选择维度存储方式直接调用 MemoryAPI本地 HTTP 服务进程内内存最小开发、测试、功能验证HTTP 协议联调、跨语言快速接入Docker 后端存储Python 应用内嵌记忆能力并持久化数据本地常驻服务、跨进程访问并持久化数据2. 选型指南按需求对号入座官方给出的选型对照表完整如下需求建议方式原因最快验证 add/searchSDK 内存 直接 MemoryAPI无外部服务启动成本最低联调 HTTP 请求格式SDK 内存 本地 HTTP无外部存储也能验证 HTTP 接口Python 应用内嵌且需要持久化SDK Docker PostgreSQL/pgvector/ES MemoryAPI不增加 HTTP 跳转后端数据可持久化本机提供跨进程 HTTP 服务且需要持久化SDK Docker PostgreSQL/pgvector/ES 本地 HTTP应用在宿主机存储在容器中便于开发调试一条命令拉起完整服务容器化部署应用与后端依赖统一由 Compose 管理嵌入和精排数据不能发送到远程模型服务容器化localprofileBGE 嵌入与精排在应用容器内运行希望减少 Milvus、etcd、MinIO 组件数量容器化postgresprofilepgvector 替代 Milvus 及其依赖3. 能力与边界3.1 默认内存栈不传配置直接调用assemble()时系统使用内置离线配置OFFLINE 栈CompositeStorage统一承载 Storage 接口KV、Vector、Fulltext、Graph Store 均为进程内实现嵌入使用 hashing 实现不依赖外部模型LLM 使用 echo精排使用 overlap进程退出后内存数据全部丢失。这与 jiuwen_memory/config/defaults.py 中的默认配置一致embedder: {_D: {target: hashing, params: {tokenizer: _D}}}, llm: {_D: echo}, reranker: {_D: {target: overlap, params: {tokenizer: _D}}},该模式适合功能开发和测试不应当被当作持久化部署。3.2 HTTP 与 MemoryAPI 一一对齐本地 HTTP 服务是MemoryAPI上的一层 JSON 适配公开其全部 36 个方法命令集直接来自MemoryAPI.__abstractmethods__见 CLI 设计说明。规则如下每个方法使用POST /v1/method_name请求字段名称、嵌套结构、必填项和默认值与同名MemoryAPI方法保持一致成功响应直接序列化原方法返回值不增加另一层业务响应或任务语义。HTTP 边界只做两类必要转换Scope、Context、MemoryPatch等 Python 对象使用同结构 JSON 对象表达枚举用字符串值、时间用 ISO 8601 字符串表达security不接受请求体传入而是由认证边界根据认证 runtime 的认证结果构造后注入dev 模式也通过配置装配完整SecurityRuntime并使用统一BindingPolicy。同步方法在请求线程内直接调用异步方法如add_async、batch_add_async由 HTTP 入口等待同名异步方法完成后返回原结果不改造成后台 job。选择 Python 直接调用通常是为了进程内低延迟、静态类型和 Python 对象而不是为了弥补 HTTP 的常规接口缺口。四个记忆新增入口add、add_async、batch_add、batch_add_async支持请求级system_metadata.coords对象按字符串键值单独校验批量逐项不能携带该键。归属判定仍需内核 router、空间及权限配置且装配期存在一致性校验assembly.py 中的_reject_routing_without_space_authorization会拒绝“判定表已配置而空间治理未开启”的组合直接抛出带修复建议的ValidationError。3.3 当前 HTTP 服务的安全边界仓库提供的是基于 Python 标准库ThreadingHTTPServer的参考服务不内置 TLS 或多进程管理。关键边界如下业务请求必须先建立可信RequestSecurityContext请求体中的security、actor_*、identity等身份声明会被拒绝默认required模式下生产 runtime 未装配时业务接口返回 503不会降级信任请求体身份本地功能测试可显式启用dev模式未配置身份映射时忽略认证头并使用固定local/developerROOT 身份配置http.dev_identities后可按 Bearer 或 X-API-Key 测试标识选择服务端预设身份缺失或未知标识返回 401。两种模式都执行 MemoryAPI 授权不允许通过请求体伪造身份仅固定 DEV 且未配 security/permission 时临时注入 allow_all映射 DEV 保留真实权限判定。具名管理员/ROOT 角色权限及受控委托待 PR2 Authorizer 接管。绑定地址校验在标准启动入口中强制执行。从 jiuwen_memory_entry/http_server/__main__.py 看HttpServer.serve()在创建 socket 之前先调用_check_binding(host)读取认证器的requires_loopback_binding要求再用 runtime 的binding_policy校验。因此 dev 模式默认只允许回环地址127.0.0.1、::1、localhost。注意仅复用handler_cls()在外部自行构造服务器不会执行该校验嵌入方必须自行保证绑定策略。DEV 没有环境变量旁路不能监听0.0.0.0容器、共享网络或生产部署必须使用required并配置 api_key / trusted 认证器显式声明可远程暴露再由前置网关补充 TLS、访问控制和流量保护。4. 不单独视为部署方案的接入方式以下形态是接入面而非独立部署选项CLI提供全部 36 个 API 同名命令参数名和 JSON 结构与 MemoryAPI 一致。本地模式直接调用 API使用--server时原样发送 HTTP 请求不保留旧参数和返回值转换。本地测试须显式--auth-mode dev远程认证由服务端决定。详见 CLI 设计说明。MCP可通过 stdio 或 streamable HTTP 暴露工具本质上是协议接入面其底层部署仍需选择内存或真实存储。jiuwen_memory_entry/sdk当前只有包目录骨架没有形成独立于jiuwen_memory.api的 SDK 产品层。Kubernetes / Helm / systemd当前仓库没有提供对应的现成部署清单。5. 容器化部署实操5.1 前置条件Docker docker compose v2分配给 Docker 的内存≥ 20 GB若默认配额偏低请在 Docker Desktop 设置中上调全栈常驻约占用 13–18 GB网络可达拉取镜像、访问云端 LLM 端点在线模型模式还需能访问EMBEDDER_BASE_URL/RERANKER_BASE_URLpostgres模式会拉取 PostgreSQL 16 pgvector 0.8.3 镜像首次创建数据卷时自动执行 scripts/pg_schema.sql本地模型模式需通过 ModelScope 下载 bge 模型约 4 GB无 GPU 时本地模型模式走 CPU 推理功能可用但批量写入与高并发场景吞吐受限。5.2 预下载模型仅本地模型模式必需嵌入/精排使用本地 bge 模型不在容器启动时联网下载。直连 HuggingFace 在部分网络环境下并不稳定且下载失败时索引构建会静默降级捕获嵌入异常后记录日志并继续导致写入看似成功、召回却为空。建议在宿主机预先下载至deploy/docker/models再由 compose 挂载到容器/models-local离线加载cd deploy/docker/local ./download-models.sh # 等价手动步骤 # pip install modelscope # modelscope download --model BAAI/bge-m3 --local_dir ../models/bge-m3 # modelscope download --model BAAI/bge-reranker-v2-m3 --local_dir ../models/bge-reranker-v2-m3下载完成后deploy/docker/models/下应包含bge-m3/与bge-reranker-v2-m3/两个目录local/.env中的EMBED_MODEL/RERANK_MODEL默认即指向容器内的/models-local/...无需修改。5.3 启动三套 profile在线模型模式不安装torch/FlagEmbedding/transformers不挂载本地模型目录cd deploy/docker/online cp .env.example .env # 编辑 .env至少填入 LLM_API_KEY、MODEL_API_TOKEN、EMBEDDER_BASE_URL、RERANKER_BASE_URL docker compose up -d --build注意 URL 约定EMBEDDER_BASE_URL必须包含/v1如https://models.example.com/v1RERANKER_BASE_URL不要包含/rerank。LLM 默认target: dashscopeLLM_ENABLE_THINKINGfalse会通过 DashScope Adapter 发送extra_body.enable_thinkingfalse设为null则完全不发送该厂商字段。PostgreSQL 模式保留在线模型 API 与 Elasticsearch仅把 Redis KV、默认 Vector、L0 Vector、L1 Vector 替换为同一个 PostgreSQL 实例中的四张独立表cd deploy/docker/postgres cp .env.example .env # 编辑 .env至少填写模型凭据和模型端点生产环境还应修改数据库密码 docker compose config docker compose up -d --build该模式启动pgvector/pgvector:0.8.3-pg16不再启动 Redis、Milvus、etcd 或 MinIO。扩展和四张表由/docker-entrypoint-initdb.d/10-agent-memory.sql在空数据卷首次启动时创建因此配置固定auto_create_schema: false/create_extension: false默认 DDL 为publicschema、1024 维、COSINE/HNSW。初始化脚本不会在已有数据卷上重复执行调整 schema、表名或向量维度时应在首次启动前同步修改.env、config.yml和初始化脚本。本地模型模式cd deploy/docker/local cp .env.example .env # 编辑 .env至少填入 LLM_API_KEY docker compose up -d --build首次启动顺序etcd / MinIO 就绪 → Milvus、Elasticsearch、Redis 健康后应用才启动depends_on: service_healthy。bge 模型从挂载的/models-local直接加载、全程不联网模型在应用首次收到请求时载入内存该次请求耗时较长此后常驻复用。查看状态与日志docker compose ps docker compose logs -f agent-memory5.4 验证服务默认JIUWEN_MEMORY_HTTP_AUTH_MODErequired在生产认证 runtime 尚未装配时业务接口返回 503。仅本机功能测试时把当前 profile 的.env改为JIUWEN_MEMORY_HTTP_AUTH_MODEdev HTTP_BIND_ADDRESS127.0.0.1然后执行docker compose up -d --force-recreate agent-memory。未配置身份映射时 dev 固定生成local/developerROOT 身份、忽略认证头但仍执行 MemoryAPI 授权多用户测试可在挂载配置中加入与memory_api同级的http.dev_identities用 Bearer 或 X-API-Key 选择预设身份详见 Config 指南。两种模式都不得暴露到共享网络或生产环境。# 健康检查 curl http://localhost:8137/healthz # 写入一条记忆首次请求会触发模型载入内存需等待数秒 curl -X POST http://localhost:8137/v1/add \ -H Content-Type: application/json \ -d {content:用户偏好用 Python 写代码,scope:{org:local,space:,user:developer,agent:,session:}} # 召回 curl -X POST http://localhost:8137/v1/search \ -H Content-Type: application/json \ -d {query:用什么语言,context:{scope:{org:local,space:,user:developer,agent:,session:},extensions:{}},top_k:5}其他接口参见 S02 MemoryAPI 规约。5.5 端口规划服务端口用途agent-memory127.0.0.1:8137默认宿主机发布地址HTTP APIelasticsearch9200ES RESTmilvus19530 / 9091SDK / healthzPostgreSQLpostgresprofile${POSTGRES_PORT:-5432}数据库连接 / 排障5.6 常见调整换 LLM 厂商同时修改config.yml的llm.default.target和.env中的LLM_BASE_URL/LLM_MODEL。阿里云用dashscope通用 OpenAI-compatible 端点用openai不要只换 URL 而保留其他厂商的专属参数。换在线模型服务改online/.env的EMBEDDER_BASE_URL/RERANKER_BASE_URL/MODEL_API_TOKEN。降低内存占用将vector_store改用 Milvus Litepymilvus 内嵌、文件存储在对应模式目录的config.yml中把uri改为本地文件如./milvus.db并从 compose 中移除 etcd / minio / milvus 三个服务。Milvus Lite 不适用于生产环境。提升中文关键词检索精度为 Elasticsearch 安装 IK 分词插件需自建 ES 镜像默认 standard 分析器对中文按单字切分。5.7 配置文件挂载与分层机制服务读哪个配置由两处决定模式目录下的docker-compose.yml把宿主机文件挂到容器/config/config.yml同目录Dockerfile的CMD把该路径作为参数传给__main__.py——真正决定“用哪个文件”的开关是 compose 里的挂载源# online/docker-compose.yml → 服务 agent-memory volumes: - ./config.yml:/config/config.yml:ro # 左 宿主机文件右 容器内固定路径配置是两级命名空间且会合并覆盖内置默认纯内存离线栈故配置文件只需写“与默认不同”的部分。新增并启用一个配置文件分三步在对应模式目录下新建文件如online/config.lite.yml只写要改动的命名空间/参数把 compose 的挂载源整体替换过去无需改 CMD重新创建容器使挂载生效改 compose 须 recreaterestart不够docker compose up -d agent-memory。进阶的多文件分层__main__.py接收多个配置路径依次叠在内置 OFFLINE 之上、靠后覆盖靠前。但注意文件之间是顶层键浅合并——后一个文件的memory_api会整体替换前一个的不做深合并「只覆盖内核里某几项」应写在单个文件的memory_api内分层更适合覆盖profile/policies这类顶层键。不走 docker 直接本地功能测试可用scripts/run-server.sh --auth-mode dev 配置路径 [更多路径…]。5.8 关停与清数据docker compose down # 停止服务保留数据卷 docker compose down -v # 停止服务并删除当前 profile 声明的本地数据卷在postgresprofile 中执行down -v会同时删除 Elasticsearch 与 PostgreSQL 数据卷包括所有 KV 和向量数据仅停止服务请使用不带-v的命令。6. 相关文档容器化部署英文SDK 部署英文Storage API 文档Retrieval API 文档Docker Compose 原始说明CLI 与 MemoryAPI 对齐说明赞分享人工智能AI AgentAgent 记忆RAGMCP 服务【免费下载链接】agent-memoryMemory 是一款面向 AI 智能体的长期记忆模块为运行在 openJiuwen 框架上的智能体提供记忆提取、存储、检索与迁移能力。项目地址https://gitcode.com/openJiuwen/agent-memory点击查看免费下载相关推荐一段录音想换成任何风格YuE2 零样本翻唱全解三步做出 48kHz 成品一个模型都不用训一段录音想换成任何风格YuE2 零样本翻唱全解三步做出 48kHz 成品一个模型都不用训 你手里有一段录音弹唱、手机录的 demo、老磁带转录都行。你人工智能音乐生成媒体生成音频大模型本地部署AI 技能模型评测agent-memory Docker Compose 容器化部署实战在线模型、本地模型与 PostgreSQL 三套后端栈全解析agent memory Docker Compose 容器化部署实战在线模型、本地模型与 PostgreSQL 三套后端栈全解析 本文基于 agent me人工智能AI AgentAgent 记忆RAGMCP 服务用 VulFi 挖掘真实固件漏洞从危险函数定位到缓冲区溢出的完整实战用 VulFi 挖掘真实固件漏洞从危险函数定位到缓冲区溢出的完整实战 固件漏洞挖掘是安全研究中最考验耐心的环节面对动辄几十 MB 的二进制固件如果全靠人工应用安全逆向工程漏洞扫描开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
