Purpose
AgentRAM MCP is a Model Context Protocol server that provides persistent memory for AI agents. Every agent session begins as if it has amnesia—AgentRAM is an ordinary HTTP memory store built specifically for agents: one call saves content, one call reads it back. No infrastructure to set up, no vectors to manage. This package wraps that API as MCP tools that agents can use directly.
Main capabilities
The server provides fifteen tools, divided into two categories: flat memory and temporal memory.
Flat memory (ten tools):
- store_memory: save a value for an agent under a key
- retrieve_memory: read a value by key
- list_memories: list everything stored for an agent
- search_memories: perform text search across keys and values, without embeddings
- delete_memory: delete an entry
- check_credits: view the current balance, free to call
Shared memory (when multiple agents need the same pool):
- create_namespace: create a shared space, free to call
- store_shared_memory: write to it
- retrieve_shared_memory: read from it
- list_shared_memories: list what is in it
Temporal memory (assertions, five tools):
- store_assertion: record a fact that may change, such as a plan, status, or preference
- retire_assertion: mark a fact as no longer true while preserving history
- get_assertion: get the fact currently true for a key
- list_assertions: list all current facts for an agent
- get_assertion_history: get the complete chain of what a key has been historically
About temporal memory
Flat memory overwrites old values. Temporal memory preserves the trail. When a fact changes, you replace the old value with a new value, and the previous value is retained so you can see how the current value evolved.
One point worth knowing in particular: if two different values land on the same key and neither replaced the other, get_assertion will not quietly pick a winner. It will tell you that the key isin dispute and return both values, letting your agent decide for itself rather than operating on a guess. list_assertions will flag keys in this state.
Flat memory and temporal memory are separate key spaces. A key named plan in store_memory has nothing to do with a key named plan in store_assertion. Use flat memory for content that only needs overwriting, and use assertions for facts where you want to keep a record.
How to use
First you need an API key. Register at agentram.dev, and the key will be sent to you by email. New accounts start with 1,000 credits, with no credit card required.
Then add the configuration to your client's MCP config. For Claude Desktop, that file is claude_desktop_config.json (on macOS it is located at ~/Library/Application Support/Claude/claude_desktop_config.json). After restarting the client, the tools will appear. Most clients let you mark them as "always allow" so you do not have to click approve on every call.
One caveat on macOS: Claude Desktop does not include Node, so install Node 18 or newer first, otherwise the server cannot start.
Environment variables:
- AGENTRAM_API_KEY (required): your key, starting with agentram_
- AGENTRAM_API_BASE (optional): defaults to https://api.agentram.dev
Use Cases
Suitable for any client that supports MCP: Claude Desktop, Claude Code, Cline, Cursor, Windsurf, etc. Ideal for scenarios where you need to let AI agents remember information across sessions, share memory, or track facts that change over time (such as status, preferences, plans).
Limitations
Read and write operations each cost 1 credit. check_credits and create_namespace are free. A read that finds no content (404) refunds the credit. Most responses include credits_remaining, making it easy for you to monitor your balance.
More information:
- Website:https://agentram.dev
- Documentation:https://agentram.dev/docs.html
- Issue feedback:https://github.com/seanmarkwei/agentram-mcp/issues
