io.github.seanmarkwei/agentram-mcp
Model Context Protocol server for AgentRAM. Persistent memory for AI agents.
Open source Open in the app JSON README (API)
About
Model Context Protocol server for AgentRAM. Persistent memory for AI agents.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- seanmarkwei
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-08-12T02:02:56Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:22
- Updated
- 2026-08-29 04:01:22
- Origin id
io.github.seanmarkwei/agentram-mcp
README
# agentram-mcp
MCP server for [AgentRAM](https://agentram.dev). It gives your AI agents persistent memory through a set of tools, with no vector database and no embedding pipeline to set up. Get a key, paste the config below, and you're running in about a minute.
Works with any MCP client: Claude Desktop, Claude Code, Cline, Cursor, Windsurf, and others.
## Why
Every agent session starts with amnesia. AgentRAM is a plain HTTP memory store built for agents: one call to save something, one call to read it back. No infra to stand up, no vectors to babysit. This package wraps that API as MCP tools so your agent can just use it.
## Setup
You need an API key first. Register at [agentram.dev](https://agentram.dev) and it gets emailed to you. New accounts start with 1,000 credits and no card is required.
Then add this to your client's MCP config. For Claude Desktop that file is `claude_desktop_config.json` (on macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"agentram": {
"command": "npx",
"args": ["-y", "agentram-mcp"],
"env": {
"AGENTRAM_API_KEY": "agentram_your_key_here"
}
}
}
}
```
Restart the client and the tools show up. Most clients let you mark them "always allow" so you're not clicking approve on every call.
One gotcha on macOS: Claude Desktop doesn't ship with Node, so install Node 18 or newer first or the server won't start.
## Tools
Fifteen tools. Ten for flat memory, five for temporal memory (facts that change over time).
Flat memory:
- `store_memory`: save a value under a key for an agent
- `retrieve_memory`: read one back by key
- `list_memories`: list everything stored for an agent
- `search_memories`: text search across keys and values, no embeddings needed
- `delete_memory`: remove one
- `check_credits`: current balance, free to call
Shared memory, for when more than one agent needs the same pool:
- `create_namespace`: make a shared space, free to call
- `store_shared_memory`: write into it
- `retrieve_shared_memory`: read from it
- `list_shared_memories`: list what's in it
Temporal memory (assertions):
- `store_assertion`: record a fact that can change, like a plan, a status, or a preference
- `retire_assertion`: mark a fact as no longer true while keeping the history
- `get_assertion`: what's currently true for a key
- `list_assertions`: all the current facts for an agent
- `get_assertion_history`: the full chain of what a key has been over time
## About temporal memory
Flat memory overwrites. Temporal memory keeps the trail. When a fact changes you supersede the old value, and the previous values stick around so you can see how you got to the current one.
The part worth knowing: if two different values land on the same key and neither one supersedes the other, `get_assertion` will not quietly pick a winner. It tells you the key is contested and returns both values, so your agent can decide instead of running on a guess. `list_assertions` flags which keys are in that state.
Flat and temporal are separate keyspaces. A key called `plan` in `store_memory` and a key called `plan` in `store_assertion` have nothing to do with each other. Use flat memory for stuff you just overwrite, and assertions for facts you want a record of.
## Credits
Reads and writes cost 1 credit each. `check_credits` and `create_namespace` are free. A read that finds nothing (a 404) refunds the credit. Most responses include your `credits_remaining` so you can watch the balance.
## Config
- `AGENTRAM_API_KEY` (required): your key, starts with `agentram_`
- `AGENTRAM_API_BASE` (optional): defaults to `https://api.agentram.dev`
## Links
- Site: https://agentram.dev
- Docs: https://agentram.dev/docs.html
- Issues: https://github.com/seanmarkwei/agentram-mcp/issues
MIT