An integration should connect another system to Kival without turning Kival into a blind mirror of that system.
Start by deciding what knowledge should become durable and shared. Source-specific synchronization policy belongs in the integration; Kival provides the object identity, history, access, context, and conflict semantics around the resulting knowledge.
Preserve stable object identity
When an external record maps to a Kival object, keep that mapping stable across synchronization runs. If the source changes, update the existing object rather than creating a fresh copy every time.
A source identifier can be stored in flat metadata as an integration convention. Kival does not prescribe a universal external-ID schema, so choose a convention that your integration can reconcile predictably.
Preserve provenance instead of copying blindly
External material may belong in Kival as a source object, an attachment, a reference, or metadata rather than as duplicated prose.
When an integration produces a synthesis or conclusion, write the durable result into the object and represent the source context explicitly enough that a later reader can understand where it came from. Kival records actions performed inside Kival; it cannot infer external lineage that the integration never supplies.
Reconcile concurrent changes
Object updates are optimistic. If the current version has changed since the integration read it, Kival returns a conflict.
Treat that as a reconciliation point. Re-read the current object, compare the external change with the new Kival state, and decide what should be published next. Do not hide the conflict behind unconditional last-write-wins behavior.
Choose how the integration observes change
Depending on the source and latency requirements, an integration can:
poll Kival state;
process durable audit events incrementally;
use realtime invalidations as a low-latency signal and then refresh authoritative HTTP state.
Kival currently does not deliver outbound webhooks. If a source system expects webhook-style delivery, receive that webhook in your integration and translate it into Kival operations there.
Scope each integration independently
Give each integration its own labeled API key with only the scopes and workspace delegation it needs. This limits impact and preserves audit attribution between otherwise unrelated systems.
Personal UI state such as favorites, pins, inbox entries, and passkey/session management is intentionally not part of the general service-integration surface.
Attachments and external files
Attachments are useful when the source artifact itself matters: reports, exported files, evidence, or other supporting material can remain associated with an object.
Do not assume attaching a file makes its contents part of the object's authored body or search model. If the important outcome is a durable conclusion or procedure, represent that in the object and keep the file as supporting context.
Keep source-specific behavior outside Kival
Kival does not impose a universal connector framework. Authentication to the source, polling schedules, source cursors, deduplication, field mapping, deletion policy, reconciliation, and external side effects belong in the integration.
That boundary keeps Kival focused on the shared knowledge that survives those integrations rather than on the operational mechanics of every external system.