Project Reports

Overview

Agents, workers, CI jobs, and Mac clients POST a Project Report JSON document to POST /api/v1/project-reports. ProjectMind validates it against a published JSON Schema, stores the raw payload, normalizes queryable rows, and updates a per-environment latest pointer. Historical reports are never deleted.

The versioned HTTPS API is the canonical ingestion interface. Future MCP tools are read-only facades over the same application services — do not treat MCP as the write path.

Project manifest (imemory.project.yaml)

Connected repositories declare capabilities, commands, protected paths, verification, and autonomy templates in imemory.project.yaml. ProjectMind validates the manifest, caches the last valid snapshot, and drives the improvement loop from configuration — not from project-name branches.

• Schema: manifest-schema.json
• Example: examples/imemory.project.yaml (sample-project fixture)
• Autonomy templates: observe-only, propose-only, manual-execution, safe-pull-request, low-risk-autonomous, finance-safe, privacy-sensitive
• Category policies (backend-enforced): product may code; relationship/financial categories route to task hub / briefing / user-action queues and never the coding agent.

Connect a new project (no ProjectMind code change)

1. Create the project in ProjectMind and connect its Git repository (configure a runtime project path).
2. Add imemory.project.yaml and AGENTS.md to the repository.
3. Refresh/load the manifest from project settings or the local Mac agent path.
4. Mint a project-report credential and POST the first report.
5. Select an autonomy template (or declare it in the manifest).
6. Confirm readiness: manifest valid, reporting configured, required commands present, coding/verification capabilities as needed.

Rule: new project = configuration and contract implementation. New platform capability = ProjectMind code change.

Quick start

1. Create a project report credential (token prefix impr_) with scope project-reports:write for your project. From the ProjectMind repo: npm run mint:project-report-credential -- --project-id <uuid> --name "reporter".
2. Download the minimal example and set project.id to your ProjectMind project UUID.
3. POST to /api/v1/project-reports with the bearer token.

curl -X POST https://your-imemory-host/api/v1/project-reports \
  -H "Authorization: Bearer impr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d @minimal.json

Authentication

Use a per-project credential. Pass the token as Authorization: Bearer impr_… or x-api-key. Tokens are stored as SHA-256 hashes only. Required write scope: project-reports:write. Credentials may expire or be revoked; expired/revoked tokens are rejected.

The credential is bound to a single project. Submitting a report whose project.id does not match returns 403.

Complete schema reference

Generated from the canonical JSON Schema (no hand-maintained field list). Unknown root-level properties are rejected; unknown keys inside extensions are accepted.

Examples

Valid examples live under spec/examples/ and are validated in CI: minimal, full, SaaS, mobile app, background worker, Mac agent, and coding agent.

• Minimal
• Complete

API reference

Generated from the OpenAPI document.

Rate limit: 60 requests / minute per credential. Success shape for ingest: { accepted, reportId, projectId, schemaVersion, receivedAt }.

Validation rules

• Body must match JSON Schema draft 2020-12; additionalProperties: false at the root (and nested objects except extensions).
• Only schemaVersion: "1.0" is accepted.
• Enums enforced for status, environment, severity, task status, deployment status.
• Timestamps must be ISO-8601 date-time.
• Maximum body size: 512 KiB.

Retry & idempotency

Clients should set a stable reportId (and optionally Idempotency-Key). Replaying the same id with the same payload returns 202 with duplicate: true. A different payload for the same id returns 409. Retry with exponential backoff on 429 / 5xx — do not retry 401, 403, or 422.

TypeScript / Python / cURL

import { IMemoryProjectReporter } from "@imemory/project-reporter";

const reporter = new IMemoryProjectReporter({
  baseUrl: "https://your-imemory-host",
  token: process.env.IMEMORY_PROJECT_REPORT_TOKEN!,
});

await reporter.submit({
  project: {
    id: "11111111-1111-1111-1111-111111111111",
    name: "Example App",
    environment: "production",
    status: "healthy",
  },
});

import json, urllib.request, uuid, datetime

token = "impr_YOUR_TOKEN"
body = {
  "schemaVersion": "1.0",
  "reportId": str(uuid.uuid4()),
  "generatedAt": datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.000Z"),
  "project": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Example App",
    "environment": "production",
    "status": "healthy",
  },
}
req = urllib.request.Request(
  "https://your-imemory-host/api/v1/project-reports",
  data=json.dumps(body).encode(),
  headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Idempotency-Key": body["reportId"],
  },
  method="POST",
)
print(urllib.request.urlopen(req).read().decode())

curl -X POST https://your-imemory-host/api/v1/project-reports \
  -H "Authorization: Bearer impr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d @minimal.json

MCP architecture

MCP is not the primary write interface for project reports. Planned read-only MCP tools (list_projects, get_project, get_latest_project_report, get_project_metrics, get_project_issues, get_project_timeline, compare_projects, generate_project_briefing, find_projects_requiring_attention) call the same internal services as this REST API. Write tools will not be added for report ingestion.

Facades live in src/lib/project-reports/mcp-facade.server.ts.

Changelog

• 1.0.0 — Initial Project Reports API, schema, OpenAPI, docs, and SDK scaffold.

Downloads

• manifest-schema.json
• project-report-schema.json
• schema.json (alias of project-report-schema)
• openapi.json
• openapi.yaml
• examples/imemory.project.yaml
• examples/sample-project.json
• examples/minimal.json
• examples/full.json
• Also: /openapi.json, /openapi.yaml, /api/v1/project-report-schema

See also API docs and MCP docs.