> ## Documentation Index
> Fetch the complete documentation index at: https://commons-knowledge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ontology and schema

> The records, evidence and relationships that make up Commons.

Your work generates sources, decisions, conversations and findings. How you organise and connect that information is your **ontology**, and it should reflect what you’re trying to achieve. A **schema** defines how those records and relationships are stored.

Say you’re researching whether one AI model can repair another. Save the paper as a **Source**, keep its original text in an **Artifact**, and connect a **Note** about the method to that Source. If it raises a question worth following up, link a **Task**. Another agent can follow those connections back to the evidence.

## The database

Commons uses **PostgreSQL**, a database that stores information in tables. It keeps records and relationships together, checks that references are valid, and supports reliable updates. Search vectors also live in PostgreSQL.

The **Objects** table holds the core knowledge records. Other tables hold identities, original evidence, activity and supporting data:

| Table | What it stores |
| - | - |
| `objects` | Tasks, Notes, Entities, Sources, Themes, Events and Threads |
| `users` | Human and agent identities |
| `credentials` | Sessions and scoped access tokens, stored as hashes |
| `artifacts` | Original text, files and their versions |
| `connections` | Typed relationships with an explanation |
| `changes` | Record changes, corrections and history |
| `traces` | Observed executions |
| `trace_items` | Messages, tool calls, results and steps |
| `request_receipts` | Saved write results used to handle retries |
| `chunks` | Derived text and vectors used for search |

Connections can link Objects, Users, Artifacts and Traces. Some tables also have direct ownership references, such as an Artifact's owning Object.

## An Object is an atomic unit of information

An Object is a small record about one thing: a task, decision, organisation or occurrence. It has a title, description, body and fields for its kind.

| Kind | Use it for |
| - | - |
| Task | Work with an owner, deadline, status and priority |
| Note | A finding, fact, idea, question or exact excerpt |
| Entity | A supplier, organisation, person or other subject |
| Source | A document or work whose evidence you keep |
| Theme | An organising concept |
| Event | An occurrence |
| Thread | A captured conversation |

The formatted title, description and body must fit **500 tokens**, including formatting. Keep long documents in Artifacts and link them to a concise Object. Oversized Objects are rejected rather than shortened automatically.

Users and Traces are separate records, not Object kinds. A Thread identifies a conversation; its messages and activity are stored separately in `trace_items`.

## Evidence and relationships

A Source describes a work. Its Artifacts keep the original text or files. A Note can record a finding and connect it to the Source it came from.

Give each Connection a specific meaning, such as “derived from” or “depends on”, and explain why it exists. A saved claim is still a claim; keeping its evidence lets someone check it.

## Adapt it to your organisation

Every organisation has different work and vocabulary. Start with existing kinds and fields. A supplier can be an Entity; procurement work can be a Task with a project field.

New kinds or fields may require changes to validation, migrations, search, tools and the UI. Update and test those together so agents and the app use the same structure. See [Customisation and Overlays](https://commons-knowledge.mintlify.site/customisation.md).

The repository's `docs/atomic-schema.md` defines the exact tables and fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.