HTTP API Server

Overview
Installation
Quick Start
Endpoints
Authentication
Examples
Environment Variables
Deploying
Next Steps

Overview

The AMFS HTTP server exposes the full AgentMemory API over REST, making it accessible from any language, service, or frontend. It includes:

Full REST endpoints covering all AMFS operations
Server-Sent Events (SSE) for real-time streaming
API key authentication
CORS support for browser-based dashboards
OpenAPI docs at /docs

Installation

pip install amfs-http-server

Or run with Docker:

docker run -p 8080:8080 ghcr.io/raia-live/amfs

Quick Start

# Start with filesystem storage
amfs-http --port 8080

# Start with Postgres
AMFS_POSTGRES_DSN=postgresql://user:pass@localhost:5432/amfs amfs-http --port 8080

# Start with API key auth
AMFS_API_KEYS=key1,key2 amfs-http --port 8080

The server is available at http://localhost:8080 with interactive API docs at http://localhost:8080/docs.

Endpoints

Entries

Method	Path	Description
`GET`	`/api/v1/entries/{entity_path}/{key}?branch=main`	Read the current version of an entry
`POST`	`/api/v1/entries`	Write a new entry (CoW, supports `branch` in body)
`GET`	`/api/v1/entries?branch=main`	List entries, optionally filtered by entity and branch
`GET`	`/api/v1/entries/{entity_path}/{key}/history`	Get version history
`POST`	`/api/v1/search`	Search entries with filters (supports `branch` in body)

All entry endpoints accept a branch parameter (defaults to main). See Git-like Timeline.

Outcomes

Method	Path	Description
`POST`	`/api/v1/outcomes`	Commit an outcome and back-propagate confidence
`GET`	`/api/v1/outcomes`	List all outcomes

Patterns

Method	Path	Description
`GET`	`/api/v1/patterns`	List unique pattern_refs with usage counts

Decision Traces

Method	Path	Description
`GET`	`/api/v1/traces`	List decision traces with enriched data (query events, error events, state diff, session timing)
`GET`	`/api/v1/traces/{trace_id}`	Get full trace detail

Agents & Timeline

Method	Path	Description
`GET`	`/api/v1/agents`	List agents with entry counts and last activity
`GET`	`/api/v1/agents/{agent_id}/memory-graph`	Get agent’s entity relationship graph
`GET`	`/api/v1/agents/{agent_id}/activity`	Get agent’s activity timeline
`GET`	`/api/v1/agents/{agent_id}/timeline`	Git-like event log (writes, outcomes, reads, briefs)

Memory Cortex

Method	Path	Description
`GET`	`/api/v1/briefing`	Get ranked knowledge digests for an entity or agent
`GET`	`/api/v1/cortex/status`	Cortex worker status and digest counts
`GET`	`/api/v1/cortex/digests`	List all compiled digests (filterable by `digest_type`)
`POST`	`/api/v1/events`	Ingest an event into the shared memory pool

Observability

Method	Path	Description
`GET`	`/api/v1/stats`	Memory statistics
`POST`	`/api/v1/context`	Record external context in the causal chain
`GET`	`/api/v1/explain`	Get the causal trace for the current session
`GET`	`/api/v1/stream`	SSE stream of real-time memory events
`GET`	`/api/v1/admin/usage`	Usage statistics and metrics
`GET`	`/health`	Health check

Admin — API Keys

Method	Path	Description
`GET`	`/api/v1/admin/api-keys`	List API keys
`POST`	`/api/v1/admin/api-keys`	Create a new API key
`DELETE`	`/api/v1/admin/api-keys/{key_id}`	Revoke an API key

Admin — Audit Log

Method	Path	Description
`GET`	`/api/v1/admin/audit`	List audit log entries

Admin — Teams (Pro)

