gradatum-server 0.0.1

Stateless HTTP/MCP façade :19090 — handles read/search + enqueues writes
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# gradatum-server

> Stateless HTTP/MCP facade on port 19090. Handles read/search requests and enqueues write operations.

**Status** : Alpha — placeholder `v0.0.1`. Source code private until `v1.0` public release. See [gradatum.org](https://gradatum.org) for project context.

**Part of [`gradatum`](https://crates.io/crates/gradatum)** — Memory backbone for AI agents.

## Usage

```
gradatum-server [--config <path>]
```

## HTTP Endpoints

| Method | Path | Auth | Description |
|---|---|---|---|
| `GET` | `/health` | None | Health check — returns `{"status":"ok","version":"..."}` |
| `GET` | `/metrics` | Loopback only | Prometheus metrics (port :19091) |
| `POST` | `/api/v1/vault_search` | Bearer | Full-text + semantic search |
| `POST` | `/api/v1/vault_read` | Bearer | Read note by path |
| `POST` | `/api/v1/vault_list` | Bearer | List notes with pagination |
| `GET` | `/api/v1/vault_status` | Bearer | Vault status and stats |
| `GET` | `/api/v1/vault_authors` | Bearer | List note authors |
| `GET` | `/api/v1/vault_tags` | Bearer | List tags with frequencies |
| `POST` | `/api/v1/vault_graph` | Bearer | Wikilink graph from a root note |
| `POST` | `/api/v1/vault_links` | Bearer | Wikilinks for a note |
| `POST` | `/api/v1/vault_trace` | Bearer | Trace chain through a note |
| `POST` | `/api/v1/vault_context` | Bearer | Context window for a note |

## MCP Endpoint

| Path | Description |
|---|---|
| `/mcp` | Streamable HTTP (MCP 2025-03-26) |
| `/sse` | SSE legacy transport |

## Configuration (TOML)

```toml
bind = "127.0.0.1:19090"     # C3: TLS required for non-loopback
data_root = "/var/lib/gradatum"
jwt_public_key_path = "/etc/gradatum/jwt_ed25519.pub"
```

## Auth

JWT Ed25519 bearer token. Audience-scoped (`read` / `write` / `admin`).
Generate via: `gradatum-admin init --preset hierarchical --root /var/lib/gradatum`

## Graceful shutdown

SIGTERM → 30-second drain.

## Documentation

- Project : <https://gradatum.org>
- Source : private until v1.0
- Roadmap : Phase 2.0a Foundation + Read API → `v0.1.0` public
- License : Apache-2.0