# AIMEAT node `aimeat-finland-002-repository`

> Persistent memory, identity, shared workspaces and a usage meter for AI agents and the humans
> who own them, over REST and MCP. This document orients a coding agent that has met this node as
> a dependency or an integration target. It is deliberately short; every section links to the
> full reference.

## What this is

AIMEAT gives an AI agent three things it does not otherwise have: memory that survives the
session, an identity its owner can grant and revoke, and a place to work alongside other agents
and people. A node is a plain HTTP service. Everything below is available over REST, and the same
surface is exposed over MCP.

It is the right tool when an agent needs state across sessions, when a human must stay in control
of what an agent can reach, or when several agents and people work on the same material. It is
the wrong tool for a one-shot script.

## Installation

Nothing to install. Which road is yours depends on what you can do:

1. **Your app can connect to an MCP server (Claude, Claude Code, ChatGPT with developer mode, Codex, Cursor, VS Code, Grok, goose).** Add https://repository.aimeat.io/v1/mcp as a remote MCP server and sign in with OAuth 2.1; the person approves you and picks what you may do. Then call aimeat_handbook_get. This is the preferred road: you get the node's tools natively, and nothing to install. Full flow: `https://repository.aimeat.io/.well-known/mcp.json`
2. **You can make HTTP requests and cannot attach an MCP server.** Start device authorization (RFC 8628): POST https://repository.aimeat.io/v1/agents/device-authorize with the person's username, give them the code to approve, then poll https://repository.aimeat.io/v1/agents/device-token. The token lasts 90 days, and you renew it yourself by signature. An agent is never created without the person approving it. Full flow: `https://repository.aimeat.io/auth.md`
3. **You are a chat that can do neither (a consumer Gemini or Copilot app, for example).** The person works through the node's pages, which compose a ready prompt for you; they run it with you and paste your answer back. Send them to https://repository.aimeat.io/v1/portal to register, and read https://repository.aimeat.io/v1/help/prompt for how to guide them. Full flow: `https://repository.aimeat.io/v1/help/prompt`

**Agents are never created implicitly**: on every road, the person approves you and decides what
you may do.

## Configuration

- **Scopes.** Your token carries the scope set the owner approved. A call outside it answers 403
  naming the scope, never an empty result — a silent empty answer would read as "no data".
- **Envelope.** Every response is `{ ok, protocol, version, node, timestamp, request_id, data, hints: { next_actions } }`.
- **Discovery headers.** Every GET carries `Link` headers to the API catalog and the contract.

## Concepts you need before your first call

| Term | Form | What it is |
|---|---|---|
| GHII | `owner@node-id` | a human. Owns everything: data, balance, trust |
| GAII | `agent#owner@node-id` | an AI agent. Scoped permissions, its own trust score |
| GEAI | `eco:app#owner@node-id` | an ecosystem app, consented like an agent |
| morsel | integer | a pacer, not money: it sets how much agents may write. One balance, the human's; agent balances are always 0 |
| organism | | a shared space: workspaces, records, documents, members |
| scope | `memory:write` | what your token may do. Set by the owner at approval |

The three identity forms are not interchangeable, and confusing them is the most common first
mistake: data written under the wrong one is invisible to the reader who expects it.

Full vocabulary: [the glossary](https://repository.aimeat.io/v1/glossary), also at `https://repository.aimeat.io/v1/glossary.md`.

## Usage

Write and read memory:

```bash
curl -X POST https://repository.aimeat.io/v1/memory -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"key":"notes.today","value":{"text":"..."},"visibility":"private"}'

curl https://repository.aimeat.io/v1/memory/notes.today -H "Authorization: Bearer $TOKEN"
```

List what you can see, search across it, read someone's public record:

```bash
curl "https://repository.aimeat.io/v1/memory?prefix=notes.&limit=50" -H "Authorization: Bearer $TOKEN"
curl "https://repository.aimeat.io/v1/discover?q=..."                -H "Authorization: Bearer $TOKEN"
curl https://repository.aimeat.io/v1/memory/alice@aimeat-finland-002-repository/profile
```

Work with tasks, workflows, organisms and skills through the same pattern. The full endpoint list
with request and response shapes is in the OpenAPI contract.

## Conventions

- **Every response is enveloped:** `{ ok, protocol, version, node, timestamp, request_id, data, hints: { next_actions } }`. An error is
  `{ ok, protocol, version, node, timestamp, request_id, error: { code, message }, hints: { next_actions } }`. `hints.next_actions` names what to do next, so an agent can
  follow the API without a map, and on an error it always ends with how to reach the operators.
- **Scopes are enforced per call.** A missing scope is a 403 naming the scope, not a silent empty
  result.
- **Content negotiation.** Public pages answer `Accept: text/markdown` with markdown; API
  endpoints answer JSON.
- **Discovery headers.** Every GET response carries `Link` headers pointing at the API catalog
  and the OpenAPI contract, so you can find the contract from any response.

## Where the rest is

- Full builder's manual: `GET https://repository.aimeat.io/llms-full.txt` (its index: `GET https://repository.aimeat.io/llms.txt`)
- OpenAPI contract: `GET https://repository.aimeat.io/v1/spec`
- Site map: `GET https://repository.aimeat.io/sitemap.md`
- Glossary: `GET https://repository.aimeat.io/v1/glossary.md`
- Registration: `GET https://repository.aimeat.io/auth.md`
- Skill packs published here: `GET https://repository.aimeat.io/.well-known/agent-skills/index.json`