gmem

gmem

为 Solana AI Agent 提供持久的项目记忆。

一个 Model Context Protocol（MCP）服务，为 AI 编码 Agent（Claude Code、Cursor 或任何支持 MCP 的工具）提供持久且了解 Solana 的项目记忆，让记忆跨会话保留：程序 ID、IDL、PDA 种子、部署状态、架构决策、审计发现。让 Agent 不再忘记昨天构建的内容。

状态：v1.2 — 稳定版，支持 EVM 和 Agent 信任评分。 九种 MCP 工具，均有真实实现（没有存根），线格式向后兼容：

• 存储：通过 better-sqlite3 使用 SQLite，每个项目一个数据库文件（从 Anchor.toml / 工作区 Cargo.toml 自动解析，可通过 GMEM_DB 覆盖）

• 排名：SQLite FTS5 BM25，并提升近期内容的排名

• 版本控制：仅追加——每次写入都会插入一条新的 (kind, natural_id, version) 记录；读取时返回最新记录；可通过进程内 Store API 查看完整历史

• Anchor 导入：gmem.ingest_anchor 会解析 Anchor.toml、记录 IDL sha256，并将 git HEAD 作为每个 Program 的 sourceCommit 记录

• Solana CLI 上下文：gmem.solana_context 会读取 ~/.config/solana/cli/config.yml、判定集群类型，并派生当前密钥对的公钥（不会泄露秘密信息）。 对 Decision 执行 gmem.write 时，会自动填入 author + authorCluster

• 感知 Git 的差异：gmem.diff 接受 ISO 时间戳和 git 引用（HEAD、HEAD~3、分支名称、完整及短 SHA）

• EVM 支持（v1.1）：gmem.ingest_hardhat 会解析 Hardhat / hardhat-deploy 工作区， 将网络分类为规范链 ID（base-mainnet 8453、optimism-mainnet 10、 polygon-mainnet 137、arbitrum-one 42161、ethereum-mainnet 1，以及测试网），并记录 与顺序无关的 ABI SHA-256。新增 EVM 智能合约实体类型 Contract。

• 许可证：MIT

• 规范：参见 SPEC.md

• 实体架构：参见 schema/

为什么需要它

Solana 正在坚定地转向以 Agent 为先的开发体验。Solana 基金会的 awesome-solana-ai 仓库收录了一系列强大的无状态参考技能—— solana-dev-skill、magicblock-dev-skill、metaplex-skill、helius-phantom-skill、 solana-game-skill 等——教 Agent 如何完成各项任务。Solana Developer MCP 提供文档。缺少的是更上一层：持久的项目记忆。

如今，每次 Claude Code 在 Solana 项目中启动会话时，都是从零开始。Agent 不会 记得昨天部署的程序 ID、两周前选定的 PDA 种子、上个冲刺周期的审计发现，也不记得 为何拒绝了某个特定的 Jupiter 集成。开发者只好粘贴上下文、手动维护 NOTES 文件， 或在每次会话中重新解释项目。这是每位借助 Agent 开发 Solana 的开发者都要付出的代价。

gmem 通过专注于 Solana 原语（程序、账户、指令、PDA、IDL、集群状态、 Anchor 配置），而不是充当通用键值存储，来解决这个问题。它与 awesome-solana-ai 中的所有现有技能互为补充，而非与之竞争。

安装

npm install -g @yksanjo/gmem

或者，不进行全局安装，直接运行：

npx @yksanjo/gmem

安装后的二进制文件仍名为 gmem。

或者，修改源代码：

git clone https://github.com/yksanjo/gmem.git ~/gmem
cd ~/gmem && npm install && npm run build

然后将 MCP 客户端指向它。以 Claude Code 为例：

// ~/.claude/mcp_servers.json
{
  "mcpServers": {
    "gmem": {
      "command": "node",
      "args": ["/absolute/path/to/gmem/dist/index.js"],
      "env": { "GMEM_DB": "~/.gmem/memory.db" }
    }
  }
}

暴露的工具（v0.1）

