Organize your context repository

Overview

Three consumers read your folder structure:

People browsing the Context tab.
Retrieval agents traversing paths with qontext_ls, qontext_find, qontext_grep, and hybrid search.
Continuous update agents placing each incoming record.

All three need the same thing: shallow folders with non-overlapping purposes, and one home per entity. Qontext proposes a structure when your repository is first built. You can change it at any time.

Recommended structure

Organize the top level by ownership and lifecycle, not by topic:

agents

skills

company

teams

engineering

sales

projects

Folder	Holds	Lifecycle
`agents/`	Reusable agent instructions and resources, including `skills/`	As long as agents use it
`company/`	Organization-wide knowledge: strategy, policies, positioning	Superseded, never closed
`teams/`	Responsibilities, processes, and relationships owned by one team	Ends when the responsibility moves
`projects/`	Initiatives with a defined outcome and end	Ends when the initiative does

This resolves the ambiguous case: a customer account belongs to the team that owns it, while a time-boxed migration for that same customer belongs in projects/ and links back to the account. Matches the repository root structure file template.

By business function instead.engineering, growth, operations, product works when every topic has one departmental home. It breaks as soon as work crosses functions, because a cross-team initiative then has several plausible homes.

Principles

One entity, one primary record. One file per customer, person, project, or topic. Search before creating; update rather than add a second record.
Link instead of copying. References are returned inline as file IDs, so an agent follows a link straight into qontext_cat. A copy diverges silently; a link cannot.
Keep folder purposes non-overlapping. When continuous updates are enabled for a source, its agents read the structure files of every folder that could hold a record. Where two folders both qualify, strictness decides placement, not your intent.
Name for retrieval. Agents traverse paths before reading content. teams/sales/customers/acme/overview.md says what it contains; teams/sales/docs/file-2.md does not.
Create folders when content arrives. Every empty folder is a path an agent must consider and rule out.

Access boundaries follow your folder tree.Access widens deeper in the tree but never narrows — restricting a subtree means setting the narrower access on its parent. Content that only some members or API keys should reach needs its own subtree from the start, not a restricted file inside an open folder. See Access management.

Naming conventions

Convention	Example
Lowercase with hyphens	`northstar-industries.md`
ISO date prefix on dated records	`2026-09-04-quarterly-review.md`
`overview.md` for an entity’s primary record	`teams/sales/customers/acme/overview.md`
Name the entity, not its category	`jane-smith.md`, not `contact-1.md`
Preserve required names exactly	`SKILL.md`, `.qontext.structure.md`

Date prefixes sort chronologically and make a record’s period visible in a qontext_ls listing without reading it.

Folder patterns

Sales and customer knowledge

teams

sales

customers

acme

overview.md

meetings

2026-09-04-quarterly-review.md

support

sso-login-failure.md

contacts

jane-smith.md

pipeline

northstar

overview.md

rev-ops

deal-stages.md

qualification-criteria.md

sales-handoff.md

Location	Contains
`customers/`	One folder per customer company
`pipeline/`	One folder per prospective company
`overview.md`	Status, owner, sources, snapshot, contacts, motivation, dated history
`meetings/`	One dated record per meeting
`support/`	One record per distinct issue
`contacts/`	One record per person
`rev-ops/`	Sales definitions and procedures shared across accounts

Northstar has only overview.md because nothing else exists yet — the subfolders appear when content does. One location per company. Let your CRM decide pipeline or customers; when the status changes, move the folder in the Context tab rather than creating a second record. Use the sales structure file template to automate this layout.

Projects

projects

customer-portal

overview.md

decisions

2026-09-02-authentication.md

meetings

2026-09-04-kickoff.md

One primary home per cross-team project, linked from each team involved. Goal, owner, status, milestones, risks, and next steps go in overview.md; decisions and meetings get their own files. Use the project summaries structure file template.

Agent skills

agents

skills

prepare-customer-meeting

