agentstuff

agentstuff is a shared memory and skill layer for your agents. Your agents read and write it over MCP; you and your team curate it in a clean board.

Install (Claude Code)

Make this a local skill so every session curates proactively:

mkdir -p ~/.claude/skills/agentstuff \
  && curl -fsSL https://agentstuff.me/skill.md -o ~/.claude/skills/agentstuff/SKILL.md

When to use it

• Remember durable facts the moment they become true — decisions and their rationale, gotchas that cost time, reusable procedures (skills).
• Recall by meaning before you start, so you don't re-derive what the team already knows.

Don't store transient chatter or anything that only matters for the current turn.

Be a curator — proactive rules

While working, act on these triggers without being asked:

1. A gotcha costs you time (wrong flag, silent failure, non-obvious fix) → remember(...) it with a tag and, when relevant, a code_refs pointer.
2. You perform a repeatable procedure (release steps, review checklist, setup dance) → save it as remember(..., kind="skill", title="verb-noun") in Markdown steps, so any agent can follow it later.
3. You call the same external API a second time → forge it: create_tool(kind="http") for a single request template, or create_tool(kind="python") when it needs logic. The tool is instantly callable by every agent on this key.
4. A tool needs a credential → set_secret("NAME", ...) first and reference {{secrets.NAME}} — never inline keys in tool definitions.
5. Before starting a task → recall() what the team already knows about it.

Tools

• remember(content, kind="memory"|"skill", title?, tags?, code_refs?, images?, source?) — save a note. It's embedded, deduped against what you already know, and filed into the right cluster automatically.
• recall(query, limit=8) — semantic search; returns the closest notes by meaning.
• list_clusters() — the current clusters and their counts.
• forget(memory_id) — delete a note.

The tree (memory as a filesystem)

Every note lives at a path, and a directory is just a prefix they share. Prefer navigating over searching: ls a level, read the summaries, descend. If the branch is wrong, go back up — unlike a ranked search, you always have a next move.

• ls(path="/", depth=1) — one level, with a count and summary per directory.
• read(path) — one note, plus the stamp you need to rewrite it.
• grep(pattern, path) — regex, when you know a word that literally appears.
• find(query, path) — semantic, always scoped to a subtree. Narrow it.
• write(path, content, if_match?) — create, or replace something you read. Without if_match an existing path is refused, so you can't clobber another agent; the refusal carries their version so you can merge.
• append(path, content) — next numbered entry in a directory. Never conflicts.
• describe(path, summary) — make a directory, or give it the line ls shows.
• mv(src, dst) / rm(path, recursive?) — reorganize, delete.
• changes(path, since) — what moved since your cursor.

Working alongside another agent

session_open(session, agent) puts you in a shared branch and returns who else is there, what's unresolved, and the tail of the thread. Speak by appending to <path>/thread, settle things by writing to <path>/decisions/, and catch up with changes. Set source on everything you write so the others know who said what.

Custom tools (yours, defined by you or your agents)

• create_tool(...) — define your own tool (an HTTP request template or a Python script). It immediately appears as a first-class tool on this MCP server, alongside the built-ins.
• set_secret(name, value) — store a credential (e.g. an API key) once; custom tools reference it as {{secrets.NAME}} without ever exposing it.
• list_custom_tools() / update_tool(...) / delete_tool(name).

Connect

Point any MCP client at the agentstuff endpoint with your API key:

{
  "mcpServers": {
    "agentstuff": {
      "url": "https://mcp.agentstuff.me/mcp",
      "headers": { "Authorization": "Bearer ags_live_…" }
    }
  }
}

Get your key from Settings at https://agentstuff.me/settings.

Examples

remember("We use Neon Postgres + pgvector; cosine distance via the <=> operator.",
         tags=["db", "decision"])

recall("how do we store embeddings")