agentmemory 官网技术解析：Next.js 15 零配置落地页、黑金设计系统与 Vercel 部署实战-育师

agentmemory 官网技术解析：Next.js 15 零配置落地页、黑金设计系统与 Vercel 部署实战

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

agentmemory 是一个基于真实基准测试的 AI 编码 Agent 持久化记忆方案（#1 Persistent memory for AI coding agents based on real-world benchmarks），本仓库为其配套的官方落地页（Landing Page）工程。本文以 website/README.md 为骨架，结合仓库内真实源码，完整讲解这套网站的技术栈选型、本地开发、Vercel 零配置部署、目录结构与各组件职责，以及由 DESIGN.md 定义的"兰博基尼风格"黑金设计系统——读完你既能直接跑起并上线这个官网，也能复用它的架构思路为任何 Next.js 项目搭建高表现力的营销站。

项目定位：为 agentmemory 服务的单页营销站

website/是 agentmemory 项目的官方网站工程，其核心任务只有一个：清晰、有冲击力地向开发者传达"给 AI 编码 Agent 一份跨会话持久记忆"的产品价值，并引导完成安装。整站采用 Next.js 15 App Router 构建，视觉上以"兰博基尼灵感"的黑金（black + gold）设计语言贯穿始终，部署到 Vercel 时无需任何环境变量配置，即"零配置（zero config）"上线。

从 website/app/page.tsx 的页面组装顺序可以看到完整的信息架构：

ScrollProgress → Nav → Hero → Stats → Primitives → Features → CommandCenter → LiveTerminal → Compare → Testimonials → Agents → Install → Footer

先讲价值主张（Hero），再用数据（Stats）与核心原语（Primitives/Features）建立信任，接着用可交互的"记忆回放终端"（LiveTerminal）做可视化演示，最后对比同类方案（Compare）、列出支持的工具链（Agents）并以一键安装（Install）收尾——整条叙事线服务于"看完就想装"这一个转化目标。

技术栈选型：极简、无构建配置、无客户端路由

README 明确列出的技术栈如下：

Next.js 15.1，App Router 模式，React 19，TypeScript 5.7
通过next/font加载Archivo + JetBrains Mono两套字体（正文与等宽代码字体）
CSS Modules+ 单一globals.css，无 Tailwind、无打包器配置文件、无客户端路由（即不引入 react-router 之类方案）

这里有两个值得留意的细节：

无客户端路由意味着站内导航全部是锚点跳转（如#features、#install），唯一的例外是 Nav 里的Docs链接，指向/docs路径。
仓库当前的 package.json 与 README 记录存在版本演进：README 写的是 Next.js 15.1 / TypeScript 5.7，而 website/package.json 实际声明next ^16.2.7、react ^19.2.7、typescript ^6.0.3，并规定engines.node >= 20。阅读和升级时以 package.json 为准，README 描述的是设计时的目标栈。

依赖面极窄是这套工程刻意保持的风格：运行时依赖只有next、react、react-dom三个包，外加一个postcss的 overrides 固定版本。对比动辄几十个依赖的营销站工程，这种克制让构建速度与可维护性都显著提升。

本地开发：三行命令跑起来

README 给出的本地开发流程非常直接：

cd website npm install npm run dev # 打开 http://localhost:3000

需要注意的是，由于仓库根目录的package.json才是 agentmemory 主包的清单，npm install必须在website/子目录内执行，才能安装官网自身的依赖。npm run dev会先触发predev钩子（见下文"构建期元数据生成"一节），随后由next dev启动开发服务器，默认端口 3000。

开发服务器就绪后，你可以直接体验页面上多个客户端交互：

Hero 区的npx命令展示（HeroNpxCommand.tsx 等）与 MemoryGraph 画布动画；
LiveTerminal 区的终端打字机回放；
Install 区的点击复制命令按钮。

部署到 Vercel：两种方式，均零配置

README 提供了两条部署路径，任选其一即可：

导入仓库方式：在 vercel.com 导入本仓库，将Root Directory（根目录）设置为website/，其余保持默认即可。
CLI 方式：在website/目录下执行npx vercel。

