✨ 它能做什么

• 🧠 跨设备同步对话 — Mac / Linux / Windows 上的 Claude Code / Codex / Cursor / Antigravity 等工具,聊过的内容统一汇总
• 🔍 混合检索 — BGE-M3 向量 + jieba 分词的全文索引,中英文都能搜
• 🕸️ 知识图谱 — LLM 自动从对话抽实体(项目 / 工具 / 技术 / 人物 / 概念)、关系、观察;超过 7 天的老观察自动压缩成 summary
• 🔗 MCP 接入 — 在任何 AI IDE 里通过 MCP 直接调 memory_search / memory_recall / daily_summary,Claude 自己就能查你过去做的事
• 📅 AI 日报 — Celery 每天 23:30 跑两阶段:先为每篇文档生成摘要,再聚合成跨工具每日 digest
• 🔒 入队前脱敏 — Collector 本地就过 14 类密钥正则(OpenAI / Anthropic / GitHub / Slack / Telegram / AWS / Bearer / 私钥 / URL 内嵌凭证 …),磁盘上 SQLite 队列也安全
• 🌐 公开分享 — 项目时间线 / 日报一键生成 share 链接,带 GeoIP 访客统计、有效期、随时撤销
• 🛡️ 完全自托管 — Docker Compose 一键起,Postgres + Redis + MinIO 全在你机器上,数据不出门
• 🔐 多租户隔离 — 多用户独立空间,owner / admin / viewer 三级角色 + 细粒度授权 + 审计日志
• ⚡ 守护进程级 — 设备上跑成 launchd / systemd / Task Scheduler,断网离线队列、自愈重试

🏗️ 架构

graph TB
    subgraph DEV["📱 用户设备 Mac/Linux/Windows"]
        direction LR
        CC["Claude Code<br/>~/.claude"]
        CDX["Codex<br/>~/.codex"]
        CUR["Cursor<br/>~/.cursor"]
        AG["Antigravity<br/>~/.gemini/antigravity"]
        OC["OpenClaw<br/>~/.openclaw"]
        HM["Hermes<br/>~/.hermes"]
        OBS["Obsidian Vault"]
        COL["memento-brain-collector<br/>watchdog 监听<br/>SQLite 离线队列<br/>sanitizer 入队脱敏"]
        CC --- COL
        CDX --- COL
        CUR --- COL
        AG --- COL
        OC --- COL
        HM --- COL
        OBS --- COL
    end

    subgraph SRV["☁️ 自托管 Memento 服务端"]
        direction TB
        NGX["nginx<br/>HTTPS + gzip"]

        subgraph DK["Docker Compose"]
            direction LR
            API["FastAPI :8000"]
            WEB["Next.js Web :3000"]
            CW["Celery Worker"]
            CB["Celery Beat"]
            PG[("PostgreSQL 16<br/>+ pgvector")]
            RD[("Redis 7")]
            S3[("MinIO<br/>S3 兼容")]
        end

        EMB["BGE-M3 Embedding<br/>:8002 宿主进程"]

        NGX --> API
        NGX --> WEB
        API <--> PG
        API <--> RD
        API <--> S3
        API -.调用.-> EMB
        CW <--> PG
        CW <--> RD
        CB --> CW
    end

    subgraph CLT["🤖 AI 工具 MCP 客户端"]
        direction LR
        MCC["Claude Code"]
        MCDX["Codex"]
        MCUR["Cursor"]
        MAG["Antigravity"]
    end

    MCP["memento-brain-memory<br/>MCP Server"]
    MCC --> MCP
    MCDX --> MCP
    MCUR --> MCP
    MAG --> MCP

    COL ==>|"HTTPS + collector token"| NGX
    MCP ==>|"HTTPS + JWT"| NGX

    subgraph PUB["🌍 公开访问"]
        SHARE["分享链接 /s/&lt;token&gt;"]
        GEO["GeoIP DB<br/>访客统计"]
    end
    NGX --> SHARE
    SHARE --> GEO

    classDef device fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef server fill:#dbeafe,stroke:#2563eb,color:#1e40af
    classDef client fill:#fce7f3,stroke:#db2777,color:#831843
    classDef public fill:#dcfce7,stroke:#16a34a,color:#14532d
    class CC,CDX,CUR,AG,OC,HM,OBS,COL device
    class API,WEB,CW,CB,PG,RD,S3,EMB,NGX server
    class MCC,MCDX,MCUR,MAG,MCP client
    class SHARE,GEO public

