Yksanjo/Gmem

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/

Why

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.

Install

npm install -g @yksanjo/gmem

Or, to run it without a global install:

npx @yksanjo/gmem

The installed binary is still called gmem.

Or, to hack on the source:

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

Then point your MCP client at it. For Claude Code:

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

Tools exposed (v0.1)

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.

Worked against real Solana projects

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:

• gmem-example-squads-v4 — Squads multisig. Anchor workspace auto-ingest + audit pointers.
• gmem-example-marginfi-v2 — Marginfi v2 lending. IDL-driven discovery of the embedded Drift integration (6 drift_* instructions surfaced automatically).
• gmem-example-kamino-klend — Kamino klend. V1/V2 coexistence pattern, first-class flash loans, on-chain referrer state, sustained per-minor-release audit cadence — all recorded as Decision entries.

Each repo is npm install && npm run build-runnable; the resulting gmem.db is committed for direct inspection.

Out of scope for v1.0

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.

Roadmap

• v0.1 — Open spec + JSON schemas + MCP server stub
• v0.2 — SQLite backend, BM25 ranking, append-only versioning
• v0.3 — Anchor workspace auto-ingest
• v0.4 — Solana CLI context capture + Decision auto-attribution
• v0.5 — git ref resolution in gmem.diff
• v1.0 — Stable release with three worked examples (DeFi vault, cNFT mint, AI agent) — see also PR #168 in solana-foundation/awesome-solana-ai
• v1.1 — EVM / Hardhat support (Base, Optimism, Polygon, Arbitrum, Ethereum, plus testnets), new Contract entity, gmem.ingest_hardhat tool, worked example 04-evm-vault

Contributing

This 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.

License

MIT — see LICENSE.