Memex

收集零散的 Codex 对话，提炼持久知识，将其连接、索引，并在关键时刻带回正确的记忆。

Memex 是一个面向 Codex 的本地优先个人知识系统。它将本地 rollout 会话转化为可搜索的对话存档、持久事实、基于本体的知识图谱，以及 Codex 可在后续工作中复用的有界上下文。

한국어 README · 文档 · 安装与操作 · 架构 · 模式

Memex 是一个独立的 Codex 原生项目，源自 MIT 许可的 jung-wan-kim/memory-bank， 后者又源自 obra/episodic-memory。它保留了知识系统能力，而非 Claude Code 兼容代码。参见血统与迁移。

为什么是 0.1.0？

0.1.0 是合适的首个公开版本。功能集已相当丰富且经过测试，但该仓库是全新独立的，其 Codex 市场、宿主适配器和安装契约在稳定的 1.0.0 之前仍可能发生变化。1.0.0 将意味着这些公共契约是刻意稳定的，而不仅仅是有许多功能存在。

Related MCP server: codex-memory-mcp

功能

• 对 Codex 对话历史进行语义、FTS5/BM25 和混合搜索

• 无需 LLM 调用的确定性全历史分析

• 增量事实提取、置信度门控、整合、修订和溯源

• 领域/类别本体和类型化知识图谱关系

• 项目、全局和显式请求的全项目范围隔离

• 1–3 跳图遍历和跨项目洞察

• 带相关性和每会话去重的有界 RAG 上下文注入

• 对压缩的 .jsonl.zst 存档进行透明的有界读取

• 九个 MCP 工具，用于对话、事实、本体、图谱和溯源

• 三个 Codex 技能，用于召回、历史分析和仪表板工作流

• 仅回环的 Web UI，包含事实、管道健康和 3D 知识星系

• Codex 原生的 SessionStart、UserPromptSubmit 和 SessionEnd 钩子

架构概览

flowchart LR
    R[Codex rollout JSONL] --> S[Sync and parser]
    S --> A[Immutable local archive]
    S --> C[(Conversation index)]
    C --> X[Incremental fact extraction]
    X --> F[(Facts and revisions)]
    F --> O[(Ontology and typed relations)]
    C --> Q[Hybrid retrieval]
    F --> Q
    O --> Q
    Q --> M[MCP tools and skills]
    Q --> H[Prompt context hook]
    C --> UI[Loopback Web UI]
    F --> UI
    O --> UI

源 rollout 是只读的。存档、SQLite/FTS/向量索引、事实和图谱数据是派生的本地状态。模型支持的工作通过隔离的、临时的本地 codex exec 运行；没有 Claude 回退或单独的 API 密钥提供者。

详细机制请参阅：

• 系统架构

• 对话生命周期

• 事实生命周期

• 知识图谱

• 检索与上下文注入

• MCP 与技能

• Web UI 与 3D 可视化

系统要求

• Node.js 22.15 或更高版本

• 已认证的 Codex CLI

• 当前钩子和 Unix 套接字运行时需要 macOS 或 Linux

该插件使用 Node 自带的 npx 启动器，将 BongSuCHOI/memex#main 的最新运行时解析到 npm 的隔离缓存中。它不会在你的项目中克隆或构建、安装全局包，也不会将依赖写入 Codex 插件缓存。

推荐安装

直接从公共仓库安装：

codex plugin marketplace add BongSuCHOI/memex
codex plugin add memex@memex

这就是完整的用户安装。它安装插件清单、三个技能、MCP 声明、生命周期钩子、CLI 启动器和 UI 启动器。首次运行时调用可能需要更长时间，因为 npx 会用原生 SQLite、向量和嵌入依赖填充其缓存。

现有的手动市场流程

外部市场布局仍支持开发和离线/本地测试：

memex-local-marketplace/
├── .agents/plugins/marketplace.json
└── plugins/memex -> /absolute/path/to/memex

将其条目指向 ./plugins/memex，使用 codex plugin marketplace add /absolute/path/memex-local-marketplace 注册，然后安装 memex@<marketplace-name>。源安装器仍可用于本地开发验证。完整的 JSON 和回滚行为保留在操作指南中。

首次运行引导

安装后，重启 Codex，以便新安装的 MCP 服务器、技能和插件管理的钩子在新会话中加载。

为了获得可读的终端命令，请定义此会话级 shell 函数。它始终指向最新的 main 运行时，并且不会全局安装：

