AGENTS

REST API for coding agents

There is no npm package. Talk to Memuron over HTTPS with a managed API key. Base URL: https://api.memuron.com/memuron.

Connection kit

Create a key at https://console.memuron.com/api-keys. Copy the secret once — it starts with arth_sk_.

What	Value
API base	https://api.memuron.com/memuron
Auth header	Authorization: Bearer arth_sk_…
Alt auth headers	X-Memuron-Api-Key / X-Artha-Api-Key
Tenant	Bound to the managed key. Optional `X-Memuron-Tenant-Id: org_…`
OpenAPI	https://api.memuron.com/docs

env

export MEMURON_API_KEY="arth_sk_…"
export MEMURON_API_BASE="https://api.memuron.com/memuron"

# Optional — managed keys already bind to your org
# export MEMURON_TENANT_ID="org_…"

1. Verify auth

curl -sS "$MEMURON_API_BASE/profile" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json"

curl -sS "$MEMURON_API_BASE/health"

2. List spaces

Always discover spaces before writing. Use the returned space.* token in scope and GraphFS cwd.

curl -sS "$MEMURON_API_BASE/spaces" \
  -H "Authorization: Bearer $MEMURON_API_KEY"

import os, requests

API = os.environ["MEMURON_API_BASE"]
headers = {"Authorization": f"Bearer {os.environ['MEMURON_API_KEY']}"}

spaces = requests.get(f"{API}/spaces", headers=headers).json()
for space in spaces.get("spaces", spaces if isinstance(spaces, list) else []):
    print(space.get("token") or space.get("id"), space.get("name"))

const API = process.env.MEMURON_API_BASE!;
const headers = {
  Authorization: `Bearer ${process.env.MEMURON_API_KEY}`,
  "Content-Type": "application/json",
};

const spacesRes = await fetch(`${API}/spaces`, { headers });
const spaces = await spacesRes.json();
console.log(spaces);

3. Ingest a memory (async)

POST /memories returns 202 with a job_id. Poll until completed — the Guardian may create a new node or update an existing one.

curl -sS -X POST "$MEMURON_API_BASE/memories" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefer dark mode in the editor; avoid emoji in changelogs.",
    "scope": ["space.personal"]
  }'

import os, time, requests

API = os.environ["MEMURON_API_BASE"]
headers = {
    "Authorization": f"Bearer {os.environ['MEMURON_API_KEY']}",
    "Content-Type": "application/json",
}

job = requests.post(
    f"{API}/memories",
    headers=headers,
    json={
        "content": "Prefer dark mode in the editor; avoid emoji in changelogs.",
        "scope": ["space.personal"],
    },
).json()
job_id = job["job_id"]

while True:
    status = requests.get(f"{API}/jobs/{job_id}", headers=headers).json()
    state = status.get("status") or status.get("state")
    print(state, status)
    if state in {"completed", "failed", "succeeded"}:
        break
    time.sleep(0.8)

const API = process.env.MEMURON_API_BASE!;
const headers = {
  Authorization: `Bearer ${process.env.MEMURON_API_KEY}`,
  "Content-Type": "application/json",
};

const ingest = await fetch(`${API}/memories`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    content: "Prefer dark mode in the editor; avoid emoji in changelogs.",
    scope: ["space.personal"],
  }),
});
const { job_id } = await ingest.json();

for (;;) {
  const job = await fetch(`${API}/jobs/${job_id}`, { headers });
  const body = await job.json();
  const state = body.status ?? body.state;
  console.log(state, body);
  if (["completed", "failed", "succeeded"].includes(state)) break;
  await new Promise((r) => setTimeout(r, 800));
}

Poll with GET https://api.memuron.com/memuron/jobs/{job_id}.

4. Hybrid search

Ranked recall with vector + lexical fusion. Good for “what do we know about X?”

curl -sS -X POST "$MEMURON_API_BASE/memories/search" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "editor preferences",
    "k": 5,
    "space": "space.personal"
  }'

import os, requests

API = os.environ["MEMURON_API_BASE"]
headers = {
    "Authorization": f"Bearer {os.environ['MEMURON_API_KEY']}",
    "Content-Type": "application/json",
}

hits = requests.post(
    f"{API}/memories/search",
    headers=headers,
    json={"query": "editor preferences", "k": 5, "space": "space.personal"},
).json()
for hit in hits.get("results", hits.get("memories", [])):
    print(hit.get("id"), hit.get("preview") or hit.get("content", "")[:120])

const API = process.env.MEMURON_API_BASE!;
const headers = {
  Authorization: `Bearer ${process.env.MEMURON_API_KEY}`,
  "Content-Type": "application/json",
};