Method	Path	Description
`GET`	`/api/v1/admin/teams`	List all teams
`POST`	`/api/v1/admin/teams`	Create a team
`PATCH`	`/api/v1/admin/teams/{id}`	Update a team
`DELETE`	`/api/v1/admin/teams/{id}`	Delete a team
`GET`	`/api/v1/admin/teams/{id}/members`	List team members
`POST`	`/api/v1/admin/teams/{id}/members`	Add a team member
`PATCH`	`/api/v1/admin/teams/{id}/members/{mid}`	Update member role
`DELETE`	`/api/v1/admin/teams/{id}/members/{mid}`	Remove a team member

Admin — Pattern Detection (Pro)

Method	Path	Description
`GET`	`/api/v1/admin/patterns`	List detected patterns
`POST`	`/api/v1/admin/patterns/scan`	Run pattern detection scan
`PATCH`	`/api/v1/admin/patterns/{id}/resolve`	Mark a pattern as resolved

Branching (Pro)

Available when the amfs-branching module is installed (pip install amfs-branching):

Method	Path	Description
`POST`	`/api/v1/branches`	Create a branch
`GET`	`/api/v1/branches`	List branches
`GET`	`/api/v1/branches/{name}`	Get branch details
`DELETE`	`/api/v1/branches/{name}`	Close a branch
`GET`	`/api/v1/branches/{name}/diff`	Diff branch vs. main
`POST`	`/api/v1/branches/{name}/merge`	Merge branch into main
`POST`	`/api/v1/branches/{name}/access`	Grant branch access
`GET`	`/api/v1/branches/{name}/access`	List access grants
`DELETE`	`/api/v1/branches/{name}/access/{type}/{id}`	Revoke access
`POST`	`/api/v1/pull-requests`	Create a pull request
`GET`	`/api/v1/pull-requests`	List pull requests
`POST`	`/api/v1/tags`	Create a snapshot tag
`GET`	`/api/v1/tags`	List tags
`POST`	`/api/v1/rollback`	Rollback memory to a point in time
`POST`	`/api/v1/fork`	Fork agent memory to a new agent

Branch access is enforced automatically — requests targeting a non-main branch are checked against the branch’s access grants. See Git-like Timeline for details.

Authentication

Set the AMFS_API_KEYS environment variable with a comma-separated list of valid API keys:

export AMFS_API_KEYS=amfs_prod_abc123,amfs_dev_xyz456

Clients must include the key in the X-AMFS-API-Key header:

curl -H "X-AMFS-API-Key: amfs_prod_abc123" http://localhost:8080/api/v1/stats

If AMFS_API_KEYS is not set, authentication is disabled (suitable for local development).

Examples

Write an entry

curl -X POST http://localhost:8080/api/v1/entries \
  -H "Content-Type: application/json" \
  -d '{
    "entity_path": "checkout-service",
    "key": "retry-pattern",
    "value": {"max_retries": 3, "backoff": "exponential"},
    "confidence": 0.85,
    "memory_type": "fact"
  }'

Write to a branch

curl -X POST http://localhost:8080/api/v1/entries \
  -H "Content-Type: application/json" \
  -d '{
    "entity_path": "checkout-service",
    "key": "retry-pattern",
    "value": {"max_retries": 5, "backoff": "linear"},
    "confidence": 0.7,
    "branch": "experiment/retry-v3"
  }'

Read an entry

curl http://localhost:8080/api/v1/entries/checkout-service/retry-pattern

Read from a branch

curl "http://localhost:8080/api/v1/entries/checkout-service/retry-pattern?branch=experiment/retry-v3"

List entries

curl http://localhost:8080/api/v1/entries

List entries on a branch

curl "http://localhost:8080/api/v1/entries?branch=experiment/retry-v3"

Response:

{
  "entries": [
    {"entity_path": "checkout-service", "key": "retry-pattern", "version": 1, "branch": "main", ...},
    ...
  ]
}

View agent timeline

curl "http://localhost:8080/api/v1/agents/deploy-agent/timeline?limit=20"

List outcomes

curl http://localhost:8080/api/v1/outcomes

Response:

{
  "outcomes": [
    {"outcome_ref": "DEP-287", "outcome_type": "success", ...},
    ...
  ]
}

