memorix (Avids2)

Memorix

Open-source cross-agent memory layer for coding agents.

Tiered MCP support across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, Trae, and other MCP-compatible clients.

Three-Layer Memory | Agent Team | Workspace Sync | Multi-Agent Orchestration | Dashboard

Chinese | Quick Start | Docker | Supported Clients | Common Workflows | Documentation | Setup Guide

______________________________________________________________________

通过Cursor、Windsurf、Claude Code、Codex或其他AI编码代理使用Memorix？阅读 代理操作员手册 面向代理的安装、MCP、挂钩和故障排除规则。

什么是Memorix？

Memorix是用于编码代理的本地第一存储器控制平面。

它将项目内存、推理上下文、Git导出的事实和可选的自主代理状态保存在一个地方，这样你就可以在IDE、会话、终端和代理运行之间继续工作，而不会丢失项目的真实性。

对于大多数用户来说，默认路径很简单：使用本地TUI/CLI或通过stdio MCP连接一个IDE。当您特别需要一个长期的后台服务、共享MCP访问或实时仪表板端点时，将HTTP视为您选择的共享控制平面模式。

为什么Memorix

大多数编码代理只记住当前线程。Memorix为他们提供了一个跨IDE、会话和项目的共享、持久的内存层。

🧠 Three-Layer MemoryObservation (what/how), Reasoning (why/trade-offs), Git Memory (immutable commit-derived facts with noise filtering) 🔍 Source-Aware Retrieval"What changed" queries favor Git Memory; "why" queries favor reasoning; project-scoped by default, global on demand ⚙️ Memory Quality PipelineFormation (LLM-assisted evaluation), dedup, consolidation, retention with exponential decay — memory stays clean, not noisy 🔄 Workspace & Rules SyncOne command to migrate MCP configs, workflows, rules, and skills across Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, etc. 👥 Agent TeamOpt-in autonomous-agent state: task board with role-based claiming, inter-agent messaging, advisory file locks, situational-awareness poll 🤖 Multi-Agent Orchestrationmemorix orchestrate runs a structured coordination loop — plan → parallel execution → verify → fix → review — with capability routing and worktree isolation 📋 Session LifecycleSession start/end with handoff summaries, watermark tracking (new memories since last session), cross-session context recovery 🎯 Project SkillsAuto-generate SKILL.md from memory patterns; promote observations to permanent mini-skills injected at session start 📊 DashboardLocal web UI for browsing memories, Git history, sessions, and read-only autonomous agent team state 🔒 Local & PrivateSQLite as canonical store, Orama for search, no cloud dependency — everything stays on your machine

支持的客户

核心 =完全挂钩集成+经过测试的MCP+规则同步。 扩展的 =挂钩集成与平台警告。 社区 =尽力而为挂钩，社区报告的兼容性。

如果客户端可以说MCP并启动本地命令或HTTP端点，即使它还不在上面的列表中，它通常也可以连接到Memorix。

______________________________________________________________________

快速开始

全局安装：

npm install -g memorix

初始化Memorix配置：

memorix init

memorix init 让您在以下两者之间进行选择 Global defaults 和 Project config.

Memorix使用两个具有两个角色的文件：

• memorix.yml 用于行为和项目设置
• .env 用于API密钥等机密

然后选择与你想做的事情相匹配的路径：

大多数用户应该选择 一 上述前两个选项。仅当您有意想要一个共享后台服务、多客户端MCP访问或实时仪表板端点时，才切换到HTTP。

常见路径：

配套命令： memorix background status|logs|stop。对于多工作区HTTP会话，请绑定 memorix_session_start(projectRoot=...).

关于启动、项目绑定、配置优先级和代理工作流的更深入细节： docs/SETUP.md 和那个 代理操作员手册.

TUI工作台

跑步 memorix 无参数打开交互式全屏终端UI（需要TTY）。使用它与项目内存聊天、搜索、快速内存捕获、诊断、后台服务控制、仪表板启动和IDE设置。按 /help 在TUI中显示当前命令列表。

单次聊天（无TUI）： memorix ask "your question".

操作员CLI

Memorix暴露了一个 CLI第一操作员界面。当您想直接从终端检查或控制当前项目时，请使用它。MCP仍然是IDE和代理的集成层。

