Palace Getting Started And API Guide

Source basis: Palace of Truth public repository README.md, docs/mcp-server.md, docs/palace-oauth-scope-catalog.md, docs/source-backed-wakeup-demo.md, third_party_plugins/agent_clients/palaceoftruth-memory/README.md, third_party_plugins/hermes/memory/palaceoftruth/plugin.yaml, and current backend route registration in backend/app/main.py, reviewed through commit 62b4328 on July 9, 2026.

Palace of Truth is a tenant-scoped truth and memory control plane for agents. It gives humans and agents one durable corpus for source-backed wakeup, semantic and temporal memory, notes, webpages, documents, media, retrieval traces, claims, graph relationships, rooms, and recovery workflows.

Use this page as the public entrypoint. Treat github.com/palaceoftruth/palaceoftruth as the implementation source of truth when a command, route, or deployment value changes.

Local Development

Standard product development runs from the main Palace repository with Docker Compose plus devinfra:

cp .env.example .env
docker compose up --build -d
di up palaceoftruth
open https://palaceoftruth.test

Frontend-only and backend-only loops are also available in that repo:

cd frontend
npm install
npm run dev

cd backend
pip install -e .
uvicorn app.main:app --reload
pytest

This landing repo is only the public static site. It does not own the Palace backend, database, worker, MCP service, tenant keys, or product API implementation.

The open-source app repository is AGPL-3.0-only. Review LICENSE, TRADEMARKS.md, NOTICE, CONTRIBUTING.md, and SECURITY.md in the public repo before redistributing, modifying, deploying, or reporting issues.

Hosted Endpoint Assumptions

Use Palace-branded URLs and environment variables by default:

export PALACEOFTRUTH_API_BASE_URL=https://api.palaceoftruth.test
export PALACEOFTRUTH_API_KEY=<tenant-api-key>

Local development commonly uses https://palaceoftruth.test. Deployed or shared MCP runtimes can use a streamable HTTP MCP endpoint when that workload and auth path are intentionally selected:

https://mcp.palaceoftruth.example/mcp

For local Codex and similar desktop agents, prefer the repo-owned stdio MCP adapter over remote HTTP. Remote MCP is a temporary fallback or deployed/shared-runtime profile, not the default local profile.

Auth And Scope Model

Palace separates runtime tenant credentials from operator-only secrets.

Validate tenant identity before write or retrieve flows:

curl -fsS "$PALACEOFTRUTH_API_BASE_URL/api/v1/memory/whoami" \
  -H "X-API-Key: $PALACEOFTRUTH_API_KEY" \
  -H "X-MCP-Scope: read"

The response should identify the tenant represented by the supplied runtime key. If whoami fails, stop and fix the runtime credential before sending memory writes.

First Memory Write

The REST memory facade accepts scoped memory entries. This example writes one small agent-scoped note. It is a live write and should only be run against a tenant where that test memory is expected.

Set PALACEOFTRUTH_TENANT_ID from the tenant_id returned by whoami, then write through the canonical REST envelope:

curl -fsS -X POST "$PALACEOFTRUTH_API_BASE_URL/api/v1/memory/entries" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PALACEOFTRUTH_API_KEY" \
  -H "X-MCP-Scope: write" \
  -H "X-MCP-Scopes: write:agent" \
  --data '{
    "tenant_id": "'"$PALACEOFTRUTH_TENANT_ID"'",
    "title": "Public getting-started smoke memory",
    "body": "Palace smoke memory for a public getting-started guide.",
    "source": "public-getting-started",
    "created_at": "2026-05-21T00:00:00Z",
    "scope": {
      "type": "agent",
      "key": "codex"
    },
    "tags": ["docs-smoke", "palaceoftruth"],
    "metadata": {
      "source": "public-getting-started"
    },
    "relationship_policy": "immediate"
  }'

The write returns a memory job identifier. Poll that job with the memory job endpoint or use the MCP helper command shown below.

First Memory Retrieve

After the write job completes, retrieve scoped memory:

curl -fsS -X POST "$PALACEOFTRUTH_API_BASE_URL/api/v1/memory/retrieve" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PALACEOFTRUTH_API_KEY" \
  -H "X-MCP-Scope: read" \
  --data '{
    "scope": {
      "type": "agent",
      "key": "codex"
    },
    "query": "public getting-started guide smoke memory",
    "limit": 5
  }'

Use exact identifiers, URLs, and tags in retrieval tests when you need deterministic evidence. Semantic retrieval quality depends on the tenant corpus, embedding state, and queued background work.

For trust-aware startup, call get_wakeup_context before a broad semantic query. It returns scoped memory summaries, trust warnings, checkpoint pointers, and safe next probes. See Source-backed wakeup.

MCP Smoke Paths

Dry-run MCP smoke commands are non-destructive and should be the first verification step.

Local stdio dry run from the main Palace repo:

cd backend
uv run python ../scripts/smoke_agent_memory_compatibility.py \
  --api-base-url https://api.palaceoftruth.test \
  mcp-stdio \
  --scope-type agent \
  --scope-key codex \
  --relationship-policy deferred \
  --dry-run

Remote streamable HTTP dry run:

cd backend
uv run python ../scripts/smoke_agent_memory_compatibility.py mcp-http \
  --mcp-url https://mcp.palaceoftruth.example/mcp \
  --scope-type agent \
  --scope-key codex \
  --relationship-policy deferred \
  --dry-run

Live MCP smokes write one deterministic scoped memory, poll the write job, retrieve the smoke memory, list scoped entries, and list recent memory jobs. They do not delete data, call admin endpoints, retry failed jobs, run cleanup, or restore data. Run them only when the appropriate tenant key or MCP bearer/OAuth credential is available.

The repo-packaged agent-client plugin lives at third_party_plugins/agent_clients/palaceoftruth-memory. It includes the Palace MCP adapter packaging, Codex setup guidance, a skillpack, read-only installed-state checks, update planning, and compatibility checks. The Hermes memory plugin source lives at third_party_plugins/hermes/memory/palaceoftruth; the current public manifest version is 1.0.24.

Generated API Docs

The backend exposes generated OpenAPI through FastAPI:

When the backend is behind local devinfra, use https://palaceoftruth.test/docs and https://palaceoftruth.test/api/openapi.json.

Endpoint Families

Current API families are mounted under /api/v1:

See Ingest, capture, and source workflows for the current public map of note, webpage, document, PDF, image, media, browser capture, saved web, RSS, OPML, YouTube channel subscription, and batch ingest paths.

Async Job Behavior

Several flows return quickly with a job id while background workers process the request. Ingest, media/document processing, memory writes, deferred relationship extraction, and maintenance operations can be queued, processing, failed, cancelled, complete, completed, or duplicate.

Use job polling, memory job listing, and Control Tower recovery views for operator visibility. Mutating recovery, cleanup, deletion, restore, and admin registration remain operator actions, not public smoke-test steps.

Error Expectations

Do not work around auth failures with admin secrets in agent runtime config. Fix the tenant runtime credential or MCP client credential instead.

Where To Go Next