Ontology and schema

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. The repository’s docs/atomic-schema.md defines the exact tables and fields.

​The database

​An Object is an atomic unit of information

​Evidence and relationships

​Adapt it to your organisation

The database

An Object is an atomic unit of information

Evidence and relationships

Adapt it to your organisation