memorix session start --agent codex-main --agentType codex
memorix memory search --query "docker control plane"
memorix reasoning search --query "why sqlite"
memorix retention status
memorix team status
memorix task list
memorix audit project
memorix sync workspace --action scan

CLI是故意的 任务形状，而不是MCP工具名称的1:1镜像。通过这些命名空间可以使用本机功能： session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest.MCP可用于IDE、代理和可选的图形兼容性工具。

码头工人

Memorix现在包括一个官方的Docker路径 HTTP控制平面.

快速启动：

docker compose up --build -d

然后连接到：

• 仪表板： http://localhost:3211
• MCP： http://localhost:3211/mcp
• 健康： http://localhost:3211/health

重要提示：Docker支持用于 serve-http，不 memorix serve项目范围的Git/config行为仅在容器可以看到它被要求绑定的存储库时才起作用。

完整的Docker指南：

将Memorix添加到您的MCP客户端：

通用标准io MCP配置

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

通用HTTP MCP配置

{
  "mcpServers": {
    "memorix": {
      "transport": "http",
      "url": "http://localhost:3211/mcp"
    }
  }
}

下面的每个客户端示例显示了最简单的stdio形状。如果您更喜欢共享HTTP控制平面，请保留上面的通用HTTP块，并在中使用特定于客户端的变体 docs/SETUP.md.

Cursor | .cursor/mcp.json

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Claude Code

claude mcp add memorix -- memorix serve

Codex | ~/.codex/config.toml

[mcp_servers.memorix]
command = "memorix"
args = ["serve"]

有关完整的IDE矩阵、Windows注释和故障排除，请参阅 docs/SETUP.md.

______________________________________________________________________

常见工作流

最常见的循环是故意小的：

memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory search --query "auth token ttl"
memorix session start --agent codex-main --agentType codex

当同时打开多个HTTP会话时，每个会话都应该绑定到 memorix_session_start(projectRoot=...) 在使用项目范围的内存工具之前。

默认情况下，HTTP MCP会话在30分钟后空闲。如果您的客户端没有从过时的HTTP会话ID中自动恢复，请在启动控制平面之前设置更长的超时时间：

MEMORIX_SESSION_TIMEOUT_MS=86400000 memorix background start  # 24h

代理团队是 不 正常的内存启动路径，它是 不 IDE窗口之间的聊天室。仅在需要任务、消息、锁或结构化自主代理工作流时加入。对于真正的多代理执行，首选：

memorix orchestrate --goal "Add user authentication" --agents claude-code,cursor,codex

资源配置文件

Memorix的设计是在正常记忆使用过程中保持轻盈：

• stdio MCP按需启动并随客户端退出
• HTTP后台模式是一个本地节点进程加上SQLite/Orama状态
• LLM富集是可选的；如果没有API密钥，Memoryx将回到本地启发式重复数据消除/搜索
• 较重的路径是构建/测试、Docker镜像构建、仪表板浏览、大型导入和可选的LLM支持的构建

在这台Windows开发机器上，在空闲几个小时后，在大约16MB的工作集上观察到健康的HTTP控制平面。将其视为本地观察，而不是跨平台保证。看 性能和资源说明 用于旋钮和权衡。

程序化SDK

将Memorix直接导入到您自己的TypeScript/Node.js项目中——不需要MCP或CLI：

import { createMemoryClient } from 'memorix/sdk';

const client = await createMemoryClient({ projectRoot: '/path/to/repo' });

// Store a memory
await client.store({
  entityName: 'auth-module',
  type: 'decision',
  title: 'Use JWT for API auth',
  narrative: 'Chose JWT over session cookies for stateless API.',
});

// Search
const results = await client.search({ query: 'authentication' });

// Retrieve, resolve, count
const obs = await client.get(1);
const all = await client.getAll();
await client.resolve([1, 2]);

await client.close();

三个子路径导出：

______________________________________________________________________

运作原理