Search

curl "http://localhost:8080/api/v1/search?entity_path=checkout-service&min_confidence=0.5&limit=10"

Commit an outcome

curl -X POST http://localhost:8080/api/v1/outcomes \
  -H "Content-Type: application/json" \
  -d '{
    "outcome_ref": "DEP-287",
    "outcome_type": "success"
  }'

Stream real-time events

curl -N http://localhost:8080/api/v1/stream

Events arrive as SSE:

event: memory_write
data: {"entity_path": "checkout-service", "key": "retry-pattern", "version": 2, ...}

event: outcome
data: {"outcome_ref": "DEP-287", "outcome_type": "success", ...}

Get a briefing

curl "http://localhost:8080/api/v1/briefing?entity_path=checkout-service"

Response:

{
  "digests": [
    {
      "digest_type": "entity",
      "scope": "checkout-service",
      "summary": {"total_keys": 5, "agents": ["deploy-bot"], "avg_confidence": 0.85},
      "entry_count": 5,
      "anticipation_score": 0.15,
      "compiled_at": "2026-04-04T12:00:00Z"
    }
  ],
  "total": 1
}

Ingest an external event

curl -X POST http://localhost:8080/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "source": "monitoring",
    "entity_path": "checkout-service",
    "key": "high-cpu-alert",
    "value": {"host": "prod-3", "cpu": 95},
    "event_type": "alert.triggered"
  }'

Check Cortex status

curl http://localhost:8080/api/v1/cortex/status

Python client

import httpx

client = httpx.Client(
    base_url="http://localhost:8080",
    headers={"X-AMFS-API-Key": "your-key"},
)

# Write
client.post("/api/v1/entries", json={
    "entity_path": "myapp/auth",
    "key": "session-timeout",
    "value": "30m",
    "confidence": 0.9,
})

# Read
entry = client.get("/api/v1/entries/myapp/auth/session-timeout").json()

Environment Variables

Variable	Description	Default
`AMFS_HTTP_HOST`	Bind host	`0.0.0.0`
`AMFS_HTTP_PORT`	Bind port	`8080`
`AMFS_API_KEYS`	Comma-separated API keys (empty = no auth)	—
`AMFS_CORS_ORIGINS`	Comma-separated allowed CORS origins	`*`
`AMFS_POSTGRES_DSN`	Postgres connection string (switches backend to Postgres)	—
`AMFS_S3_BUCKET`	S3 bucket (switches backend to S3)	—
`AMFS_DATA_DIR`	Filesystem data directory	`.amfs`
`AMFS_AGENT_ID`	Server agent identity	`amfs-http-server`

Deploying

Docker

docker run -p 8080:8080 \
  -e AMFS_POSTGRES_DSN=postgresql://user:pass@host:5432/amfs \
  -e AMFS_API_KEYS=your_key_here \
  ghcr.io/raia-live/amfs

Docker Compose

See Docker & Kubernetes guide for the full docker-compose.yml.

Kubernetes

helm install amfs ./helm/amfs \
  --set storage.backend=postgres \
  --set amfs.apiKeys=your_key_here

Next Steps

Docker & Kubernetes — deploy AMFS in containers
S3 Adapter — use S3-compatible storage as the backend
MCP Setup — give coding agents direct memory access

HTTP API Server

Table of Contents

Overview

Installation

Quick Start

Endpoints

Entries

Outcomes

Patterns

Decision Traces

Agents & Timeline

Memory Cortex

Observability

Admin — API Keys

Admin — Audit Log

Admin — Teams (Pro)

Admin — Pattern Detection (Pro)

Branching (Pro)

Authentication

Examples

Write an entry

Write to a branch

Read an entry

Read from a branch

List entries

List entries on a branch

View agent timeline

List outcomes

Search

Commit an outcome

Stream real-time events

Get a briefing

Ingest an external event

Check Cortex status

Python client

Environment Variables

Deploying

Docker

Docker Compose

Kubernetes

Next Steps