---
name: hypermemory
version: 0.13.4
description: >-
  Persistent memory graph for AI agents via HyperMemory MCP tools. Recall
  context, store facts and relationships, enforce hyperedge policy, and
  maintain graph hygiene on every message. Use when HyperMemory MCP is
  connected or the user mentions HyperMemory memory tools.
enforcement: mandatory
trigger: every_turn
---

# HyperMemory MCP — Agent Protocol

Connect MCP server URL: `https://api.hypermemory.io/mcp`

Use MCP tools on every message. Do not simulate memory — call the tools.

## Every conversation

**First message (before responding):**

1. `hm_get_overview`
2. `hm_recall` with keywords from the user's message

**Every message (silently, before responding):**

1. `hm_recall` — check if the fact already exists
2. New → `hm_store` with `key`, `description`, `node_type`, `relationships`
3. Exists → `hm_update`
4. Wrong → `hm_forget`
5. Before the final response → call `hm_tokens` exactly once for this turn

Never ask permission to save. Never announce that you saved.

---

## Organization memory

Members of a HyperMemory organization get the organization's memory with their own on every `hm_recall`, searched in parallel, under `organization_memory` (labelled with the organization's `name`). Organization memory is read-only: never try to store, update or forget anything in it. When an organization admin turns on organization write mode in the HyperMemory dashboard, the server sends that admin's writes (`hm_store`, `hm_update`, `hm_forget`, `hm_add_relationships`, `hm_ingest`, `hm_upload_file`) to the organization graph and the result carries `write_target`; never pick the target yourself. To read what was written there, send that organization's `organization_id` to `hm_get_nodes`, `hm_find_related`, `hm_get_overview` or `hm_list_orphans` (the result carries `read_target`); without it they read your own graph. A key or relationship endpoint "not found" during write mode means it is missing from the organization graph: create it there first.

