io.github.yksanjo/gmem
Persistent, Solana-aware project memory for AI coding agents. Typed entities + git-aware diffs.
Open source Open in the app JSON README (API)
About
Persistent, Solana-aware project memory for AI coding agents. Typed entities + git-aware diffs.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- yksanjo
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Stars
- 1
- Last push
- 2026-07-09T22:09:50Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:42
- Updated
- 2026-08-29 04:01:42
- Origin id
io.github.yksanjo/gmem
README
# 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`](./SPEC.md)
- Entity schemas: see [`schema/`](./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
```bash
npm install -g @yksanjo/gmem
```
Or, to run it without a global install:
```bash
npx @yksanjo/gmem
```
The installed binary is still called `gmem`.
Or, to hack on the source:
```bash
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:
```jsonc
// ~/.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`](./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**](https://github.com/yksanjo/gmem-example-squads-v4) —
Squads multisig. Anchor workspace auto-ingest + audit pointers.
- [**gmem-example-marginfi-v2**](https://github.com/yksanjo/gmem-example-marginfi-v2) —
Marginfi v2 lending. IDL-driven discovery of the embedded Drift integration
(6 `drift_*` instructions surfaced automatically).
- [**gmem-example-kamino-klend**](https://github.com/yksanjo/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`](./ROADMAP.md) for v1.x / v2.
## Roadmap
- [x] v0.1 — Open spec + JSON schemas + MCP server stub
- [x] v0.2 — SQLite backend, BM25 ranking, append-only versioning
- [x] v0.3 — Anchor workspace auto-ingest
- [x] v0.4 — Solana CLI context capture + Decision auto-attribution
- [x] v0.5 — git ref resolution in `gmem.diff`
- [x] v1.0 — Stable release with three worked examples ([DeFi vault](./examples/01-defi-vault/),
[cNFT mint](./examples/02-cnft-mint/), [AI agent](./examples/03-ai-agent/)) — see also
[PR #168 in `solana-foundation/awesome-solana-ai`](https://github.com/solana-foundation/awesome-solana-ai/pull/168)
- [x] v1.1 — EVM / Hardhat support (Base, Optimism, Polygon, Arbitrum, Ethereum, plus testnets),
new `Contract` entity, `gmem.ingest_hardhat` tool, [worked example 04-evm-vault](./examples/04-evm-vault/)
## Contributing
This is an early-stage spec. The most useful thing right now is feedback on
[`SPEC.md`](./SPEC.md) — does the entity model cover the Solana primitives that matter
to *your* project? Open an issue or PR.
## License
MIT — see [`LICENSE`](./LICENSE).