const res = await fetch(`${API}/memories/search`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    query: "editor preferences",
    k: 5,
    space: "space.personal",
  }),
});
console.log(await res.json());

5. GraphFS query (preferred for agents)

Filesystem-style pipelines over the semantic graph. Start with the manual, keep results small with head / --limit, then select fields.

curl -sS -X POST "$MEMURON_API_BASE/spaces/query" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cwd": "/spaces/space.personal",
    "query": "semantic \"editor preferences\" --limit 5 | select id,type,title,preview"
  }'

import os, requests

API = os.environ["MEMURON_API_BASE"]
headers = {
    "Authorization": f"Bearer {os.environ['MEMURON_API_KEY']}",
    "Content-Type": "application/json",
}

# Read the query manual once when learning the language
manual = requests.get(f"{API}/spaces/query/manual", headers=headers).text
print(manual[:500])

result = requests.post(
    f"{API}/spaces/query",
    headers=headers,
    json={
        "cwd": "/spaces/space.personal",
        "query": 'rg "preferences" | head 10 | select id,type,title,preview',
    },
).json()
print(result)

const API = process.env.MEMURON_API_BASE!;
const headers = {
  Authorization: `Bearer ${process.env.MEMURON_API_KEY}`,
  "Content-Type": "application/json",
};

const result = await fetch(`${API}/spaces/query`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    cwd: "/spaces/space.personal",
    query: 'semantic "editor preferences" --limit 5 | select id,type,title,preview',
  }),
});
console.log(await result.json());

Useful query shapes

queries

ls | head 20
rg "authentication" | head 10 | select id,type,title
semantic "why did the deployment fail" --limit 10
find --id MEMORY_ID | related --limit 10

6. Get, update, delete

Only call these with an exact ID returned from search/query. Deletes are destructive — require explicit user intent in agent workflows.

curl -sS "$MEMURON_API_BASE/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MEMURON_API_KEY"

curl -sS -X PUT "$MEMURON_API_BASE/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefer dark mode; keep changelogs plain text."
  }'

curl -sS -X DELETE "$MEMURON_API_BASE/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MEMURON_API_KEY"

7. Assemble cited context

Build a prompt-ready context block with citations for answering from verified memory.

curl -sS -X POST "$MEMURON_API_BASE/context/assemble" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What editor preferences should I respect?",
    "space": "space.personal",
    "k": 8
  }'

8. Ingest a document

curl -sS -X POST "$MEMURON_API_BASE/documents/ingest" \
  -H "Authorization: Bearer $MEMURON_API_KEY" \
  -F "file=@./spec.pdf" \
  -F "space_ref=space.personal"

Full agent loop (Python)

Drop this into Replit, a worker, or any agent host that can run Python and store secrets.

"""Minimal Memuron agent loop — list spaces → query → ingest → poll."""
from __future__ import annotations

import os
import time
import requests

API = os.environ.get("MEMURON_API_BASE", "https://api.memuron.com/memuron")
KEY = os.environ["MEMURON_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}


def list_spaces():
    return requests.get(f"{API}/spaces", headers=HEADERS).json()


def query(cwd: str, q: str):
    return requests.post(
        f"{API}/spaces/query",
        headers=HEADERS,
        json={"cwd": cwd, "query": q},
    ).json()


def ingest(content: str, scope: list[str]):
    return requests.post(
        f"{API}/memories",
        headers=HEADERS,
        json={"content": content, "scope": scope},
    ).json()["job_id"]


def wait_job(job_id: str, timeout_s: float = 60.0):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        body = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS).json()
        state = body.get("status") or body.get("state")
        if state in {"completed", "failed", "succeeded"}:
            return body
        time.sleep(0.75)
    raise TimeoutError(job_id)


if __name__ == "__main__":
    spaces = list_spaces()
    print("spaces:", spaces)
    cwd = "/spaces/space.personal"
    print(query(cwd, "ls | head 20"))
    job = ingest("User prefers concise PR descriptions.", ["space.personal"])
    print("job:", wait_job(job))
    print(query(cwd, 'semantic "PR descriptions" --limit 5 | select id,preview'))

Errors and agent rules

401 — missing/invalid key. Check arth_sk_ prefix and scopes.
403 — key lacks scope or space ACL blocked the path.
404 — wrong ID or space. Re-list / re-query; never invent IDs.
On query errors, call GET /spaces/query/manual and retry with a smaller pipeline.
Do not call console, billing, webhook, or engine admin routes — they are not part of the public API-user surface.

Endpoint-by-endpoint reference lives under API Reference. Live schema: https://api.memuron.com/docs.