SKILL.md

references

briefing-format.md

One folder per skill, named to match the name in SKILL.md. Supporting files go in references/, scripts/, or assets/ and load only when needed. Link to shared company knowledge rather than copying it into each skill. See Skills distribution.

File templates

Fictional examples. Adapt the sections, not the content.

Entity overview

Place at: <entity folder>/overview.md Use when: A customer, prospect, person, product, or team needs one record answering the common questions.

overview.md

# Acme

| Metadata | Value |
| --- | --- |
| Status | POC |
| Owner | Maya Chen |
| Sources | HubSpot: Acme; Slack: #acme-x-qontext; Notion: [Weekly] Team check-out |

## Snapshot

One open POC in the Customers pipeline: a six-week test with Acme's support organization. The workspace holds roughly 400 files after one restructure. As of 2026-09-04, two groups and nine users are active.

## Contact person

Jane Smith — Head of Support: project sponsor and Qontext admin. Requested the separate testing workspace. Email: jane.smith@acme.example.

Tom Alvarez — role not recorded: joined the initial scoping meeting. Email: tom@acme.example.

## Why they want to work with us

Phase one gives support agents policy and account context from Salesforce and public Slack channels. Phase two tests whether the same layer serves the sales organization; the Head of Support has brought two engineers in to evaluate it.

## History

2026-09-05: Three users could not complete SSO login. Cause not confirmed; tracked as [SSO login failure](support/sso-login-failure.md).

2026-09-04: The [quarterly review](meetings/2026-09-04-quarterly-review.md) confirmed Salesforce and Slack as the initial sources.

2026-08-21: Acme restructured the repository and began testing. Retrieval was about 1.1 seconds across several hundred files.

## Other

Customers pipeline; POC; open; high priority.

Open support: SSO login failure affecting accounts created before 2026-08-20.

Recommended setup: repository default member access set to no access, department folders shared to groups.

An overview carries durable state — what is true now, and the dated history behind it. Action items and open questions belong in the meeting record that raised them; here they go stale within days and lose their origin. Mark what a source does not establish, in place: “role not recorded”, “cause not confirmed”. Otherwise an agent answering from this file presents your inference as fact.

Meeting record

Place at: <entity folder>/meetings/YYYY-MM-DD-<topic>.md Use when: A conversation produced decisions or actions that later work depends on.

2026-09-04-quarterly-review.md

# Quarterly review — Acme

**Date:** 2026-09-04
**Attendees:** Maya Chen, Jane Smith, Tom Alvarez
**Source:** HubSpot meeting note

## Decisions

- Salesforce and Slack are the initial sources for the pilot.

## Discussion

- Support volume has doubled since June; Acme wants agents to answer from account history.
- The sales expansion depends on a successful support pilot.

## Actions

- Maya: confirm the Salesforce scope by 2026-09-11.
- Jane: validate the SSO fix with three test users.

## Open questions

- Whether the sales expansion needs a separate agreement.

One meeting per file, and the home for action items and open questions — both stay tied to the conversation that produced them. Where the meeting exists in a source, link it and update this file when the source note changes.

Decision record

Place at: projects/<project>/decisions/YYYY-MM-DD-<topic>.md Use when: A choice constrains later work and its reasoning must outlive the people who made it.

2026-09-02-authentication.md

# Authentication for the customer portal

**Date:** 2026-09-02
**Status:** Accepted
**Owner:** Tom Alvarez

## Decision

Use the existing SSO provider for the customer portal instead of building a separate login.

## Context

Two options: extend the current SSO provider, or run a standalone identity service for external users.

## Reasoning

Extending SSO reuses the audited login path and avoids a second set of credentials. The standalone service would have supported per-customer branding, which no customer has asked for.

## Consequences

- External users need accounts in the SSO provider.
- Per-customer branding requires revisiting this decision.

## Supersedes

Nothing.

Mark a superseded decision and leave it in place rather than deleting it.

