The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gmem listing page.
Persistent project memory for Solana AI agents.
A Model Context Protocol (MCP) server that gives AI coding agents — Claude Code, Cursor, or anything that speaks MCP — durable, Solana-aware memory of a project across sessions: program IDs, IDLs, PDA seeds, deployment state, architectural decisions, audit findings. So agents stop forgetting what they built yesterday.
Status: v1.1 — stable, with EVM support. Seven MCP tools, real implementations (no stubs), backward-compatible wire format:
Storage: SQLite via better-sqlite3, one db file per project (auto-resolved from
Anchor.toml / workspace Cargo.toml, override with GMEM_DB)
Ranking: SQLite FTS5 BM25 with a recency boost
Versioning: append-only — every write inserts a new (kind, natural_id, version) row;
reads return the latest; full history available via the in-process Store API
Anchor ingest: gmem.ingest_anchor parses Anchor.toml, captures IDL sha256s,
records git HEAD as sourceCommit per Program
Solana CLI context: gmem.solana_context reads ~/.config/solana/cli/config.yml,
classifies the cluster, derives the active keypair's pubkey (secret never leaks).
gmem.write on a Decision auto-attributes author + authorCluster
Git-aware diff: gmem.diff accepts both ISO timestamps and git refs (HEAD, HEAD~3,
branch names, full and short SHAs)
EVM support (v1.1): gmem.ingest_hardhat parses Hardhat / hardhat-deploy workspaces,
classifies networks into canonical chain ids (base-mainnet 8453, optimism-mainnet 10,
polygon-mainnet 137, arbitrum-one 42161, ethereum-mainnet 1, plus testnets), captures
a reorder-invariant ABI SHA-256. New Contract entity kind for EVM smart contracts.
License: MIT
Spec: see SPEC.md
Entity schemas: see schema/
Solana has moved decisively toward an agent-first developer experience. The Foundation's
awesome-solana-ai repo indexes a strong layer of stateless reference skills —
solana-dev-skill, magicblock-dev-skill, metaplex-skill, helius-phantom-skill,
solana-game-skill, and more — that teach agents how to do things. The Solana
Developer MCP exposes documentation. What's missing is the layer above: persistent
project memory.
Today every Claude Code session on a Solana project starts cold. The agent doesn't remember the program ID it deployed yesterday, the PDA seeds it chose two weeks ago, the audit finding from last sprint, or why a specific Jupiter integration was rejected. The developer compensates by pasting context, hand-maintaining NOTES files, or re-explaining the project every session. That is a tax on every agent-assisted Solana developer.
gmem fixes this by being opinionated about Solana primitives — programs, accounts,
instructions, PDAs, IDLs, cluster state, Anchor configs — rather than being a generic
key-value store. It complements every existing skill in awesome-solana-ai rather than
competing with any of them.
Or, to run it without a global install:
The installed binary is still called gmem.
Or, to hack on the source:
Then point your MCP client at it. For Claude Code:
| Tool | Purpose |
|---|---|
gmem.recall(query) | Retrieve memory entries relevant to a natural-language query, ranked by BM25 + recency |
gmem.write(entity) | Persist a typed memory entry (Program / Account / Instruction / Decision / Finding / Integration); append-only |
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) |
gmem.list_decisions() | List all Decision entries for the active project, newest first |
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 |
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. |
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. |
Full input/output JSON schemas are in SPEC.md.
The examples/ folder in this repo demonstrates the shape of project memory
with synthetic projects. These companion repos build the same shape from
public Solana programs you've probably heard of, with every entity citing
its source:
drift_* instructions surfaced automatically).Decision entries.Each repo is npm install && npm run build-runnable; the resulting gmem.db
is committed for direct inspection.
To keep the v1 scope honest, gmem v1.0 does NOT include: hosted multi-user sync,
cross-project search, agent reputation, on-chain memory anchoring. These are tracked in
ROADMAP.md for v1.x / v2.
gmem.diffsolana-foundation/awesome-solana-aiContract entity, gmem.ingest_hardhat tool, worked example 04-evm-vaultThis is an early-stage spec. The most useful thing right now is feedback on
SPEC.md — does the entity model cover the Solana primitives that matter
to your project? Open an issue or PR.
MIT — see LICENSE.