Manage Reference Data

Manage Reference Data

Maintain a reference-kind scope — a non-core Brain/ layer of external facts/records the personal brain discovers bridges to, not a query store (a CRM owns queries). This skill upserts entity notes (overwrite-in-place), stamps the reference contract, and reindexes. It is generic: pass scope=<Folder> for any registered reference scope; Company is the default.

Read first: resources/layered-brains/REFERENCE-SCOPE-SCHEMA.md (the generic kind contract: frontmatter + linking + privacy) and the target scope's own schema doc for its type:/relationship: enum + structure (Company → COMPANY-BRAIN-SCHEMA.md, which also defines the family sub-scopes and the ref-* playbook suite this skill is the seed of). This skill enforces those docs; it does not restate them.

Hard rules (non-negotiable — these are what make it a reference scope):

• Every note gets provenance: reference. Never originated/endorsed/encountered/ai-inferred.
• Reference notes are never crystallized, lifecycle-classified, or used as a synthesis-pulse source.
• Reference scopes are non-core → they never train q-values (the engine learn-gate already guarantees this; do not bypass it).
• Default read scope is unchanged. Reference data surfaces only under an explicit BRAIN_READ_SCOPE=core,<Scope> mount.

Step 0 — Resolve the scope and confirm it is registered + reference-kind

cd resources/local-brain-search
SCOPE="${1:-Company}"   # or parse scope=<Folder> from args
./venv/bin/python - "$SCOPE" <<'PY'
import sys, memory_config as mc
folder = sys.argv[1]
print("kind         :", mc.scope_kind(folder))
print("is_reference :", mc.is_reference_scope(folder))
print("is_core      :", folder in mc.CORE_FOLDERS)
PY

• If is_reference is False: the scope is not registered as reference. Stop and either (a) add a ScopeDef(..., SCOPE_KIND_REFERENCE, False, (...)) to SCOPE_REGISTRY in memory_config.py, or (b) register_scope("<Folder>", kind="reference", slugs=(...)). See the schema doc → "Adding a new reference scope". Do not write entity notes into a non-reference folder.

Step 1 — Privacy (settled: private agent, no gate)

Cornelius is a fully private agent on a private remote, so reference data is committed/synced by default — no per-scope gate to clear. Just populate.

The only exception: if this specific scope must be host-local (e.g. third-party data you've agreed not to sync), add Brain/$SCOPE/ to .gitignore first. Default is to commit.

Step 2 — Upsert the entity note (overwrite-in-place)

One note = one entity. Path: Brain/<Scope>/<entity-name>.md for a flat scope; for a family scope, route into the correct child folder per that scope's schema doc (e.g. Brain/Company/people/<name>.md, Company/market/<name>.md — never loose at the family root). Apply the frontmatter contract exactly — type:/relationship: values come from the scope's schema doc:

---
type: <per the scope's schema doc — Company's enum is in COMPANY-BRAIN-SCHEMA.md>
relationship: <per the scope's schema doc, when the scope uses the axis>
provenance: reference
scope: <Scope>
status: active
as_of: <today YYYY-MM-DD>
updated: <today>
created: <today, or preserve existing>
created_by: <your model name>
updated_by: <your model name>
agent_version: 01.25
---

# <Entity display name>

<concise factual body>

## Relations
- <relation>: [[Other Entity]]

## Change Log
- <today> — <what changed and the source>

• add: create the file. update: overwrite-in-place (re-stamp as_of:/updated:, preserve created/created_by). Reference data is mutable — overwriting is correct, not destructive.
• supersede: set the old note status: superseded + superseded_by: "[[New Entity]]"; create the new note status: active. Keep both (history).
• Relations are [[wiki-links]] (explicit edges, traversed by connection-finder). Use a contract/engagement note as the join for many-to-many (Client × Product × owner × dates × value).