# 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