Local API

A small JSON HTTP API your machine serves on the loopback interface - health, the six memory verbs, git-sync control, and a local MCP endpoint. For scripts and tools on this machine; anything remote uses the cloud MCP server instead.

The base URL

text

http://127.0.0.1:4243

The CLI's background daemon serves this API. It autostarts on the first memory verb, or start it explicitly with agentage daemon start. Every route below is plain JSON over HTTP.

Loopback only, no auth

The daemon binds to 127.0.0.1 and there is no authentication on the socket - it trusts every process on your machine and is never exposed to the network. Use it for local scripts and tools. For anything remote, use the cloud MCP server and REST API, which are OAuth-protected. Change the port with AGENTAGE_DAEMON_PORT.

Endpoints

Every route, grouped by resource. Click a row to expand its contract - parameters, a curl example, the JSON response, response fields, and errors. The memory routes mirror the MCP tools one-to-one; the request body carries the same parameters.

Health

Cheap liveness probe. Returns the running CLI version, the daemon pid, its uptime and how many memory requests it has served. Use it to check whether the daemon is up before scripting against it.

Example

bash

curl -s http://127.0.0.1:4243/api/health

Response 200

json

{
  "ok": true,
  "version": "0.1.0",
  "pid": 51234,
  "uptime": 42,
  "served": 7
}

Fields

ok	boolean	Always true when the daemon answers.
version	string	Running CLI version.
pid	integer	Daemon process id.
uptime	integer	Seconds since the daemon started.
served	integer	Memory requests served so far.

Errors

ECONNREFUSED the daemon is not running - start it with `agentage daemon start`

Memory

Literal substring search over a vault, ranked by match count. Returns paths and snippets, never full bodies. Mirrors the memory__search tool.

Parameters

query	string, body	Search text. Required.
opts.vault	string, body	Target vault. Optional.
opts.folder	string, body	Scope to a folder. Optional.
opts.limit	integer, body	Max hits, default 20.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{"query":"postgres","opts":{"vault":"notes","limit":5}}'

Response 200

json

{
  "results": [
    {
      "path": "@notes/welcome.md",
      "title": "welcome",
      "snippet": "# Welcome We use Postgres for full-text search.",
      "score": 1,
      "updated": "2026-07-06T14:11:31+00:00"
    }
  ]
}

Fields

results	array	Ranked matches.
results[].path	string	Document path; @<vault>/ prefixed when scoped to a vault.
results[].snippet	string	Match context.
results[].score	integer	Match count - how many times the query hits the note.
nextCursor	string, optional	Present only when more pages exist; pass back as opts.cursor for the next page.

Errors

400 invalid JSON body · 404 unknown verb

Full document by path: frontmatter, markdown body and metadata. Bodies over 64 KB are clamped. Mirrors memory__read.

Parameters

ref	string, body	@<vault>/<path>, or <path> with opts.vault. Required.
opts.vault	string, body	Target vault. Optional.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/read \
  -H "Content-Type: application/json" \
  -d '{"ref":"@notes/welcome.md"}'

Response 200

json

{
  "path": "welcome.md",
  "title": "welcome",
  "frontmatter": {},
  "body": "# Welcome\nWe use Postgres for full-text search.\n",
  "tags": [],
  "updated": "2026-07-06T14:11:31+00:00",
  "deleted": false
}

Fields

path	string	Resolved document path, vault-relative (no @ prefix).
title	string	Filename stem.
frontmatter	object	Parsed YAML frontmatter.
body	string	Markdown body.
tags	string[]	Frontmatter tags.
updated	string	ISO 8601 last write.
deleted	boolean	True for a tombstoned document.

Errors

400 not found, or invalid body

Idempotent full write - creates or replaces the document and commits. The engine refuses to store obvious secrets. Mirrors memory__write.

Parameters

ref	string, body	Target document. Required.
body	string, body	Markdown body. Required.
opts.vault	string, body	Target vault. Optional.
opts.frontmatter	object, body	YAML frontmatter to set. Optional.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/write \
  -H "Content-Type: application/json" \
  -d '{"ref":"work/plan.md","body":"Q3 focus is search.","opts":{"vault":"notes","frontmatter":{"tags":["work"]}}}'

Response 200

json

{
  "path": "@notes/work/plan.md",
  "rev": "8e0670daa3bef7cdd58152b70092e3da553445b4",
  "updated": "2026-07-06T14:37:07.262Z"
}

Fields

path	string	The document path that was written, echoed with its @<vault>/ prefix when the request was vault-scoped.
rev	string	Git commit hash of this write.
updated	string	ISO 8601 commit time.

Errors

400 invalid body, or a refused secret

Targeted edit: str_replace (op.old_str / op.new_str), or replace/append the body (op.mode + op.body). Mirrors memory__edit.

Parameters

ref	string, body	Target document. Required.
op.mode	string, body	replace \| append \| str_replace.
op.body	string, body	New or appended content.
op.old_str / op.new_str	string, body	Exact, unique substring to replace, and its replacement.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/edit \
  -H "Content-Type: application/json" \
  -d '{"ref":"@notes/welcome.md","op":{"mode":"str_replace","old_str":"Postgres","new_str":"SQLite"}}'

Response 200

json

