entities

name	entities
description	Tracked entities — people, companies, projects, tools — within facets. Detect, attach, move, merge/undo, resolve ambiguities, restore versions, update, alias, search, network, relationship history, entity history, overview. TRIGGER: entity, person, company, relationship, who is, contact, sol call entities detect/attach/merge/search/network/history/overview.

Entities CLI Skill

Maintain facet-scoped entity memory. Invoke via Bash: sol call entities <command> [args...].

Environment defaults: When SOL_FACET is set, all commands use it automatically. Same for SOL_DAY where DAY is accepted.

Common pattern:

sol call entities <command> [args...]

Entity Lifecycle

• Detected: day-scoped, ephemeral observations captured for a specific day.
• Attached: persistent entities tracked long-term in a facet.
• Blocked: entities the owner has blocked; do not detect, attach, or reuse.
• Detached: entities the owner removed; do not re-attach automatically.

Use detect for day-specific sightings and attach for long-term tracking.

list

sol call entities list [FACET] [-d DAY]

List entities for a facet.

• FACET: facet name (default: SOL_FACET env).
• -d, --day: optional day (YYYYMMDD).

Behavior notes:

• Without --day: lists attached (permanent) entities.
• With --day: lists detected entities for that day.

Examples:

sol call entities list work
sol call entities list work -d 20260115

detect

sol call entities detect TYPE ENTITY DESCRIPTION [-f FACET] [-d DAY]

Record a detected entity for a day.

• TYPE: entity type (alphanumeric + spaces, minimum 3 chars).
• ENTITY: entity id, full name, or alias.
• DESCRIPTION: day-scoped description.
• -f, --facet: facet name (default: SOL_FACET env).
• -d, --day: day in YYYYMMDD (default: SOL_DAY env).

Behavior notes:

• If ENTITY matches an attached entity, detection uses its canonical name.
• Blocked entities are rejected.
• Duplicate detections for the same day are rejected.

Example:

sol call entities detect "Person" "Alicia Chen" "Led architecture review" -f work -d 20260115

attach

sol call entities attach TYPE ENTITY DESCRIPTION [-f FACET]

Attach an entity permanently to a facet.

• TYPE: required type.
• ENTITY: id, name, or alias reference.
• DESCRIPTION: persistent description.
• -f, --facet: facet name (default: SOL_FACET env).

Behavior notes:

• If already attached, command reports existing entity.
• Blocked entities are rejected.
• Previously detached entities are rejected.

Example:

sol call entities attach "Company" "Acme Corp" "Primary platform vendor" -f work

update

sol call entities update ENTITY DESCRIPTION [-f FACET] [-d DAY]

Update entity description.

• ENTITY: entity id, name, or alias for attached entities; exact name for day-scoped detected updates.
• DESCRIPTION: new description.
• -f, --facet: facet name (default: SOL_FACET env).
• -d, --day: optional day (YYYYMMDD) to update a detected entity.

Behavior notes:

• Without --day: updates an attached entity.
• With --day: updates a detected entity for that day.

Examples:

sol call entities update "acme_corp" "Primary vendor for identity services" -f work
sol call entities update "Alicia Chen" "Discussed migration plan" -f work -d 20260115

move

sol call entities move ENTITY --from FACET --to FACET [--merge] [--consent]

Move an attached entity from one facet to another.

• ENTITY: entity name or partial match.
• --from: source facet.
• --to: destination facet.
• --merge: merge observations and relationship if an entity already exists in the destination.
• --consent: assert that explicit owner approval was obtained before the move (agent audit trail).

Behavior notes:

• Without --merge: fails if the entity already exists in the destination facet.
• With --merge: combines observations (deduplicated by content + observed_at) and preserves an existing relationship record; the source directory is removed afterwards.
• Both facets must exist.

Examples:

sol call entities move "Alex Chen" --from personal --to work
sol call entities move "Alex Chen" --from personal --to work --merge --consent

aka

sol call entities aka ENTITY AKA [-f FACET]

Add an alias to an attached entity.

• ENTITY: entity id, name, or alias reference.
• AKA: alias to add.
• -f, --facet: facet name (default: SOL_FACET env).

Behavior notes:

• Automatically skips aliases that equal the first word of the entity name.
• Automatically deduplicates existing aliases.
• Validates alias uniqueness across entities in the facet.

Example:

sol call entities aka "Federal Aviation Administration" "FAA" -f work

observations

sol call entities observations ENTITY [-f FACET]

List durable observations for an attached entity.

• ENTITY: entity id, name, or alias.
• -f, --facet: facet name (default: SOL_FACET env).

Output is numbered for quick review.

Example:

sol call entities observations "Alicia Chen" -f work

observe

sol call entities observe ENTITY CONTENT [-f FACET] [--source-day DAY]

Add a durable observation to an attached entity.

• ENTITY: entity id, name, or alias.
• CONTENT: observation text.
• -f, --facet: facet name (default: SOL_FACET env).
• --source-day: optional day (YYYYMMDD) when this was observed.

Behavior notes:

• Observation number is auto-calculated by the CLI.

Observation Quality Guidance

Good observations (durable factoids):

• "Prefers async communication over meetings"
• "Works PST timezone, typically available after 10am"
• "Has deep expertise in distributed systems and Rust"
• "Reports to Sarah Chen on the platform team"

Bad observations (day-specific activity; use detect instead):

• "Discussed API migration today"
• "Sent contract for review"

Example:

sol call entities observe "Alicia Chen" "Prefers design docs before implementation" -f work --source-day 20260115

