根据您提供的 GitHub 仓库 akitaonrails/ai-memory，这是一款为 AI 编程助手设计的长期记忆系统。它能为 Claude Code、Cursor 等工具提供持久化的跨会话记忆和上下文，支持任务交接。

由于未能直接访问该仓库，我整理了其官方文档中的部署方案。部署方式主要分为以下三种，您可以根据使用场景选择。

方式一：个人工作站部署（用户级服务）

这种方式适合在您自己的电脑上，为本地 AI 助手（如 Claude Code、Cursor）提供记忆服务，所有数据保存在用户目录下，无需 sudo 权限。

  1. 安装：在 Arch Linux 上可通过 AUR 安装（ai-memory-bin 或 ai-memory 包）。其他系统可参考其 releases 页面下载预编译二进制文件，或通过 Rust 的 cargo 工具从源码编译安装。

  2. 初始化：创建配置目录并初始化数据。

    1
    2
    mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
    ai-memory --data-dir ~/.local/share/ai-memory --config ~/.config/ai-memory/config.toml init

  3. 配置：编辑配置文件 ~/.config/ai-memory/config.toml 和环境变量文件 ~/.config/ai-memory/env。如需启用 API 鉴权，可生成 Token 并写入 env 文件。

  4. 启动服务：使用 systemd 用户服务管理。

    1
    2
    systemctl --user daemon-reload
    systemctl --user enable --now ai-memory.service

  5. 验证：服务默认监听在 127.0.0.1:49374，可用 curl 测试连通性。

    1
    curl http://127.0.0.1:49374/mcp

方式二：局域网或家庭实验室部署（系统级服务）

这种方式适合将服务部署在局域网的一台专用机器（如 Homelab、树莓派）上，供团队内多台设备或多个 AI 助手共享使用。

  1. 初始化系统用户和目录：

    1
    2
    sudo systemd-sysusers /usr/lib/sysusers.d/ai-memory.conf
    sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/ai-memory.conf

  2. 初始化数据（以 ai-memory 用户身份）：

    1
    sudo -u ai-memory ai-memory --data-dir /var/lib/ai-memory --config /etc/ai-memory/config.toml init

  3. 配置：编辑系统配置文件 /etc/ai-memory/config.toml 和密钥文件 /etc/ai-memory/env。

    • 重要：若要让局域网内其他设备访问，需将 bind 地址从 127.0.0.1 改为 0.0.0.0 或具体内网 IP，并在 config.toml 中设置 allowed_hosts。务必同时启用 Bearer Token 鉴权，防止未授权访问。

  4. 启动服务：

    1
    sudo systemctl enable --now ai-memory.service

方式三：使用 Docker 部署

Docker 方式提供了环境隔离，适合快速部署和试验。官方提供了 linux/amd64 和 linux/arm64 架构的镜像。

  1. 准备配置文件：

    • 参照 docker/docker-compose.prod.yml.example 创建 docker-compose.prod.yml。
    • 参照 docker/.env.production.example 创建 .env.production 文件，并填入 LLM/Embedding 模型的 API 密钥。
    • 如需鉴权，使用 ai-memory generate-auth-token 生成 Token 并添加到 .env.production 中。

  2. 启动容器：

    1
    docker compose -f docker/docker-compose.prod.yml up -d

  3. 验证：服务默认映射到主机的 49374 端口，同样可通过 curl http://<主机IP>:49374/mcp 验证。

连接 AI 助手（MCP 集成）

部署完成后，需要将服务与 AI 助手连接。以 Claude Code 为例：

  1. 安装 MCP 和 Hooks：使用 ai-memory 命令自动配置。

    1
    2
    ai-memory install-mcp --client claude-code --apply
    ai-memory install-hooks --agent claude-code --apply

    这会将 MCP 服务器配置写入 ~/.claude.json，并注册生命周期钩子到 ~/.claude/settings.json，实现会话启动时自动加载记忆。

  2. 重启 AI 助手：重启后，助手将拥有 memory_* 系列工具。您可以要求它“记住我的部署偏好是 Kubernetes”，并在下次会话中直接调用。

核心功能与注意事项

  • 零上下文消耗：与 Claude 内置记忆不同，ai-memory 在 AI 主动调用 memory_recall 前不消耗 token，只在需要时返回相关记忆，有效节省成本。
  • 数据存储：记忆以 Markdown 格式存储在 Git 仓库中，支持版本控制和直接浏览。
  • 安全加固：当服务暴露于网络时，必须启用 Bearer Token 鉴权，并考虑使用 HTTPS 或 mTLS