工具	用途
gmem.recall(query)	检索与自然语言查询相关的记忆条目，并按 BM25 + 时效性排序
gmem.write(entity)	持久化一个有类型的记忆条目（Program / Account / Instruction / Decision / Finding / Integration）；仅追加
gmem.diff(from, to)	显示两个时间点之间记忆状态的变化——接受 ISO 时间戳或 git 提交引用（HEAD、HEAD~3、分支名称、完整或简短 SHA）
gmem.list_decisions()	列出当前项目的所有 Decision 条目，按时间倒序排列
gmem.ingest_anchor()	自动导入 Anchor 工作区：解析 Anchor.toml，从 target/idl/ 获取 IDL sha256，记录当前 git HEAD 作为源提交，并为每个（程序、集群）对写入一个 Program
gmem.solana_context()	读取当前 Solana CLI 配置（~/.config/solana/cli/config.yml），返回已配置的集群、RPC URL 和当前密钥对的公钥。gmem.write 会使用此信息自动将 Decision 条目标记为开发者钱包所做。绝不会返回私钥。
gmem.ingest_hardhat()	v1.1 — 自动导入 Hardhat / EVM 工作区：解析 hardhat.config.{ts,js,cjs,mjs}，读取 deployments/<network>/<Contract>.json 下的每个部署产物（hardhat-deploy 约定），将网络归类为规范链（base-mainnet、optimism-mainnet 等），记录顺序无关的 ABI SHA-256 和 git HEAD 作为 sourceCommit。为每个（链、地址）对写入一个 Contract 实体。
gmem.ingest_agent_activity(pubkey, cluster?)	v1.2 — 通过 Helius RPC 获取自主 Agent 钱包的 Solana 活动并进行汇总（交易数、不同交互方、失败率、钱包使用时长、受制裁邻居数量），使用透明的 v1 启发式方法评分，并为每个（集群、公钥）写入一个 Agent 实体。设置 HELIUS_API_KEY 或传入 apiKey；fixturePath 可基于快照离线运行。
gmem.score_agent(pubkey, cluster?)	v1.2 — 返回最新存储的 Agent 信任评分，并显示各项因素对评分的影响。只读：不会调用 RPC，也不会写入数据——请先运行 gmem.ingest_agent_activity。

完整的输入/输出 JSON 架构见 SPEC.md。

在真实 Solana 项目中运行

此仓库中的 examples/ 文件夹通过合成项目展示了项目记忆的形式。这些配套仓库基于你可能听说过的公开 Solana 程序构建了相同形式，每个实体都会引用其来源：

• gmem-example-squads-v4 — Squads 多签。自动导入 Anchor 工作区 + 审计引用。
• gmem-example-marginfi-v2 — Marginfi v2 借贷。由 IDL 驱动的内嵌 Drift 集成发现 （自动呈现 6 条 drift_* 指令）。
• gmem-example-kamino-klend — Kamino klend。V1/V2 共存模式、一等闪电贷、链上推荐人状态、持续的次版本审计节奏——全部记录为 Decision 条目。

每个仓库都可通过 npm install && npm run build 运行；生成的 gmem.db 已提交，可直接检查。

v1.0 不包括的内容

为确保 v1 的范围表述准确，gmem v1.0 不包括：托管式多用户同步、跨项目搜索、Agent 声誉、链上记忆锚定。这些内容已列入 ROADMAP.md，计划用于 v1.x / v2。

路线图

• v0.1 — 开放规范 + JSON schemas + MCP 服务存根
• v0.2 — SQLite 后端、BM25 排序、仅追加版本控制
• v0.3 — 自动摄取 Anchor 工作区
• v0.4 — 捕获 Solana CLI 上下文 + Decision 自动归因
• v0.5 — 在 gmem.diff 中解析 git ref
• v1.0 — 稳定版发布，附带三个完整示例（DeFi 金库， cNFT 铸造、AI Agent）——另请参阅 solana-foundation/awesome-solana-ai 中的 PR #168
• v1.1 — 支持 EVM / Hardhat（Base、Optimism、Polygon、Arbitrum、Ethereum，以及测试网）， 新增 Contract 实体、gmem.ingest_hardhat 工具、完整示例 04-evm-vault
• v1.2 — Agent 信任评分：新增 Agent 实体、gmem.ingest_agent_activity + gmem.score_agent 工具、完整示例 05-agent-reputation、 MCP Registry 页面（server.json 1.2.0）

贡献

这是一份早期规范。目前最有帮助的是针对 SPEC.md 提供反馈——实体模型是否涵盖了对你的项目至关重要的 Solana 基元？欢迎提交 issue 或 PR。

许可证

MIT — 详见 LICENSE。