Graphmem README

Graphmem

Shared, local memory for coding agents. Keep project decisions across sessions and tools with SQLite storage, local semantic search, and linked entities. Claude Code, Codex, OpenCode, pi, and other MCP clients can share the same store.

Optional code tools find definitions, outline files, list imports, and compare symbols between Git revisions.

Install

npm install --global @sonic182/graphmem
gmem-install
gmem version

The npm package contains launchers. gmem-install explicitly downloads and verifies the matching CPU binary, or reuses a working native gmem on your PATH. Package installation itself downloads no binary. After upgrading the package, run gmem-install again; separately installed binaries are not replaced.

MCP clients that launch servers with npx can run npx -y @sonic182/graphmem mcp. The graphmem command downloads and verifies the binary on its first run; gmem never downloads anything on its own.

Alternatively, download your platform's archive from GitHub Releases, verify it against SHA256SUMS, and put the extracted executable on your PATH. Linux releases require glibc 2.39 and OpenSSL 3. For other systems or CUDA, build from source.

Use it with your coding agent

Plugins include MCP registration, skills, and guidance to recall context before work and save durable decisions afterward.

Claude Code and Codex need gmem and Node.js on PATH. In Codex, trust the Graphmem hooks in /hooks and start a new thread. Pi offers binary setup on first startup; OpenCode prints an installer command if needed.

See plugin setup and troubleshooting.

For another MCP client, configure it to launch your installed binary:

{
  "mcpServers": {
    "graphmem": {
      "command": "/absolute/path/to/gmem",
      "args": ["mcp"]
    }
  }
}

CLI

gmem remember "Use nextest for integration tests" \
  --type convention --scope repo:/absolute/path/to/project
gmem search "integration tests"
gmem tui
gmem mcp

Memories default to the current Git repository; git must be on PATH. Outside a repository, the default scope is global. Reads always include global memories; explicitly select other projects with --scope (CLI) or scopes (MCP). Writes are limited to the current repository and global, including updates and deletions. The MCP list_scopes tool discovers scopes and their write permissions. Data lives in ~/.graphmem; set GRAPHMEM_HOME to use another directory.

CLI reference · MCP tool reference

Code navigation (optional)

Release binaries include these tools; source builds need --features code.

gmem code find CodeService
gmem code outline src/application/code.rs
gmem code imports src/application/code.rs
gmem code diff origin/master

These tools work on Git checkouts without an embedding model. They index definitions, not call sites or references; use ast-grep for those. Set GRAPHMEM_CODE=off to disable code tools.

Options and supported languages · Benchmark results and limitations

Configuration

No config file is required. To customize embeddings, retrieval, or code indexing, create ~/.graphmem/config.toml. See the configuration reference.

Build

See source builds and CUDA setup.

Development

just verify

Runs formatting checks, compilation, Clippy, and tests. Design · Schema evolution

To preview the documentation site, run hugo server --source site. See site setup.

License

MIT.