memex() { npx --yes --package=github:BongSuCHOI/memex#main memex "$@"; }

然后执行一次性语料库设置：

memex setup
memex sync
memex backfill extract --foreground
memex backfill ontology --foreground
memex backfill embeddings --foreground
memex status

memex setup 检查有效的 Codex memories 功能。当内置 Memory 启用时，Memex 会解释双重记忆/冲突记忆风险，并建议禁用它。交互式终端会请求确认；自动化和非交互式 shell 在没有显式 memex setup --disable-codex-memory 批准标志的情况下绝不会更改设置。该更改使用 Codex 自己的 codex features disable memories 命令，并在之后进行验证。

每个阶段的作用：

1. sync 读取现有的 $CODEX_HOME/sessions，归档新的 rollout，并构建对话搜索索引。

2. backfill extract 从已索引的交流中提炼持久事实。

3. backfill ontology 对事实进行分类并构建图谱结构。

4. backfill embeddings 填充缺失的语义向量。

5. status 分别报告对话、事实和图谱的就绪状态。

大型历史和本地模型支持的提取可能需要几分钟或更长时间。请在前台运行命令，以确保首次完成无歧义。如果你选择 --background，“已启动”并不等于“已完成”；请持续检查 memex status，直到待处理计数达到预期状态。

市场安装不会在此引导步骤之前修改源 rollout 或派生数据。sync 是幂等的，可以安全重复。

日常使用

memex sync
memex search "why did we choose SQLite?"
memex search --both "authentication migration"
memex stats
memex analyze --top 30 --out ~/memex-report.md
memex status

MCP 工具与技能

该插件提供：

search, read, search_facts, search_ontology, ask_avatar,
trace_fact, explore_graph, cross_project_insights, graph_stats

项目敏感工具需要规范的绝对项目路径或显式的 global/all 范围。MCP 进程绝不会从其自身的 cwd 猜测范围。参见 MCP 与技能 获取模式和示例。

本地 Web UI

npx --yes --package=github:BongSuCHOI/memex#main memex-ui
# http://localhost:3847

路由：

• / — 对话、项目、搜索和交流

• /facts — 事实、修订、溯源和受保护的变更

• /graph — 有范围的实时 3D 知识图谱

• /pipeline — 就绪和积压健康状态

服务器仅绑定到回环地址。参见可视化。

更新

预览，然后更新 Git 市场快照并重新安装插件：

memex update --dry-run
memex update

运行时启动器已经跟随最新的 main；memex update 也会刷新市场快照，因此更新的技能、钩子和 MCP 元数据会一起安装。之后重启 Codex。持久 Memex 数据会被保留。

召回溯源与自我摄取安全

Memex 将钩子召回记录为持久的、按事件划分的 memex_recall 收据，以会话和人类提示哈希为键。Memex MCP 检索结果也以相同方式分类。溯源是证据级别的，而非回合级别的：人类断言和允许列表中的本地仓库、Git 历史和测试执行结果即使在召回旁边也仍然可学习；Memex 结果、外部/未知工具输出和助手生成的综合则不可学习。完整的交流仍然可搜索。这防止了“召回 → 代理回声 → 新事实 → 召回”的放大，同时保留了基于证据的事实演化。

卸载

插件管理的钩子在插件被移除时会消失。如果旧版/手动安装使用了 setup-hooks，请在删除插件之前仅移除那些带指纹的条目：

npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks --dry-run
npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks
codex plugin remove memex@memex --json
codex plugin marketplace remove memex --json

卸载会保留 $CODEX_HOME/sessions 和 Memex 的派生数据。在手动删除之前，请检查确切的数据路径。参见操作指南。

数据与隐私

默认派生数据保留在 ~/.config/memory-bank 以保持持久数据兼容性。解析顺序：

1. MEMORY_BANK_HOME

2. MEMORY_BANK_CONFIG_DIR

3. $XDG_CONFIG_HOME/memory-bank

4. ~/.config/memory-bank

该命名是历史存储兼容性，而非 Claude 运行时适配器。参见模式和安全边界。

验证

npm run typecheck
npm run build
npm test
npm run test:marketplace
npm run test:package
node --test test/codex-slice.test.mjs
node --test test/*slice.test.mjs
node scripts/validate-plugin.mjs

Codex CLI 0.149.1 不暴露 codex plugin validate；该仓库记录了该版本边界，并运行隔离的已安装工件替代品。当前收据和剩余限制记录在验证中。

贡献

仅为开发或贡献而克隆和构建：

git clone https://github.com/BongSuCHOI/memex.git
cd memex
npm ci
npm run build
npm test

阅读 AGENTS.md 了解产品不变量、所有权边界和必需检查。当行为发生变化时，在同一变更中更新文档地图中标识的所有者文档。

许可证

MIT。上游归属和第三方声明位于 docs/LINEAGE.md 和 THIRD_PARTY_NOTICES.md 中。