{
  "markdown": "# gmem\n\n**Persistent project memory for Solana AI agents.**\n\nA Model Context Protocol (MCP) server that gives AI coding agents — Claude Code, Cursor,\nor anything that speaks MCP — durable, Solana-aware memory of a project across sessions:\nprogram IDs, IDLs, PDA seeds, deployment state, architectural decisions, audit findings.\nSo agents stop forgetting what they built yesterday.\n\nStatus: **v1.1 — stable, with EVM support.**\nSeven MCP tools, real implementations (no stubs), backward-compatible wire format:\n- Storage: SQLite via better-sqlite3, one db file per project (auto-resolved from\n  `Anchor.toml` / workspace `Cargo.toml`, override with `GMEM_DB`)\n- Ranking: SQLite FTS5 BM25 with a recency boost\n- Versioning: append-only — every write inserts a new `(kind, natural_id, version)` row;\n  reads return the latest; full history available via the in-process `Store` API\n- Anchor ingest: `gmem.ingest_anchor` parses `Anchor.toml`, captures IDL sha256s,\n  records git HEAD as `sourceCommit` per Program\n- Solana CLI context: `gmem.solana_context` reads `~/.config/solana/cli/config.yml`,\n  classifies the cluster, derives the active keypair's pubkey (secret never leaks).\n  `gmem.write` on a Decision auto-attributes `author` + `authorCluster`\n- Git-aware diff: `gmem.diff` accepts both ISO timestamps and git refs (HEAD, HEAD~3,\n  branch names, full and short SHAs)\n- EVM support (v1.1): `gmem.ingest_hardhat` parses Hardhat / `hardhat-deploy` workspaces,\n  classifies networks into canonical chain ids (base-mainnet 8453, optimism-mainnet 10,\n  polygon-mainnet 137, arbitrum-one 42161, ethereum-mainnet 1, plus testnets), captures\n  a reorder-invariant ABI SHA-256. New `Contract` entity kind for EVM smart contracts.\n\n- License: MIT\n- Spec: see [`SPEC.md`](./SPEC.md)\n- Entity schemas: see [`schema/`](./schema/)\n\n## Why\n\nSolana has moved decisively toward an agent-first developer experience. The Foundation's\n`awesome-solana-ai` repo indexes a strong layer of *stateless* reference skills —\n`solana-dev-skill`, `magicblock-dev-skill`, `metaplex-skill`, `helius-phantom-skill`,\n`solana-game-skill`, and more — that teach agents *how* to do things. The Solana\nDeveloper MCP exposes documentation. What's missing is the layer above: **persistent\nproject memory.**\n\nToday every Claude Code session on a Solana project starts cold. The agent doesn't\nremember the program ID it deployed yesterday, the PDA seeds it chose two weeks ago, the\naudit finding from last sprint, or why a specific Jupiter integration was rejected. The\ndeveloper compensates by pasting context, hand-maintaining NOTES files, or re-explaining\nthe project every session. That is a tax on every agent-assisted Solana developer.\n\ngmem fixes this by being **opinionated about Solana primitives** — programs, accounts,\ninstructions, PDAs, IDLs, cluster state, Anchor configs — rather than being a generic\nkey-value store. It complements every existing skill in `awesome-solana-ai` rather than\ncompeting with any of them.\n\n## Install\n\n```bash\nnpm install -g @yksanjo/gmem\n```\n\nOr, to run it without a global install:\n\n```bash\nnpx @yksanjo/gmem\n```\n\nThe installed binary is still called `gmem`.\n\nOr, to hack on the source:\n\n```bash\ngit clone https://github.com/yksanjo/gmem.git ~/gmem\ncd ~/gmem && npm install && npm run build\n```\n\nThen point your MCP client at it. For Claude Code:\n\n```jsonc\n// ~/.claude/mcp_servers.json\n{\n  \"mcpServers\": {\n    \"gmem\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/gmem/dist/index.js\"],\n      \"env\": { \"GMEM_DB\": \"~/.gmem/memory.db\" }\n    }\n  }\n}\n```\n\n## Tools exposed (v0.1)\n\n| Tool | Purpose |\n| ---- | ------- |\n| `gmem.recall(query)` | Retrieve memory entries relevant to a natural-language query, ranked by BM25 + recency |\n| `gmem.write(entity)` | Persist a typed memory entry (Program / Account / Instruction / Decision / Finding / Integration); append-only |\n| `gmem.diff(from, to)` | Show how memory state changed between two points in time — accepts ISO timestamps OR git commit refs (HEAD, HEAD~3, branch names, full or short SHAs) |\n| `gmem.list_decisions()` | List all `Decision` entries for the active project, newest first |\n| `gmem.ingest_anchor()` | Auto-ingest an Anchor workspace: parse `Anchor.toml`, capture IDL sha256s from `target/idl/`, record the current git HEAD as source commit, write one Program per (program, cluster) pair |\n| `gmem.solana_context()` | Read the active Solana CLI config (`~/.config/solana/cli/config.yml`), return the configured cluster + RPC URL + active-keypair pubkey. Used by `gmem.write` to auto-attribute Decision entries to the developer wallet. Never returns the secret key. |\n| `gmem.ingest_hardhat()` | **v1.1** — Auto-ingest a Hardhat / EVM workspace: parses `hardhat.config.{ts,js,cjs,mjs}`, reads every deployment artifact under `deployments/<network>/<Contract>.json` (the hardhat-deploy convention), classifies the network into a canonical chain (base-mainnet, optimism-mainnet, etc.), records a reorder-invariant ABI SHA-256 and git HEAD as `sourceCommit`. Writes one Contract entity per (chain, address) pair. |\n\nFull input/output JSON schemas are in [`SPEC.md`](./SPEC.md).\n\n## Worked against real Solana projects\n\nThe `examples/` folder in this repo demonstrates the *shape* of project memory\nwith synthetic projects. These companion repos build the same shape from\n**public Solana programs you've probably heard of**, with every entity citing\nits source:\n\n- [**gmem-example-squads-v4**](https://github.com/yksanjo/gmem-example-squads-v4) —\n  Squads multisig. Anchor workspace auto-ingest + audit pointers.\n- [**gmem-example-marginfi-v2**](https://github.com/yksanjo/gmem-example-marginfi-v2) —\n  Marginfi v2 lending. IDL-driven discovery of the embedded Drift integration\n  (6 `drift_*` instructions surfaced automatically).\n- [**gmem-example-kamino-klend**](https://github.com/yksanjo/gmem-example-kamino-klend) —\n  Kamino klend. V1/V2 coexistence pattern, first-class flash loans, on-chain\n  referrer state, sustained per-minor-release audit cadence — all recorded as\n  `Decision` entries.\n\nEach repo is `npm install && npm run build`-runnable; the resulting `gmem.db`\nis committed for direct inspection.\n\n## Out of scope for v1.0\n\nTo keep the v1 scope honest, gmem v1.0 does NOT include: hosted multi-user sync,\ncross-project search, agent reputation, on-chain memory anchoring. These are tracked in\n[`ROADMAP.md`](./ROADMAP.md) for v1.x / v2.\n\n## Roadmap\n\n- [x] v0.1 — Open spec + JSON schemas + MCP server stub\n- [x] v0.2 — SQLite backend, BM25 ranking, append-only versioning\n- [x] v0.3 — Anchor workspace auto-ingest\n- [x] v0.4 — Solana CLI context capture + Decision auto-attribution\n- [x] v0.5 — git ref resolution in `gmem.diff`\n- [x] v1.0 — Stable release with three worked examples ([DeFi vault](./examples/01-defi-vault/),\n  [cNFT mint](./examples/02-cnft-mint/), [AI agent](./examples/03-ai-agent/)) — see also\n  [PR #168 in `solana-foundation/awesome-solana-ai`](https://github.com/solana-foundation/awesome-solana-ai/pull/168)\n- [x] v1.1 — EVM / Hardhat support (Base, Optimism, Polygon, Arbitrum, Ethereum, plus testnets),\n  new `Contract` entity, `gmem.ingest_hardhat` tool, [worked example 04-evm-vault](./examples/04-evm-vault/)\n\n## Contributing\n\nThis is an early-stage spec. The most useful thing right now is feedback on\n[`SPEC.md`](./SPEC.md) — does the entity model cover the Solana primitives that matter\nto *your* project? Open an issue or PR.\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE).\n",
  "bytes": 7507,
  "sha": "357317b8c59d8c90256dfc4320d7d9fdaaf1c16551980d7a2b94647e81bd6442",
  "repo_slug": "yksanjo/gmem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yksanjo_gmem_4449525a/readme"
}