---
title: "Brief"
method: POST
path: "/kythene.v1.KytheneService/Brief"
tags: ["kythene.v1.KytheneService"]
---

# Brief

`POST /kythene.v1.KytheneService/Brief`

## Request

- Base URL: `https://kythene.com` (the document declares no server; this is the origin it was published from)
- URL: `https://kythene.com/kythene.v1.KytheneService/Brief`
- Auth: none required

Brief is the single session-opening call: workspace guide + catchup delta +
 project memory index + inbox, compact enough to prime a session in one shot.

## Headers

- `Connect-Protocol-Version` 1, required: Define the version of the Connect protocol
- `Connect-Timeout-Ms` number: Define the timeout, in ms

## Request body

- KytheneV1BriefRequest
  - `project` string: project optionally scopes the memory index to one project (a project-kind tag name, or the value from resolve_project); empty briefs the whole workspace.
  - `peek` boolean: peek reads the catchup delta without advancing the cursor. Default false: brief is the session opener, so it consumes the delta like catchup does.
  - `space` string: space optionally selects which of your spaces to brief (an id or name from list_spaces). Omit it when you belong to a single space.

## Response `200`

Success

- KytheneV1BriefResponse
  - `workspaceId` string
  - `workspaceName` string
  - `project` string: project is the scope the index reflects (empty = the whole workspace).
  - `guide` string: guide is the workspace operating manual - the house rules for working here.
  - `catchup` string[]: catchup lists, compactly, what changed since this instance last looked (publishes, versions, feedback, promotions) - excluding your own instance's writes. catchup_more counts entries beyond this list; first_look is true for a brand-new instance with no delta window yet.
  - `catchupMore` integer
  - `firstLook` boolean
  - `memoryIndex` KytheneV1BriefMemoryEntry[]: memory_index is the project's memory as titles + one-line hooks + ids, NOT bodies - enough to know what exists and whether it matters, then fetch by id.
    - `id` string
    - `title` string: title is what the memory is about.
    - `hook` string: hook is a one-line snippet - enough to know whether the memory matters, NOT the body. Fetch the full memory by id (recall) when it does.
    - `type` string
    - `project` string
    - `updatedAt` string, date-time: A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format.
  - `memoryTotal` integer: memory_total is how many memories are in scope; the index may be capped to keep the brief compact, so total greater than len(memory_index) means there is more - recall to page it.
  - `inboxCount` integer: inbox_count is how many items await you across your workspaces; headlines is a short preview of the most recent.
  - `inboxHeadlines` string[]
  - `truncated` boolean: truncated is true when any list here was capped to keep the brief small, so a reader knows it has not seen everything (rather than mistaking the cap for the whole - the manufactured-absence trap).
  - `startHere` string: start_here is set ONLY when this workspace holds no memories at all, and it carries what to do about that (#153). An empty workspace is the one state where every other field is blank and the tools all look broken: recall returns nothing, so the assistant reasonably concludes Kythene has nothing to offer and stops calling it - the workspace then stays empty forever. This is the instruction that breaks that loop, and it is delivered HERE because brief is the one call every client is told to make first, whether it loaded a skill, a plugin or nothing at all. It disappears by itself the moment the workspace has content, so it can never become stale advice. Do not confuse it with first_look, which is about this INSTANCE's cursor: a brand-new instance connecting to a mature workspace sets first_look and must NOT be given onboarding.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/kythene/apis/kythene-v1.md) · [All operations](https://skmtc.dev/kythene/apis/kythene-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/kythene/apis/kythene-v1/revisions/5a768e642d10?raw)