{
  "path": "@notes/welcome.md",
  "rev": "2abbd3203f725b8373e56194df938fdc6b887bab",
  "updated": "2026-07-06T14:12:22.931Z"
}

Fields

path	string	The document path that was written, echoed with its @<vault>/ prefix when the request was vault-scoped.
rev	string	Git commit hash of this write.
updated	string	ISO 8601 commit time.

Errors

400 no match for old_str, or not found

Browse a vault as a folder tree (two levels deep). Paths are @<vault>/ prefixed when scoped to a vault. Mirrors memory__list.

Parameters

folder	string, body	Folder prefix. Optional.
opts.vault	string, body	Target vault. Optional.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/list \
  -H "Content-Type: application/json" \
  -d '{"opts":{"vault":"notes"}}'

Response 200

json

{
  "folder": "@notes",
  "entries": [
    {
      "type": "folder",
      "path": "@notes/work",
      "files": 2,
      "entries": [
        {
          "type": "folder",
          "path": "@notes/work/tasks",
          "files": 1
        },
        {
          "type": "file",
          "path": "@notes/work/plan.md",
          "title": "plan",
          "updated": "2026-07-06T14:37:07+00:00"
        }
      ]
    },
    {
      "type": "file",
      "path": "@notes/welcome.md",
      "title": "welcome",
      "updated": "2026-07-06T14:37:07+00:00"
    }
  ],
  "truncated": false,
  "files": 3
}

Fields

folder	string	The listed folder.
entries	array	File and folder nodes, tree order.
entries[].type	string	"file" or "folder".
entries[].path	string	Node path.
entries[].files	integer	Folder nodes: file count under the folder.
entries[].entries	array, optional	Folder nodes: nested children, down to two levels deep in total.
entries[].truncated	boolean, optional	Folder nodes: true when its children were cut at the per-folder cap.
files	integer	Total files under the folder.

Errors

400 invalid body

Removes the document and commits the deletion, so it stays recoverable from git history. Mirrors memory__delete.

Parameters

ref	string, body	Target document. Required.
opts.vault	string, body	Target vault. Optional.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/memory/delete \
  -H "Content-Type: application/json" \
  -d '{"ref":"@notes/old.md"}'

Response 200

json

{
  "path": "@notes/old.md",
  "deleted": true
}

Fields

path	string	The deleted document path.
deleted	boolean	Always true on success (recoverable from git history).

Errors

400 not found

Sync

The current state of every git-backed vault: its remote, interval, whether a cycle is running, and the last run and result. Empty when no vault has a git remote.

Example

bash

curl -s http://127.0.0.1:4243/api/sync/status

Response 200

json

{
  "vaults": [
    {
      "vault": "work",
      "remote": "git@github.com:you/memory.git",
      "intervalSeconds": 300,
      "running": false
    }
  ]
}

Fields

vaults	array	One entry per git-backed vault.
vaults[].vault	string	Vault name.
vaults[].remote	string	Git remote URL.
vaults[].intervalSeconds	integer	Auto-sync interval; 0 = manual only.
vaults[].running	boolean	True while a cycle is in flight.
vaults[].lastRun	string	ISO 8601 of the last cycle. Optional.
vaults[].lastResult	object	Summary of the last cycle (ok, pushed, committed, conflicts). Optional.

Errors

Forces a commit + push + pull-rebase for a single vault, regardless of its interval. Conflicts keep both sides: the remote copy is written as <file>.conflict.md.

Parameters

vault

string, body

Vault to sync. Required.

Example

bash

curl -s -X POST http://127.0.0.1:4243/api/sync/run \
  -H "Content-Type: application/json" \
  -d '{"vault":"work"}'

Response 200

json

{
  "vault": "work",
  "remote": "git@github.com:you/memory.git",
  "ok": true,
  "committed": true,
  "pushed": true,
  "conflicts": []
}

Fields

ok	boolean	False when the cycle failed.
committed	boolean	A sync commit was made.
pushed	boolean	Local commits were pushed.
conflicts	string[]	Paths written as <file>.conflict.md.
reason / error	string	Failure kind and message when ok is false (e.g. "unreachable").

Errors

400 vault is required, or no sync origin configured

MCP

The same frozen six memory__* tools as the cloud endpoint, served locally as stateless Streamable HTTP JSON-RPC. GET and DELETE return 405 (stateless: POST only). See the MCP tools reference for the tool contracts.

Parameters

(body)

JSON-RPC 2.0

A JSON-RPC request, e.g. tools/list or tools/call.

Example

bash

curl -s -X POST http://127.0.0.1:4243/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Response 200

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "memory__search"
      },
      {
        "name": "memory__read"
      },
      {
        "name": "memory__write"
      },
      {
        "name": "memory__edit"
      },
      {
        "name": "memory__list"
      },
      {
        "name": "memory__delete"
      }
    ]
  }
}

Fields

result.tools

array

The six memory__* tool contracts (names, schemas, annotations).

Errors

405 GET or DELETE - the endpoint is stateless (POST only) · 500 internal error

What this API is not

Not remote - it lives on 127.0.0.1 only; never port-forward or proxy it to the internet.
Not authenticated - there are no tokens or keys; access is machine-local trust.
Not the way to connect an AI - point MCP clients at the stdio command or the local endpoint http://127.0.0.1:4243/mcp (see the CLI guide). AI outside this machine uses the cloud MCP server.