两种方式的共同前提：

无需任何环境变量（No env vars required）；
Node 20 LTS 或更高版本（与 website/package.json 中engines.node >= 20一致）。

这里有一条重要的实操提醒，来自 website/scripts/gen-meta.mjs 的报错信息：Vercel 上必须检出完整仓库（full repo）而不仅是website/子目录，因为构建期脚本要向上读取仓库根目录的package.json版本号以及src/、test/下的源码统计信息；如果只上传了 website 目录，脚本会直接抛错失败。也就是说，"Root Directory 设为 website/"并不代表可以只把 website 目录推上去。

构建期元数据生成：gen-meta 机制

这是本工程一个很有价值的工程细节，值得单独说明。package.json中dev、build均带前置钩子：

"predev": "node scripts/gen-meta.mjs", "prebuild": "node scripts/gen-meta.mjs"

website/scripts/gen-meta.mjs 会在每次 dev/build 之前：

向上定位仓库根目录（website/的上一级）；
读取根目录package.json的version字段；
统计MCP 工具数：扫描 src/mcp/tools-registry.ts 中name: "memory_前缀的注册项；
统计Hook 类型数：解析 src/types.ts 中export type HookType联合类型里的字符串成员；
统计REST 端点数：扫描 src/triggers/api.ts 中config: { api_path: "的配置项；
统计测试用例数：递归遍历 test/ 目录，按it(/test(计数；
将结果写入 website/lib/generated-meta.json。

随后 website/lib/meta.ts（标注为import "server-only"）在构建时把这份 JSON 静态导入，供 Stats、Features、LiveTerminal 等组件展示。脚本注释解释了为什么必须这样设计：meta.ts曾尝试用import.meta.url在运行时读取仓库文件，但 Next.js 会把服务端组件编译进.next/server/，此时../..会落到构建缓存内部而非仓库根目录，导致版本号静默回退成0.0.0；改为构建期解析 + 静态 JSON 导入后彻底规避了该问题。脚本还内置了兜底默认值（45 个工具、12 个 hook、107 个端点、794 个测试），即使统计失败页面也不会白屏。

目录结构与组件职责拆解

README 给出了完整的目录结构，逐项说明如下（均已结合源码核实）：

website/ app/ layout.tsx — <html> + 字体 + metadata + viewport page.tsx — 按顺序组装各落地页区块 globals.css — 设计令牌、按钮、section-head 工具类 components/ Nav.tsx — 六边形公牛标识 + 菜单 Hero.tsx — 标题 + 导语 + CTA MemoryGraph.tsx — 客户端 canvas 动画 + 六边形暂停 + 滚动轨道 Stats.tsx — 交叉进入视口时数字滚动 Primitives.tsx — 三张卡片，3D 鼠标倾斜效果 LiveTerminal.tsx — memory.recall 与 consolidate 的打字机回放 Compare.tsx — agentmemory vs Mem0/Letta/Cognee 对比表 Agents.tsx — 已支持 Agent 的网格 Install.tsx — 点击复制 npm 与控制台命令 Footer.tsx — 源码 / 变更日志 / 许可证链接 ScrollProgress.tsx — 视口顶部的金色细进度条 next.config.ts tsconfig.json package.json

app/layout.tsx：全局骨架

website/app/layout.tsx 承担三件事：

字体加载：通过next/font/google加载 Inter（映射到--font-sans）与 JetBrains Mono（映射到--font-mono，取 400/500 两个字重），并以 CSS 变量形式注入<html>，避免额外网络请求和布局偏移。注意：README 中的 "Archivo" 与当前源码实际使用的 Inter 有出入，以 layout.tsx 为准。
Metadata 与 Viewport：设置metadataBase为https://agentmemory.dev、页面标题与描述、favicon（/icon.svg）、Open Graph 与 Twitter 卡片；viewport中themeColor: "#0a0a0a"与黑金主题呼应。
全局样式引入：import "./globals.css"。

app/page.tsx：服务端组装 + 客户端岛屿

website/app/page.tsx 是一个服务端组件：先调用getProjectMeta()读取构建期生成的统计元数据，再按顺序渲染各个区块组件，并把mcpTools、hooks、restEndpoints作为 props 传给 Stats、Features、CommandCenter、LiveTerminal。

README 特别强调的架构约定是：每个交互组件都是"use client"岛屿，其余全部在服务端渲染。这正符合 Next.js App Router 的推荐模式——静态内容不携带任何客户端 JS，只有真正需要浏览器能力的组件（canvas 动画、IntersectionObserver、剪贴板、状态切换）才声明为客户端组件，从而把首屏 JS 体积压到最小。

Nav.tsx：服务端数据 + 锚点导航

Nav.tsx 是服务端组件，内部通过fetchRepoStats()（来自 website/lib/github.ts）在服务端拉取 GitHub 仓库 Star 数，经formatCompact格式化后展示在导航右侧的 GitHub 入口上。导航项为锚点列表（Stack / Features / Control / Demo / Agents / Install / Docs），移动端由 MobileNavToggle.tsx 接管。

Hero.tsx 与 MemoryGraph.tsx：开场视觉

Hero.tsx 的芯片区动态显示v{meta.version}（即构建期从根 package.json 读到的版本号），导语引用了 LongMemEval-S 上 95.2% 的检索召回率数据——该数据在 website/components/Compare.tsx 中同样出现，且 Compare 组件特别声明"只有 agentmemory 的数字是我们自己测的、可在仓库复现，竞品数字是它们各自基准上的公开声明，仅供参考"，体现了严谨的举证态度。

MemoryGraph.tsx 是 Hero 区的环境动画：一块 canvas 上以 26px 间距铺设点阵，用正弦波叠加计算每点透明度（上限 0.13 alpha），配合轻微漂移形成"静谧星野"效果；它同时实现了两个滚动 UI——六边形暂停状态与右侧金色滚动轨道。值得称道的是性能与无障碍处理：使用devicePixelRatio适配高清屏、requestAnimationFrame驱动、监听 resize 重绘，并尊重prefers-reduced-motion（系统开启"减少动态效果"时只渲染一帧静态画面，不再动画）。

LiveTerminal.tsx：把记忆能力"演"出来

LiveTerminal.tsx 是整页最有说服力的演示组件：它在终端窗口里逐字"打字"回放一段真实的 agentmemory 使用脚本：

$ npx @agentmemory/agentmemory [agentmemory] iii-engine ready on :3111 [agentmemory] {mcpTools} MCP tools registered [agentmemory] {hooks} autohooks armed $ memory.recall({ query: "where did we land the retry logic?" }) // hybrid retrieval: BM25 + vector + graph ✓ 3 memories · reranked on device → src/retry.ts:47 · exponentialBackoff(max=5, jitter=true) → commit 8f2e14c · "resolve conflict + honor x-amz headers" → session 2026-04-16 · "bug: race when Retry-After is empty" $ memory.consolidate({ project: 'pay-api' }) ✓ raw observations → semantic memories · audit rows written

其中{mcpTools}、{hooks}由构建期元数据注入真实数字。实现上，组件用 IntersectionObserver 在滚动到视口 40% 时自动播放一次（只播一次），逐字符定时渲染，prefers-reduced-motion时零延迟完成；底部提供Replay按钮随时重播，右上角终端标题agentmemory@localhost:3111呼应了 agentmemory 服务实际监听 3111 端口的事实。

Install.tsx：三步安装 + 点击复制

Install.tsx 是转化漏斗的终点，提供了四条命令：

步骤	命令	说明
1. 安装一次	`npm install -g @agentmemory/agentmemory`	把`agentmemory`放入 PATH
2. 启动记忆服务	`agentmemory`	运行于 :3111，查看器在 :3113
3. 运行演示	`agentmemory demo`	播种 3 个会话，展示真实数据上的混合检索
零安装替代	`npx @agentmemory/agentmemory`	用 npx 缓存取代第 1+2 步，注意 README 中的注意事项

每条命令都是可点击复制的CopyBox按钮（navigator.clipboard.writeText，复制成功短暂显示 "COPIED"）。区块导语还交代了关键的模型策略：本地捕获与检索不需要 LLM 密钥；只有要启用 consolidation、图抽取与 LLM 压缩时才需要为 Anthropic / OpenAI / Gemini / MiniMax / OpenRouter 配置密钥——这与仓库主 README 的能力划分一致。

Compare.tsx：对比表的数据边界

Compare.tsx 渲染一张 agentmemory 与 Mem0 / Letta / Zep(Graphiti) 的对比表，维度包括检索召回率、外部依赖（agentmemory 为 0）、REST 端点数、MCP 工具数、自动捕获 hook、原生 Agent 插件数（6）与开源协议（Apache-2.0）。组件源码中明确写了免责声明式导语：竞品数字来自对方各自基准的公开声明，展示目的只是给出量级参考（ballpark），只有 agentmemory 一行是可复现的实测值。作为技术文章引用时也请沿用同样的边界表述。

设计系统：源自兰博基尼的黑金规范

README 明确指出设计系统的唯一权威来源是仓库根目录的 DESIGN.md，它由npx getdesign@latest add lamborghini生成，并约定"每一个新组件都应先参考它"。核心规范摘要如下：

色彩：绝对黑#000000作为主导表面；兰博基尼金#FFC000是唯一强调色，且只用于主 CTA 按钮；纯白#FFFFFF承载文字；悬停态用暗金#917300、幽灵按钮悬停用青色#1EAEDB；中性灰从#181818→#202020→#494949→#7D7D7D逐级提亮，用"表面变亮"代替投影来表达层级。
排版：全大写是默认语态；显示标题用 400 常规字重 + 0.92–1.19 的紧凑行高；无斜体；标题字号从 120px 的 Hero 级到 10px 的微标签，形成 12:1 的戏剧性层级跨度。
圆角：按钮与卡片一律0px直角（"锐利、棱角分明"），全站唯一允许圆角的是 20px 的开关组件。
动效约束：悬停交互只允许颜色/透明度变化，禁止 scale 或 translate 动画；深度靠表面色阶而非阴影——在黑底上阴影没有意义。
间距：基础单位 8px，按钮内边距幽灵态 16px / 金色主按钮 24px，区块纵向 48–56px。
触控目标：CTA 高度不小于 48px，超过 WCAG 44×44px 要求。

在 website/app/globals.css 中，这些令牌落地为.btn--accent（金色主按钮）、.btn--ghost（透明幽灵按钮）、.section-head/.section-eyebrow/.section-title/.section-lede等工具类，页面各区块统一复用，保证全站视觉一致。

动手实践建议

想在本地完整跑通：先确认 Node ≥ 20（node -v），再cd website && npm install && npm run dev；首次启动会自动生成lib/generated-meta.json，若该文件缺失或数字异常，检查是否在仓库根目录执行了构建脚本。
想自定义视觉：不要零散改各组件 CSS，先读 DESIGN.md 的调色板与排版表，再统一调整 globals.css 中的设计令牌，最后才动组件级 CSS Module。
想新增区块：遵循"服务端组件为主体、"use client"岛屿只留给交互"的约定，在 page.tsx 中按顺序插入，并在 DESIGN.md 中核对新组件用色、字号与圆角是否符合黑金规范。
想上线：按 README 的两种 Vercel 方式任选其一，注意必须检出完整仓库（构建脚本需要根目录的版本号与源码统计），无需配置任何环境变量。

总结

website/这份工程的价值不止于"一个官网"，而是一套可复制的营销站方法论：极简依赖与零构建配置让任何人三分钟内跑起来；构建期从真实源码统计并注入版本、工具数、测试数等动态数据，让营销页上的每一个数字都"长在仓库上"、可随发版自动更新；服务端组件 + 客户端岛屿的架构在表现力与性能间取得平衡；黑金设计系统则用一份权威规范文档约束所有新组件。对想要搭建技术产品落地页的团队而言，这份 README 连同 DESIGN.md 本身就是一份高质量的参考实现。

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

agentmemory 官网技术解析：Next.js 15 零配置落地页、黑金设计系统与 Vercel 部署实战