Concepts

The Vault

Doss is a plain folder, usually ~/.doss, synced across the owner’s devices with git. Agents remember and recall by reading and writing files.

~/.doss/
  self/          facts about the owner; path = topic
  peers/         what other people shared with the owner
  notes/         Markdown scratch; never disclosed
  policy.yaml    synced disclosure rules for owner memory
  devices/       synced active/deactivated device records
                 plus GitHub deploy-key metadata when available
  ledger/        disclosure log, one append-only JSONL file per device
  local/
    access.yaml  device-local access rules; gitignored, never synced
  INSTRUCTION.md entry router agents read first
  CONTENT.md     content maintenance rules
  DISCLOSURE.md  outbound disclosure and local access rules

Content under self/, peers/, and notes/ is Markdown. YAML is reserved for configuration files such as policy.yaml and local/access.yaml.

Fact Shape

A self/**/*.md fact is Markdown, optionally with YAML frontmatter. A non-empty rough string is required only when policy.yaml grants rough disclosure for that fact’s topic.

---
source: owner
status: active
confidence: high
tags: [profile]
rough: "Toronto"
---
Home address: 123 King St W, Toronto.

The path is the policy topic: self/profile/address.md is governed by profile/address. rough: is the only owner-authored coarse/redacted value. The Markdown body is the full private fact; no is a policy outcome, not a fact field. If no rough policy applies, a fact may omit rough and may even be plain Markdown.

Disclosure Policy

policy.yaml answers: what owner memory may this verified requester receive? It syncs because it is the owner’s portable disclosure preference.

groups:
  friends:  [kordi:pedro, kordi:qiancx]
  contacts: [kordi:jiaxin]
 
can-see:
  friends:
    profile/address: rough   # share only rough:
    profile/dietary: full    # share the Markdown body
    work: rough              # applies under self/work/
  contacts:
    profile/address: rough
  # anything not listed: no disclosure

Policy levels are no, rough, and full.

• no: disclose nothing. This is also the default when no rule matches.
• rough: disclose only the fact’s rough: value.
• full: disclose the Markdown body after frontmatter.
• If rough is allowed but the fact has no valid rough: value, disclose nothing for that fact. The agent must not invent a summary from the full body.

Topics omit the self/ prefix. A topic can be a folder such as work or a fact such as profile/address; folder rules inherit downward, and more specific rules win. If someone belongs to several groups, the highest level wins in this order: no, then rough, then full.

status: suggested facts are never disclosed. peers/ and notes/ are never disclosed.

Local Access

local/access.yaml answers a different question: what may this requester ask this device’s agent to do with local folders? It is gitignored because folder paths and local risk differ per machine.

grants:
  friends:
    ~/Projects/opensource: full    # read, edit, run
    ~/Documents/public: read       # read/share only
  contacts:
    ~/Projects/opensource: read

These files do not grant each other. policy.yaml never permits editing local projects, and local/access.yaml never permits disclosure of owner facts from self/.

Requester Views

doss view --for VERIFIED_ID --out DIR creates a short-lived directory for one external requester. It combines the two gates without mixing their meanings:

• allowed owner facts from policy.yaml are projected under generated self/
• local folder grants from local/access.yaml are projected into access.json
• manifest.json records the requester id, expiry, source hashes, source vault commit, and any rough-shared facts omitted because rough: was missing

Denied topics, unlisted topics, status: suggested facts, missing rough values, peers/, and notes/ are omitted. doss view validates the vault before export and refuses policy, access, device, or ledger problems other than missing rough: values; missing rough: values are omitted and recorded in manifest.json. A host should generate a fresh view after changing policy.yaml or local/access.yaml, then give the external-facing agent only that view instead of the raw vault.

Identity

Disclosure starts from trusted request metadata supplied by the host platform, not from message text. A requester id should look like kordi:pedro. If there is no verified id, the requester is treated as unknown and default deny applies.

When a verified requester is not in any policy.yaml group, the agent asks the owner which existing or new group should include that id. Until the owner answers and policy.yaml is updated, nothing leaves.

Devices

Every device has a synced YAML record under devices/ with status: active or status: deactivated. GitHub-backed vaults also store the repository and deploy-key id for that device. doss init registers the current device, installs a per-device writable GitHub deploy key when the vault is GitHub-backed, and prints the same list as doss devices.

doss uninstall marks the current device deactivated, pushes that state when possible, revokes its recorded GitHub deploy key when present, and then deletes the local vault.

Agent Rule Files

INSTRUCTION.md is intentionally small. It tells agents which rule file to read:

• CONTENT.md for maintaining Markdown memory content.
• DISCLOSURE.md for outbound disclosure and local access decisions.

This keeps daily memory writing separate from public disclosure while giving doss connect one stable entry point to inject into agent instructions.