agent-memory: Instructions file for Codex

agent-memory

结构化记忆系统 —— 负责记忆的摄入、构建、检索与生命周期管理。

项目结构

.
├── jiuwen_memory/      # 内核源码（接口/接入/构建/检索/编排/存储/共享插件）
├── tests/              # 测试（unit / integration，路径镜像 jiuwen_memory/）
├── jiuwen_memory_entry/  # 接入形态（CLI / HTTP / MCP / SDK；whl 独立顶层）
├── docs/               # 设计文档归档（design / specs / features）
├── jiuwen_memory_adapter/ # 外部 agent 插件适配（whl 独立顶层）
├── deploy/             # 部署配置（docker / local）
├── evaluation/         # 评测框架（benchmark / metrics / smoke_test）
├── examples/           # 使用示例与快速上手
├── scripts/            # 运行脚本（run-cli / run-server / run-mcp，见「环境与运行」）
└── .claude/            # AI 辅助工具配置（rules / skills / settings）

AGENTS.md 层级

AGENTS.md                        ← 本文件：项目入口，目录结构 + 测试/代码风格/归档/提交约定
jiuwen_memory/AGENTS.md          ← 内核总览：模块地图 + 数据流 + 架构铁律 + 子模块 AGENTS.md 创建规则
jiuwen_memory/<subdir>/AGENTS.md ← 模块本地：代码目录结构、文件关系、入口、行为铁律、本地约束
docs/AGENTS.md                   ← 文档归档规约：文档目录结构、命名规则、文档骨架、提交约定

职责边界：

• 本文件：新人入口，描述项目是什么、怎么构建、代码风格、提交规范
• jiuwen_memory/AGENTS.md：内核开发者入口，描述模块间关系和数据流走向
• jiuwen_memory/<subdir>/AGENTS.md：模块本地规约，只写相对稳定的结构性约束（模块职责边界、行为铁律、本地约束、文件关系），不写会频繁变化的特性设计
• docs/specs/：跨模块接口规约（接口契约、协议、不变量、公共 API），相对稳定
• docs/features/：特性设计文档（决策、方案取舍、验证基线、已知遗留），承载会变化的特性层面内容
• docs/AGENTS.md：只讲归档结构与命名规约，不重复模块设计内容

环境与运行

• Python：>=3.11。包为顶层布局（jiuwen_memory / jiuwen_memory_entry / jiuwen_memory_adapter），无 src/ 布局——仓库根存在空的 src/ 目录但未纳入 [tool.setuptools.packages.find]，不要往里放代码或从中导入。
• 安装：pip install -e ".[dev]" 装开发依赖。按需追加 extras：deploy（Milvus/ES/Redis/PG 真后端 + api_reranker 出站 httpx）、mcp（MCP server）、nlp（spacy/hanlp）、embed（FlagEmbedding/torch）。pyproject.toml 已配 uv 阿里云镜像。
• 运行入口用 scripts/run-{cli,server,mcp}.sh：它们已把 PYTHONPATH 设为 仓库根:jiuwen_memory_entry/core；直接 python -m jiuwen_memory_entry... 会因缺 jiuwen_memory_entry/core 路径导致导入失败。
  • CLI：scripts/run-cli.sh
  • HTTP server：scripts/run-server.sh
  • MCP：scripts/run-mcp.sh（需先 pip install ".[mcp]"；默认 stdio，设 MCP_TRANSPORT=http + MCP_PORT 切 Streamable HTTP）
• Postgres schema：scripts/pg_schema.sql（deploy 后端用）。