数据流(单条对话从产生到可搜)

sequenceDiagram
    participant T as AI 工具
    participant W as 本地文件
    participant C as Collector
    participant Q as SQLite 队列
    participant A as API
    participant P as Postgres
    participant E as Embedding
    participant M as MCP

    T->>W: 写 .jsonl 对话
    W->>C: watchdog 文件事件
    C->>C: 解析 + 脱敏
    C->>Q: 入离线队列
    Q->>A: HTTPS POST(失败重试)
    A->>P: 写 documents / conversation_messages / content_tsv
    A-->>E: 异步算 embedding
    E->>P: 写 document_embeddings (pgvector)
    A-->>P: LLM 抽 entities / relations
    Note over M: 用户在 Claude Code 里调 memory_search
    M->>A: GET /api/memory/semantic
    A->>E: 算 query embedding
    E->>P: cosine_distance 排序
    P-->>M: 返回相关 chunk

Embedding 失败时 embedding_status 写为 failed,Celery beat 每 15 分钟扫 pending/failed 自动重试,不会因为单次抖动丢向量。

🧰 支持的 AI 工具

🚀 快速开始

一键安装(推荐)

# macOS / Linux
curl -fsSL https://mem.ihasy.com/install.sh | sh

# Windows (PowerShell)
iwr https://mem.ihasy.com/install.ps1 -useb | iex

也可以浏览器打开 https://mem.ihasy.com/install 拿复制好的命令。脚本会下载仓库到 ~/memento/(可用 MEMENTO_INSTALL_DIR 覆盖),然后跑内置 ./install.sh。

已 clone 仓库

git clone https://github.com/ddong8/memento.git && cd memento
./install.sh            # macOS / Linux
.\install.ps1           # Windows

install.sh 自动完成:

1. 生成 .env 随机密钥(JWT / collector token / MinIO / Postgres 密码)
2. docker compose up -d --build 起 7 个容器
3. 探活 API /health
4. 交互提示创建第一个用户(自动 owner,拿 collector_token)
5. pip install memento-brain-collector + setup + 注册系统服务

可选参数:

服务端口

端口与常见项目错开,避免冲突。

💻 在额外设备上接入

pip install memento-brain-collector   # 只装采集器
# 或 pip install memento-brain         # 一并装齐 collector + MCP memory
memento-collector setup                # 交互式填 URL + token

PyPI 包名 memento-brain-collector / memento-brain-memory(短名 memento-memory 被占了),CLI 保留短别名 memento-collector / memento-memory。

怎么拿 token?

• 跑过 ./install.sh → 末尾会打印,同时存到 .env.local
• Web 注册 → /auth/register 第一个用户自动 owner + 显示 token;之后任意时刻头像 → 个人资料

守护进程

memento-collector status    # 查看状态
memento-collector start     # 启动服务
memento-collector stop      # 停止服务
memento-collector run       # 前台运行(调试)

按平台自动适配:macOS launchd / Linux systemd user / Windows Task Scheduler。

🕸️ 知识图谱

LLM 自动从同步进来的对话和文档里抽:

• 实体 (knowledge_entities) — 项目 / 工具 / 技术 / 人物 / 概念,跨对话去重合并
• 关系 (knowledge_relations) — 实体之间的 uses / creates / depends_on / discussed
• 观察 (observations) — 关于某个实体的具体事实陈述,带时间戳和来源 doc

自动压缩:同一实体超过 7 天的累积观察会被 LLM 合并成一段更短的 summary,保语义、省空间。压缩窗口可通过 MEMENTO_COMPACTION_AGE_DAYS 调整。

通过 MCP 工具 memory_recall / memory_context / memory_store 可读写;Web /memory 页可视化查看。

🧠 MCP 记忆服务

装齐 memento-brain 后,所有 AI IDE 会自动配置 MCP 接入(由 memento-collector setup 完成):

接入后在任何 AI IDE 里可以调:

外加 4 个 MCP resources(以 URI 形式暴露,IDE 可订阅):

👥 用户与权限

关键流程:

• 注册:/auth/register — 首个用户自动 owner + active,之后注册需要 admin 批准
• token 自助管理:右上角头像 → 个人资料,查看/复制/重新生成 collector token
• 批准用户:owner/admin 进 /admin,pending 用户旁有按钮,批准后 token 立即出现可复制
• 细粒度授权:/admin/permissions 按 project / tool 给 viewer 发 read/write 权限
• 审计日志:access_logs 表落库每次敏感操作(user_id / action / IP / metadata),便于事后追溯

