Gmem

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.2 — stable, with EVM support and agent trust scoring. Nine 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)

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
• v1.2 — Agent trust scoring: new Agent entity, gmem.ingest_agent_activity + gmem.score_agent tools, worked example 05-agent-reputation, MCP Registry surface (server.json 1.2.0)

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.