# @raybird\.chen/memoria 中文文档

规范地址：https://npmcn.com/package/%40raybird.chen/memoria/

版本：1\.36\.1
npm 元数据更新时间：2026-11-02T06:44:41.088Z
中文译文更新时间：2026-11-02T07:06:00.192Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40raybird.chen/memoria
原文对照：https://npmcn.com/package/%40raybird.chen/memoria/?lang=original
项目主页：https://github.com/raybird/Memoria
源码仓库：https://github.com/raybird/Memoria

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：3 个
- 首次发布：2026-05-24T12:11:31.166Z
- 最新版本发布：2026-11-02T06:44:40.767Z
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

用于AI代理的交叉会话、可跟踪、自托管持久内存-SQLite-backed CLI+HTTP API+Node SDK。

## 安装

```sh
npm install @raybird.chen/memoria
```

也可以使用：`pnpm add @raybird.chen/memoria`、`yarn add @raybird.chen/memoria`、`bun add @raybird.chen/memoria`

## README

# Memoria

[English](https://npmcn.com/package/%40raybird.chen/memoria/README.md) ｜ **繁體中文**

讓 AI Agent 擁有跨會話、可追溯、可自託管的持久記憶。

Memoria 將決策、踩坑經驗與學到的技能保存到本地 SQLite，在 agent 需要時召回相關記憶。Markdown 筆記與編譯後的 brief 讓記憶可讀，也能在下次 session 直接載入。

## 能力概覽

| 能力 | 用途 |
| --- | --- |
| 持久記憶 | 匯入 session，或用 `remember` 保存單筆筆記；SQLite 與 markdown 保留來源 |
| 召回 | Keyword、tree、hybrid 檢索，以及選用的本地 embedding 語意召回 |
| 長期上下文 | Durable 記憶、明確取代舊記憶，以及由 `AGENTS.md` 指引讀取的專案 brief |
| Git 記憶 | 唯讀觀察 repository，增強變更摘要，召回時附上 commit 來源 |
| 效用回饋 | 回報召回是否有用，讓觀測效用影響排序與保留 |
| Wiki | 匯入 markdown/text、編譯 wiki 頁面、歸檔有價值的查詢結果 |
| 記憶工作台 | 透過本機唯讀介面瀏覽、搜尋與閱讀完整記憶、理由及來源 |
| 整合 | CLI、HTTP API、原始碼層級 Node.js SDK 與 agent adapter 共用核心 |

核心在本地執行，只有 `better-sqlite3`、`commander`、`zod` 三個 runtime 依賴。MCP/libSQL 為選用功能，SQLite 始終是資料真相來源。需要語意索引或跨系統圖譜投射時，請見 [MCP/libSQL 指南](https://npmcn.com/package/%40raybird.chen/memoria/docs/MCP_INTEGRATION.md)。

## 快速開始

需要 **Node.js ≥ 18**。安裝後執行互動式 `memoria setup`（或直接傳入旗標一次完成）：

```bash
npm install -g @raybird.chen/memoria
memoria setup
# 非互動一次到位（全域記憶 + Claude Code 與 Codex skills + 本地語意召回）：
# memoria setup --scope global --agent both --vector --yes

memoria remember "使用 pnpm" --project Memoria --rationale "以 lockfile 為準"
memoria recall "為什麼用 pnpm" --project Memoria --mode vector --json
memoria brief --project Memoria
```

這些命令直接存取本地資料，server 為選用。全域 setup 會將預設資料根目錄（`~/.memoria`）與本地向量設定寫入使用者設定檔（`install.json`），新開的終端機不需要手動 `export MEMORIA_HOME` 或 `LIBSQL_URL` 即可共用同一份記憶庫。專案範圍（`--scope project`）會使用目前專案的 `./memoria`，而顯式傳入的 `MEMORIA_HOME` 或 `--memoria-home` 永遠優先。

`setup` 也會產生初始 brief，並在備份既有檔案後，將受管理區塊（`<!-- memoria:managed:start -->` ... `<!-- memoria:managed:end -->`）接進共用的 `AGENTS.md` 與 `CLAUDE.md`。記憶更新後請執行 `memoria brief` 重新產生 brief。專案辨識、durable 標記與效用回饋詳見 [CLI 指南](https://npmcn.com/package/%40raybird.chen/memoria/docs/CLI.zh-TW.md)。

## 使用介面瀏覽記憶

需要 v1.33.0 或更新版本。原始碼 checkout 可執行 `pnpm run build` 與 `node dist/cli.mjs serve --ui`。

完成 setup 後執行：

```bash
memoria serve --ui
```

開啟印出的 `http://127.0.0.1:3917/ui/`。工作台提供決策、技能與 Session 分類、專案篩選、完整理由與來源、搜尋、摘要、淺深色與鍵盤操作。它使用與 CLI 相同的已初始化資料根，也可明確指定 `MEMORIA_HOME=/path/to/data-root memoria serve --ui`。

介面在前景執行，按 Ctrl+C 關閉；資產隨程式內嵌，可離線瀏覽，明確搜尋會保留本地 recall 遙測。範圍、語意搜尋與存取邊界詳見 [本機工作台指南](https://npmcn.com/package/%40raybird.chen/memoria/docs/CLI.zh-TW.md#%E6%9C%AC%E6%A9%9F%E8%A8%98%E6%86%B6%E5%B7%A5%E4%BD%9C%E5%8F%B0)。

## 搭配 Agent 使用

Setup 會將 **memoria** skill 部署到 `<memoria-home>/.agents/skills/memoria/SKILL.md`，並依選擇把 host 的標準探索目錄連結到這裡（Claude Code 為 `~/.claude/skills/memoria`，Codex 為 `~/.codex/skills/memoria` 或 `$CODEX_HOME/skills/memoria`），重跑 `setup` 即同步更新所有已連結的 host：

```bash
memoria setup --scope global --agent both --yes
```

Skill 引導 agent 在工作前召回記憶，並在做出決策或完成變更後寫回。部署路徑、備份與獨立安裝方式見 [安裝指南](https://npmcn.com/package/%40raybird.chen/memoria/docs/INSTALL.md)。

選用的下一步：

-   **HTTP 或 hooks：** 執行 `memoria setup --serve --json`，接著參考 [API 文件](https://npmcn.com/package/%40raybird.chen/memoria/docs/API.zh-TW.md) 或 [SDK 與 Agent 整合](https://npmcn.com/package/%40raybird.chen/memoria/docs/INTEGRATIONS.zh-TW.md)。
-   **語意召回：** 在 `memoria setup` 選擇 `--vector` 會一次完成依賴安裝、本地模型暖機、樹狀索引建立、全量記憶寫入 `<memoria-home>/.memory/vectors.db` 以及就緒驗證。進階診斷與修復流程見 [Semantic Recall Operations](https://npmcn.com/package/%40raybird.chen/memoria/docs/OPERATIONS.md#semantic-recall-operations-optional)。
-   **Repository 記憶：** 從 `memoria repo add /path/to/project` 開始，詳見 [Git-Aware Memory Operations](https://npmcn.com/package/%40raybird.chen/memoria/docs/OPERATIONS.md#git-aware-memory-operations)。

## 文件導覽

| 指南 | 內容 |
| --- | --- |
| [安裝](https://npmcn.com/package/%40raybird.chen/memoria/docs/INSTALL.md) | npm、獨立安裝包、資料路徑、部署 skill 與背景服務 |
| [CLI](https://npmcn.com/package/%40raybird.chen/memoria/docs/CLI.zh-TW.md) · [English](https://npmcn.com/package/%40raybird.chen/memoria/docs/CLI.md) | 命令、記憶標記、brief 產生與範圍 |
| [HTTP API](https://npmcn.com/package/%40raybird.chen/memoria/docs/API.zh-TW.md) · [English](https://npmcn.com/package/%40raybird.chen/memoria/docs/API.md) | 端點、請求範例與回傳語意 |
| [SDK 與 Agent 整合](https://npmcn.com/package/%40raybird.chen/memoria/docs/INTEGRATIONS.zh-TW.md) · [English](https://npmcn.com/package/%40raybird.chen/memoria/docs/INTEGRATIONS.md) | 原始碼 SDK 用法與 hook 設定 |
| [維運](https://npmcn.com/package/%40raybird.chen/memoria/docs/OPERATIONS.md) | 索引、向量修復、清理、備份與治理 |
| [MCP/libSQL](https://npmcn.com/package/%40raybird.chen/memoria/docs/MCP_INTEGRATION.md) | 選用的圖譜投射與增量同步 |
| [AGENTS.md](https://npmcn.com/package/%40raybird.chen/memoria/AGENTS.md) · [CLAUDE.md](https://npmcn.com/package/%40raybird.chen/memoria/CLAUDE.md) | 架構、開發命令與 agent 約定 |
| [規格](https://npmcn.com/package/%40raybird.chen/memoria/SPEC.md) · [路線圖](https://npmcn.com/package/%40raybird.chen/memoria/RFC.md) | 已實作行為與未來方向 |
| [版本紀錄](https://npmcn.com/package/%40raybird.chen/memoria/CHANGELOG.md) · [發版 SOP](https://npmcn.com/package/%40raybird.chen/memoria/RELEASE.md) | 版本歷史與維護者流程 |

最後驗證：2026-10-26，對照 issue-30 實作、CLI help 與文件檢查。工作台需要 v1.33.0 或更新版本。

## 授權

MIT

## 常见问题

### @raybird\.chen/memoria 是什么？

用于AI代理的交叉会话、可跟踪、自托管持久内存-SQLite-backed CLI\+HTTP API\+Node SDK。

### 如何安装 @raybird\.chen/memoria？

在项目目录运行 npm install @raybird\.chen/memoria，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 memoria，可以用 npx memoria 直接运行。

### @raybird\.chen/memoria 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/raybird\.chen\_\_memoria 是否存在。

### @raybird\.chen/memoria 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @raybird\.chen/memoria 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @raybird\.chen/memoria 可以商用吗？

@raybird\.chen/memoria 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @raybird\.chen/memoria 还在维护吗？

最新版本 1\.36\.1 发布于 2026/11/02（1 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 45 个；首次发布于 2026/05/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。