search

sol call entities search [--query QUERY] [--type TYPE] [--facet FACET] [--since YYYYMMDD] [--limit N]

Search entities by text, type, facet, or detected activity since a day.

• --query: optional text query.
• --type: filter by entity type (e.g., Person, Company).
• --facet: filter by facet.
• --since: filter to entities detected on or after YYYYMMDD.
• --limit: maximum results.

Examples:

sol call entities search --query "Chen"
sol call entities search --type Person --facet work
sol call entities search --since 20260115

network

sol call entities network ENTITY [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--evidence-limit N] [--include-principal] [--json]

Show one-hop recorded connections for a journal entity.

• ENTITY: entity id, name, or alias. Output uses the journal entity id slug.
• --kinds: optional edge kind filter; repeat the flag or comma-separate values.
• --facet: optional facet filter and resolution scope.
• --day-from, --day-to: optional evidence day bounds.
• --limit: maximum neighbors to show.
• --evidence-limit: evidence rows per neighbor.
• --include-principal: include the owner/principal entity when it would otherwise be hidden.
• --json: return the raw route payload.

Behavior notes:

• Empty output means the edge table exists but this entity has no recorded connections under the filters.
• Ranking counts only evidence dated up to today; each item carries an evidence_class of attendance, semantic, or mixed.
• If the edge index has not been built, the command tells the owner to run journal indexer --rescan.

Examples:

sol call entities network "Alicia Chen" --facet work
sol call entities network romeo_montague --limit 10 --evidence-limit 2

history

sol call entities history ENTITY [PEER] [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--offset N] [--json]

Show newest-first evidence rows for one entity pair.

• ENTITY: entity id, name, or alias.
• PEER: optional peer entity. If omitted, defaults to the principal entity.
• --kinds: optional edge kind filter; repeat the flag or comma-separate values.
• --facet: optional facet filter and resolution scope.
• --day-from, --day-to: optional evidence day bounds.
• --limit: maximum evidence rows.
• --offset: pagination offset.
• --json: return the raw route payload.

Behavior notes:

• Evidence rows include day, edge kind, available label/anchor, source, and path.
• History is the full honest pair record, including future-dated evidence rows.
• If no principal entity exists and PEER is omitted, the command fails and asks for PEER.

Examples:

sol call entities history "Alicia Chen"
sol call entities history "Alicia Chen" "Sam Rivera" --day-from 20260601

overview

sol call entities overview [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--json]

Show the global recorded-connections overview.

• --kinds: optional edge kind filter; repeat the flag or comma-separate values.
• --facet: optional facet filter.
• --day-from, --day-to: optional evidence day bounds.
• --limit: maximum connected entities to show.
• --json: return the raw route payload.

Behavior notes:

• Use this before network when you need to know which entities are most connected.
• Ranking counts only evidence dated up to today; each item carries an evidence_class of attendance, semantic, or mixed.
• The header reports total entities and whether the displayed list is truncated.

Example:

sol call entities overview --facet work --limit 20

merge

sol call entities merge SOURCE_SLUG TARGET_SLUG [--commit/--no-commit] [--keep-source-as-aka/--no-keep-source-as-aka]

Plan or execute a merge of two journal entities (e.g., collapse duplicate records after review).

• SOURCE_SLUG: entity slug to merge from (removed on --commit).
• TARGET_SLUG: entity slug to merge into (canonical).
• --commit/--no-commit: default --no-commit. Returns a JSON plan with no mutations. Pass --commit to persist.
• --keep-source-as-aka/--no-keep-source-as-aka: default --keep-source-as-aka. Preserve the source display name as an alias on the target.

Behavior notes:

• Observations and aliases from source are merged into target with deduplication.
• If any other entity references SOURCE_SLUG in its alias list, the merge is rejected and the offenders are listed.
• If both entities have principals assigned, the merge is rejected.

Examples:

sol call entities merge jeremy-miller jeremie-miller
sol call entities merge jeremy-miller jeremie-miller --commit

undo-merge

sol call entities undo-merge MERGE_ID --yes [--json]

Deterministically undo one recorded merge. Use the merge_id returned by a successful merge or accepted merge suggestion. This restores the recorded source entity and its owned references without rolling back unrelated later target changes. --yes is required.

ambiguities and resolve-ambiguity

sol call entities ambiguities [--status open|resolved] [--json]
sol call entities resolve-ambiguity AMBIGUITY_ID ENTITY_ID --yes [--json]

List persisted low-confidence entity questions and choose an existing scoped entity. The list includes candidates and origin lanes. A recorded choice sticks for later mutation runs. Never resolve to a blocked, missing, or out-of-scope entity. resolve-ambiguity requires --yes.

entity-history and restore-version

sol call entities entity-history ENTITY_ID [--json]
sol call entities restore-version ENTITY_ID VERSION_ID --yes [--json]

entity-history shows durable identity versions (create, update, restore, merge, merge undo). This is distinct from history, which shows relationship evidence between two entities. Restore only ordinary identity versions; merge-bearing history must use undo-merge. restore-version requires --yes.

Gotchas

• merge previews by default. Default is --no-commit: it emits a JSON plan without mutating anything. Pass --commit when you actually want the merge to happen.
• history and entity-history are different. history reads relationship evidence; entity-history reads restorable identity versions.
• Undo and restore require explicit confirmation. Pass --yes; the commands make no request without it.
• detect requires TYPE ≥ 3 chars. Shorter types are silently rejected.
• observe is for durable traits, detect is for day-scoped sightings. Mixing them skews future entity context.