akh-medu Server

Multi-workspace server hosting N engine instances with REST and WebSocket APIs.

Building

cargo build --release --features server --bin akh-medu-server

Running

# Default: 0.0.0.0:8200
akh-medu-server

# Custom bind/port via env vars
AKH_SERVER_BIND=127.0.0.1 AKH_SERVER_PORT=9000 akh-medu-server

Environment Variables

Directory Layout

~/.config/akh-medu/
    config.toml                 # global config
    workspaces/
        default.toml            # per-workspace config

~/.local/share/akh-medu/
    workspaces/
        default/
            kg/                 # oxigraph, redb, hnsw
            skills/             # activated skill data
            compartments/       # compartment data
            scratch/            # agent scratch space
        project-alpha/
            kg/
            ...
    seeds/                      # installed seed packs

~/.local/state/akh-medu/
    sessions/
        default.bin             # agent session state

REST API

Health

curl http://localhost:8200/health

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "workspaces_loaded": 2
}

List Workspaces

curl http://localhost:8200/workspaces

Response:

{
  "workspaces": ["default", "project-alpha"]
}

Create Workspace

curl -X POST http://localhost:8200/workspaces/my-project

Response:

{
  "name": "my-project",
  "created": true
}

Delete Workspace

curl -X DELETE http://localhost:8200/workspaces/my-project

Response:

{
  "deleted": "my-project"
}

Workspace Status

curl http://localhost:8200/workspaces/default/status

Response:

{
  "name": "default",
  "symbols": 142,
  "triples": 89
}

Apply Seed Pack

curl -X POST http://localhost:8200/workspaces/default/seed/identity

Response:

{
  "pack": "identity",
  "triples_applied": 18,
  "already_applied": false
}

Preprocess Text

curl -X POST http://localhost:8200/workspaces/default/preprocess \
  -H 'Content-Type: application/json' \
  -d '{"chunks": [{"id": "1", "text": "The Sun is a star."}]}'

List Equivalences

curl http://localhost:8200/workspaces/default/equivalences

Equivalence Stats

curl http://localhost:8200/workspaces/default/equivalences/stats

WebSocket Protocol

Connect to ws://localhost:8200/ws/{workspace} for a streaming TUI session.

Client Messages

Input (natural language):

{
  "type": "input",
  "text": "What is the Sun?"
}

Command:

{
  "type": "command",
  "text": "status"
}

Available commands: status, goals.

Server Messages

The server streams AkhMessage JSON objects back. Each message has a type field:

{"type": "fact", "text": "Sun is-a Star", "confidence": 0.95, "provenance": null}
{"type": "system", "text": "Connected to workspace \"default\"."}
{"type": "tool_result", "tool": "kg_query", "success": true, "output": "Found 3 triples."}
{"type": "goal_progress", "goal": "Explore Sun", "status": "Active", "detail": null}
{"type": "error", "code": "ws", "message": "workspace not found", "help": null}

Systemd Example

[Unit]
Description=akh-medu Knowledge Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/akh-medu-server
Environment=AKH_SERVER_BIND=127.0.0.1
Environment=AKH_SERVER_PORT=8200
Environment=RUST_LOG=info,egg=warn
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target