- `hm_get_overview` lists the caller's organizations in `organizations` (absent when the caller belongs to none).
- One organization: nothing to do; it is always searched.
- Several organizations: each project is bound to one of them, or to none, in `~/.config/hypermemory/projects.json` (`{"version": 1, "projects": {"<project root>": {"organization_id": "<id or none>", "name": "<organization name>"}}}`; the project root is the repository's main working tree, shared by all its worktrees: the parent of `git rev-parse --path-format=absolute --git-common-dir` when that ends in `/.git`, else that directory; outside git, the working directory). At session start, read the binding for this project. If there is none, ask the user before other work which organization this project belongs to (list the organizations plus "none, personal memory only"), then write their answer to that file. Send the bound `organization_id` (or `"none"`) on every `hm_recall` for the session.
- `organization_memory.status`: `included` (results attached), `selection_required` (several organizations and no `organization_id` sent: ask and bind as above), `excluded` (`"none"` was sent), `selected_graph` (this credential's graph is the organization graph, so the main results already are its memory), `failed` (tell the user the organization search failed; your own results are still valid).

## Tool reference

| Tool | Use when |
|------|----------|
| `hm_get_overview` | Start of conversation — graph stats |
| `hm_recall` | Search memory; always before store |
| `hm_get_nodes` | Hydrate known exact keys with full node details |
| `hm_store` | New node + optional relationships; an existing key changes only the fields sent (`if_exists`: `update`, `keep`, `error`) |
| `hm_update` | Update a node (`key`) or edge (`edge_id`). Edge endpoints/type are immutable |
| `hm_forget` | Delete a node (`key`) or single edge (`edge_id`). Edge delete preserves nodes |
| `hm_find_related` | Traverse graph from a seed node |
| `hm_add_relationships` | Connect existing nodes; fix orphans (at most 25 per call; retrying is safe) |
| `hm_get_chat_context` | Reload nodes from current chat session |
| `hm_list_orphans` | After every `hm_ingest` |
| `hm_ingest` | Dense multi-entity text (creates orphans) |
| `hm_upload_file` | User explicitly asks to store a file (Pro+) |
| `hm_list_files` | Query uploaded files |
| `hm_timeline_write` | Diary line not captured as a node |
| `hm_tokens` | End-of-turn token/cost report with weighted activity segments |
| `hm_timeline` | Temporal lookup (not auto-loaded) |
| `hm_skill` | Retrieve or update current HyperMemory agent skills |

For `hm_tokens`, report `cost_usd` with a separate `cost_quality`:
`provider_actual`, `price_calculated`, `self_estimated`, or `unavailable`.
Only use `provider_actual` for a provider-billed amount.
For OpenRouter, submit client-visible token fields and weighted segments; they
remain provisional until management analytics reconciliation. Claude Desktop
uses `self_estimated` with uncertainty and no API-equivalent dollar cost.
When multiple AI accounts are configured, include the matching `ai_account_id`
in `hm_tokens`. Without it, HyperMemory auto-assigns only when exactly one
active account matches `ai_tool`; ambiguous reports remain unassigned but still
count in the user's aggregate totals.
Each segment category may appear only once per report. Merge activities that
share a category into one segment and combine their weights before calling
`hm_tokens`; all resulting weights must total exactly 100. Estimate the split
from the work actually performed; exact token counters do not make activity
attribution exact. Weight what the turn did: building or editing a workbook, document or deck is
`doc_processing`, gathering and reading sources is `research`, drafting text is
`writing`, figures are `calculations`, code is `coding`. Reading the
conversation, files and tool results belongs to the work it served: there is
no `context` category and the server refuses it. Use `memory` only for the
HyperMemory calls themselves. Never send a fixed split such as memory 10 /
context 90. Allowed categories are `reasoning`, `memory`,
`doc_processing`, `automation`, `personal`, `chatting`, `research`, `design`,
`calculations`, `coding`, `planning`, `productivity`, `writing`, and
`unmatched`. Use `unmatched: 100` only when classification is genuinely
unavailable. Do not use the removed `mem_ingest` or `mem_retrieve` categories.

**Edge editing:** `hm_update` and `hm_forget` accept an optional `edge_id`
(from read responses) to target a single edge. Pass `edge_version` for
optimistic concurrency. To change edge endpoints or type, delete and recreate.

**Naming traps:** There is no `hm_related` or `hm_relate`. Use `hm_find_related` to traverse, `hm_add_relationships` to create edges.

**Recall vs hydrate:** Use `hm_recall` to search for candidate nodes. Use
`hm_get_nodes(keys=[...])` when you already know exact keys and need full,
untruncated descriptions, data, assets, duplicate records, and relationships.

**Skill updates:** If asked to install or update HyperMemory instructions, call
`hm_skill` with `action="get"` and the best variant for the agent.

---

## Description Quality

A description is the node's primary content. It must be **self-contained and
specific** — a reader with no other context should be able to distinguish this
node from similar concepts and understand what it represents.

**Quality test:** If the description could apply to a different domain without
changing a word, it is too generic. Rewrite it.

Bad — could describe anything:

```
"Agents responsible for managing local estates."
"A type of power that existed during the Sengoku period."
"Organizations that are based in Kyoto."
```

Good — specific enough to be useful:

```
"Shōkan (estate officers) managed day-to-day operations of shoen estates
on behalf of absentee Kyoto proprietors, collecting nengu rice-tax and
settling local disputes under delegated authority."
```

**Rules:**

1. Include the domain-specific term and its meaning, not just a generic gloss.
2. Name concrete relationships, mechanisms, or constraints — not just that
   something "exists."
3. One or two sentences, 80–300 characters, leading with the point in the
   words someone would search with later. Padding is worse than brevity.
4. Do not repeat the key name as the entire description.
5. Keep commit hashes, IDs, file paths, hosts and ports in `data`, never in the
   description.
6. On `hm_update`, rewrite the description to what is true now; never append
   an "UPDATE" paragraph to the old text.
7. A rule the user stated, a choice between alternatives, and a finding or
   open risk each get their own node (`preference`, `decision`, `fact`), linked
   to the event they came from — never only a clause inside that event.

---

## System-Level Nodes

When storing three or more related nodes that belong to a larger system,
process, or structure, also store a node for the system itself. The system
node's description should explain what the system is and how its parts
interact. Its relationships should connect to the constituent nodes.

This prevents the "fragments without a frame" problem where individual nodes
exist but the structure they belong to is absent from the graph.

---

## Node types

```
user person organization component event decision concept artifact
project technology preference fact skill
```

`node_type` is one canonical ontology class, not a free-form label. Do not
invent new types or ontology classes in agent output. If unsure, omit
`node_type` or choose the closest canonical class; the server resolves invalid
or missing input internally before persistence.

Classify based on what the node **represents**, not surface-level word
matching in the key name:

- A class of people (e.g. "warrior-landholder") is `concept`, not `person`.
- A named individual (e.g. "Minamoto Yoritomo") is `person`.
- A running service or deployable unit is `component`.
- A category, pattern, or abstract idea is `concept`.
- A specific choice with alternatives considered is `decision`.

**Key format:** `{type}_{name}` — e.g. `decision_jwt_auth`, `person_alice`, `tech_redis`

**Singleton:** `user_profile` — primary user; keep updated.

---

## Style Contract

Use `node_type="preference"` for prescriptive communication and visual-language
memories that should guide future agent output.

Style nodes are not transcripts. Synthesize user descriptions, feedback, and
source content into prompt-usable instructions for another agent. Keep short
source quotes only when they are valuable as examples.

**Keys:** `style_{scope}_{facet}` or `style_{scope}_{project}_{facet}` when a
scope has multiple project styles.

**Data envelope convention:**

```json
{
  "facet": "voice | tone | lexicon | format | visual | photography | persona",
  "scope": "brand/project/audience this governs",
  "project": "optional project discriminator within the scope",
  "strength": "mandatory | preferred | situational",
  "intent": "one-line purpose",
  "rules": ["operational do-rules"],
  "avoid": ["explicit anti-patterns"],
  "examples": [{"do": "...", "dont": "..."}],
  "tokens": {}
}
```

`facet`, `scope`, and `strength` are required by convention. `project`,
`intent`, `rules`, `avoid`, `examples`, and `tokens` are optional.

Always include an `applies_to` edge to `project_*`, `org_*`, or `user_profile`.
After authoring related facets, create or maintain a joint-necessity hyperedge
such as `{scope}_style_system` or `{scope}_{project}_style_system`.

Written style nodes should turn vague feedback into operational rules,
anti-patterns, lexicon choices, formatting preferences, and high-signal
do/don't examples. Visual, photography, image, and video style nodes should
prefer concrete generation-ready tokens: real font names or font families,
exact hex colors, composition, lighting, camera, texture, motion, aspect ratio,
and rendering vocabulary. Avoid generic adjectives unless paired with observable
implementation details.

After overview/recall, resolve the active style when a project, brand,
organization, user, or artifact context is clear. Treat matching style memories
as binding writing and design instructions for the session. If no active context
is clear, do not pin a style contract.

---

## Relationships

Always include at least one relationship on `hm_store`. Orphan nodes (zero edges) are a hygiene failure.

A relationship should explain **why** two nodes are connected — the
structural, causal, or functional link between them.

**Quality test:** If the relationship could be replaced with "is related to"
without losing meaning, it is too vague. Rewrite it.

Bad — bare verbs or emotional labels:

```json
{"to_key": "concept_defiance", "relationship": "showed"}
{"to_key": "concept_nengu_dues", "relationship": "sought"}
```

Good — explains the structural connection:

```json
{"relationships": [{"to_key": "tech_qdrant", "relationship": "search pipeline depends on Qdrant for hybrid vector retrieval"}]}
```

### Binary edge spec

```json
{"from_key": "person_alice", "to_key": "project_foo", "relationship": "Alice leads the platform migration"}
```

Omit `from_key` on `hm_store` — defaults to the stored node's key.

### Hyperedge spec (3+ participants)

```json
{
  "relationships": [{
    "participant_keys": ["project_hypermemory", "tech_surrealdb", "tech_qdrant", "tech_redis"],
    "relationship": "platform_component_assembly",
    "description": "These four components ship as one deployable platform unit; removing any one breaks the production stack definition"
  }]
}
```

---

## Hyperedge policy (enforced server-side)

Hyperedges mean **joint necessity** — removing any participant changes the meaning.

| Participants | Rule |
|--------------|------|
| **2** | Auto-downgraded to binary edge |
| **3** | Requires **80+ char** `description` explaining joint necessity |
| **4–5** | Specific `relationship` label (≥10 chars, not generic) |
| **10+** | Encouraged for true assembly/cluster facts |
| **Any** | Rejects generic labels: `relates_to`, `connected`, `associated`, `linked`, `related` |
| **`chat_*`** | **Reserved** for system session grouping — never use |

**Removal test:** If the group still makes sense after removing one node, use binary edges.

**5+ nodes in one joint fact:** one hyperedge with all participants — not a mesh of pairs.

---

## Graph hygiene

**After every `hm_ingest`:**

1. `hm_list_orphans` (limit 20)
2. Enriched orphans → `hm_add_relationships`
3. Noise → `hm_forget`
4. Verify orphans trending to zero

Never chain ingests without orphan cleanup between them.

---

## Session hyperedges

Server auto-groups nodes after **5+ tool calls** in a session. Resume with `hm_get_chat_context`. Do not create `chat_*` relationships.

---

## Files (Pro+)

`hm_upload_file` / `hm_list_files` — only when user explicitly asks about file storage.

---

## Timeline (optional)

`hm_timeline_write` for diary entries. `hm_timeline(period="24h")` for temporal lookup. Not auto-loaded.

---

## Hard rules

- Overview + recall before first response
- Recall before every store
- Use a canonical `node_type` when confident; omit rather than invent one
- Always include `relationships` on store
- Never skip memory on any message