🌐 公开分享

项目时间线和日报可以一键生成公开分享链接:

• 进 /projects/<id>/timeline 或 /daily/<date>,右上角 分享 按钮
• 选有效期(可永久),生成 /s/<token> URL
• 访客无需登录直接查看
• 后台记录访客 IP + 国家/地区/城市(本地 GeoIP DB,无外发请求)
• 随时可撤销

🛠️ 技术栈

⚙️ 后台任务

Celery beat 调度的定时任务:

📁 目录结构

memento/
├── collector/                # 本地采集器 — PyPI: memento-brain-collector
│   └── collector/
│       ├── main.py           # 守护进程入口
│       ├── cli.py            # setup / install / start / stop / uninstall
│       ├── watcher.py        # watchdog 跨平台监听 + 去抖
│       ├── queue.py          # SQLite WAL 离线队列
│       ├── sync_client.py    # HTTPS 同步(分片上传 / 离线重试)
│       ├── sanitizer.py      # 入队前脱敏(API key / 私钥 / OAuth)
│       ├── parsers/          # 8 个解析器
│       └── tools/            # 6 个工具定义
├── mcp_server/               # MCP 记忆 — PyPI: memento-brain-memory
├── memento_brain/            # Meta — PyPI: memento-brain(一键装齐)
├── server/                   # 后端 FastAPI
│   └── server/
│       ├── main.py           # 入口 + schema 迁移 + validate_production
│       ├── config.py         # MEMENTO_ 前缀 settings + fail-fast
│       ├── middleware/       # JWT + collector token (constant-time)
│       ├── api/              # REST + SSE + MCP 挂载
│       ├── db/               # 16 张表
│       ├── services/         # ingest / embedding / graph / cache / geoip
│       └── tasks/            # Celery worker + beat
├── web/                      # Next.js 16 前端
│   ├── src/app/              # 18+ 页面
│   └── src/components/       # Aurora 设计系统
├── embedding/                # BGE-M3 宿主服务
├── scripts/                  # install.py 后端 + 工具脚本
├── deploy/bootstrap/         # curl 一键安装(install.sh / .ps1 / index.html)
├── docs/                     # project-architecture.md / collector-architecture.md
└── docker-compose.yml

⚙️ 环境变量

所有变量统一 MEMENTO_ 前缀。

🌐 远程访问 / 自定义域名

• 前端 API 地址自动跟随 window.location.hostname(代码里 getApiBase(),不写死)

• Docker 端口映射自动支持 IPv4 + IPv6

• 放行域名改 server/server/main.py 里的 allow_origin_regex,默认:

  allow_origin_regex=r"(https?://localhost:\d+|https?://mem\.ihasy\.com)"
  

🗑️ 卸载

./install.sh uninstall          # 只停容器,保留数据 / .env / pip 包
./install.sh uninstall --purge  # 同上 + 删 Docker 数据卷 + .env
./install.sh uninstall --all    # 核弹级(加 -y 跳过二次确认)

--all 会清:

• pip 包(memento-brain-* + 旧品牌 daily-report-*)
• ~/.memento + ~/.daily-report(旧路径)
• Collector 日志(macOS / Linux / Windows 各自路径)
• Embedding venv + HuggingFace 模型缓存(~1.3 GB)
• Docker 镜像 + 数据卷
• .env / .env.local
• AI 工具的 MCP memento-memory 条目

memento-collector uninstall                                  # 摘掉 launchd/systemd/Task
pip uninstall -y memento-brain-collector memento-brain-memory memento-brain
rm -rf ~/.memento

# 日志(选一)
rm -rf ~/Library/Logs/memento                                # macOS
rm -rf ~/.local/share/memento/logs                           # Linux
# Windows: Remove-Item -Recurse $env:LOCALAPPDATA\memento

# AI 工具 MCP 条目手动删掉 memento-memory 块

📄 License

本项目采用 AGPL-3.0 许可证。

简单说:个人使用、自托管、内部用、研究学习都免费。但如果你拿这份代码(或任何改动)对外提供网络服务(SaaS / 公开 host),按 AGPL 第 13 条,你必须把你修改后的完整源码也按 AGPL 公开。

商业授权(免除 AGPL 限制、闭源使用、SaaS 化等场景)请联系作者。