flowchart LR
    subgraph ING["Ingress"]
        A["Git Hooks
commit + ingest"]
        B["MCP Tools
search, store, recall"]
        C["CLI / TUI
operator workflows"]
        D["Dashboard
read-mostly project view"]
    end

    subgraph RUN["Runtime"]
        E["stdio MCP Server
memorix serve"]
        F["HTTP Control Plane
background / serve-http"]
        G["Project Binding
git root + config"]
    end

    subgraph MEM["Memory"]
        H["Observation
facts, gotchas, fixes"]
        I["Reasoning
why, trade-offs, risks"]
        J["Git Memory
commit-derived ground truth"]
        K["Session + Agent Team
opt-in tasks, locks, handoffs"]
    end

    subgraph PROC["Processing"]
        L["Formation
quality shaping"]
        M["Embedding + Index
hybrid retrieval"]
        N["Graph Linking
entity relations"]
        O["Dedup + Retention
consolidate over time"]
    end

    subgraph USE["Consumption"]
        P["Search / Timeline / Detail"]
        Q["Dashboard / Agent Team View
read-mostly state"]
        R["Recall / Handoff / Resume"]
        S["Skills / Sync / Orchestrate"]
    end

    A --> E
    B --> E
    C --> E
    D --> F

    E --> G
    F --> G

    G --> H
    G --> I
    G --> J
    G --> K

    H --> L
    H --> M
    I --> L
    I --> N
    J --> M
    J --> N
    K --> O

    H --> P
    I --> P
    J --> P
    K --> Q
    H --> R
    I --> R
    J --> R
    K --> S

Memorix不是一个单一的线性管道。它从多个入口表面接受内存，在多个基板上持久化内存，运行多个异步质量/索引分支，并通过检索、仪表板和显式代理团队表面公开结果。

内存层

• 观察记忆：发生了什么变化，事情是如何运作的，问题，问题解决笔记
• 推理记忆：为什么做出选择、替代方案、权衡、风险
• Git内存：源自提交的不可变工程事实

检索模型

• 默认搜索为 项目范围
• scope="global" 跨项目搜索
• 全局点击可以通过项目感知的引用显式打开
• 源代码感知检索提高了Git对“发生了什么变化”问题的记忆和对“为什么”问题的推理记忆

______________________________________________________________________

文档

📖 文档地图 --找到正确文档的最快路径。

其他深度参考：

• 记忆形成管道
• 设计决策
• 模块
• 已知问题和路线图
• AI上下文注释
• llms.txt
• llms-full.txt

______________________________________________________________________

1.0.8的新增功能

版本 1.0.8 基于1.0.7协调/存储/团队基线构建，具有CLI优先的操作员界面、官方Docker路径、仪表板改进和广泛的钩子修复。

• CLI首个产品界面：每个Memorix原生操作员功能现在都有一个面向任务的CLI路由-- session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingestMCP仍然是集成协议和可选的图形兼容层。
• Docker部署：官方 Dockerfile, compose.yaml健康检查， --host 绑定，以及 医生.md 用于在容器中运行HTTP控制平面。
• 多代理编排器: memorix orchestrate 在Claude、Codex、Gemini CLI和OpenCode之间运行计划、并行执行、验证、修复、审查和合并循环，并具有功能路由、工作树隔离和代理回退。
• SQLite规范商店：SQLite中的观察、迷你技能、会话和档案。共享数据库句柄，新鲜安全检索，死 JsonBackend 远离的。
• 选择加入代理团队：任务板、消息、文件锁、切换工件和自主代理心跳状态。 session_start 默认情况下是轻量级的；团队身份可通过以下方式选择加入 joinTeam 或 team_manage join.
• 仪表板语义分层：团队页面过滤器选项卡（活动/最近/历史）、不强调的历史代理、按真实/临时/占位符分组的项目切换器、身份页面清理。
• 挂钩修复：OpenCode事件名称键映射+ Bun.spawn → spawnSync；副驾驶 pwsh 回退+全局钩子保护；钩子处理程序诊断日志记录。
• 程序化SDK: import { createMemoryClient } from 'memorix/sdk' 直接从您自己的代码中存储、搜索、获取和解析观察结果，而无需MCP或CLI。也出口 createMemorixServer 和 detectProject.
• 测试套件稳定性：E2e和实时LLM测试被排除在默认套件之外，负载敏感测试被隔离，因此默认验证路径保持确定性。

______________________________________________________________________

发展

git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install

npm run dev
npm test
npm run build

关键本地命令：

memorix status
memorix dashboard
memorix background start
memorix serve-http --port 3211
memorix git-hook --force

______________________________________________________________________

致谢

明星历史

许可证

Apache 2.0