Issue record

Place at: <entity folder>/support/<issue>.md Use when: A distinct problem needs its own investigation thread, separate from the entity overview.

sso-login-failure.md

# SSO login failure

**Status:** Open
**Reported:** 2026-09-05 by [Jane Smith](../contacts/jane-smith.md)
**Affects:** [Acme](../overview.md)

## Symptom

Three Acme users cannot complete SSO login. The provider returns a valid assertion and no session is created.

## Confirmed

- Reproduced for two of the three reported accounts.
- Only accounts created before 2026-08-20 are affected.

## Not confirmed

- Whether the provider's recent metadata change is the cause.

## Next steps

- Compare the assertion for an affected and an unaffected account.

The Confirmed and Not confirmed split is the point: an agent answering from this file must not pass an open hypothesis off as established.

Anti-patterns

Pattern	Failure	Fix
One company under both `customers/` and `pipeline/`	Two partial answers, neither current	One folder per company, moved on status change
A `misc/`, `general/`, or `docs/` folder	Nothing is decidably out of scope	Name folders by what belongs in them
`teams/sales/emea/enterprise/accounts/acme/`	Every level is another path to traverse	Keep only levels that carry meaning
A policy copied into several folders	Copies diverge; none is authoritative	One record, linked
Restricted content in an open folder	Access cannot narrow further down the tree	Give it its own subtree
Placeholder files and empty folders	Paths that return nothing	Create them when content exists
Dates inside the file but not in its name	Same-topic records collide in a listing	Prefix with the ISO date

Check your structure

Each case should have exactly one answer:

Case	One correct home
A meeting note for an existing customer	That company’s `meetings` folder
A prospect becomes a customer	The existing company folder, moved
A policy published in Confluence	The policies folder under `company`
A migration for one customer, staffed across two teams	`projects/`, linked from both teams
A reusable instruction set for an agent	Its own folder under `agents/skills/`
A person working at two accounts you track	One contact record, linked from both

Two plausible homes means that boundary is not distinguishable yet. Tighten the folder definitions, then record the rule in the folder’s structure file.

Set up your structure

Shape the top level

In the Context tab, create your top-level folders. Every one is a boundary you will maintain, so keep the count small.

Write the root structure file

Add /.qontext.structure.md from the repository root template. Root guidance is inherited by every folder, so shared conventions belong here and nowhere else.

Set access on folders, not files

Set restrictions on the parent of the subtree you want to limit. See Access management.

Add folder-specific guidance

Give folders with their own rules — accounts, policies, projects — a structure file covering only what differs from the root.

Review what lands

Watch the Changes tab. Misplacements and duplicates point at a folder boundary that needs sharpening, not a missing folder.

Prompts to get started

“List my top-level folders and tell me which two have the most overlapping purpose.”
“Find companies that appear in both customers and pipeline, and propose which record should survive.”
“Which folders contain no files, or only a single placeholder file?”
“Draft an overview.md for teams/sales/customers/acme from everything you can find about Acme.”

Get started

Context repository

Interfaces

Features

Sources

Clients

Organize your context repository

Overview

Recommended structure

Principles

Naming conventions

Folder patterns

Sales and customer knowledge

Projects

Agent skills

File templates

Entity overview

Meeting record

Decision record

Issue record

Anti-patterns

Check your structure

Set up your structure

Prompts to get started

​Overview

​Recommended structure

​Principles

​Naming conventions

​Folder patterns

​Sales and customer knowledge

​Projects

​Agent skills

​File templates

​Entity overview

​Meeting record

​Decision record

​Issue record

​Anti-patterns

​Check your structure

​Set up your structure

​Prompts to get started

Overview

Recommended structure

Principles

Naming conventions

Folder patterns

Sales and customer knowledge

Projects

Agent skills

File templates

Entity overview

Meeting record

Decision record

Issue record

Anti-patterns

Check your structure

Set up your structure

Prompts to get started