/map-connections

name: map-connections
description: "Scan context files to extract entities and relationships into the memory system. Triggers on \"who knows who?\", \"network graph\", \"map my connections\", \"extract relationships\". See also: `brain` for graph visualization once relationships are extracted."
argument-hint: "[--incremental] [file-path]"
effort-level: high

Map Connections

Scan context files to extract entities, relationships, and build a connection graph. This command populates the memory system with structured relationship data from markdown files.

Usage

• `/map-connections` -- Full scan of people/, projects/, context/
• `/map-connections --incremental` -- Only scan files modified since last run
• `/map-connections [file-path]` -- Scan a specific file

Trigger Words

Use this command when the user says:

• "map my connections", "build my network", "scan for relationships"
• "analyze my people files", "who knows who"
• "populate the graph", "extract entities from files"

Workflow

1. Gather Files

Scan these directories for markdown files:

• `people/` - Relationship files
• `projects/` - Project documentation
• `context/` - User context files

For incremental mode, check file modification times against the last run timestamp (stored in `context/.map-connections-last-run`).

Read each .md file in people/, projects/, context/
Track: filename, content, modification time

2. Extract Entities from Each File

For each file, extract:

**Entity Name:** From filename or first heading

• `people/sarah-chen.md` -> "Sarah Chen" (type: person)
• `projects/website-redesign.md` -> "Website Redesign" (type: project)
• First `# Heading` in file overrides filename-based name

**Mentioned Entities:** Scan file content for:

• **People patterns:** Names in "works with [Name]", "client of [Name]", mentions of capitalized names
• **Organizations:** Company names, "works at [Org]", "employed by [Org]"
• **Projects:** "working on [Project]", project file references

**Attributes (Phase 2):** Look for structured data:

• **Geography:** "based in [City]", "from [City]", city/state mentions
• **Role:** "CEO of", "founder of", titles in file
• **Industry:** Keywords like "real estate", "finance", "tech"
• **Communities:** "member of [Group]", known groups (YPO, EO)

3. Extract Relationships

Identify explicit and implicit relationships. For each relationship, set `origin_type` honestly based on how you know it. The system automatically caps strength based on origin, so always use `strength: 1.0` and let the guards enforce the ceiling.

**Extracted Relationships** (origin_type: "extracted", ceiling: 0.8) Explicitly stated in the file:

• "works with [Name]" -> `works_with`
• "client of [Name]" -> `client_of`
• "reports to [Name]" -> `reports_to`
• "invested in [Project]" -> `invested_in`
• "manages [Name]" -> `manages`
• "partner at [Org]" -> `partner_at`
• "advisor to [Name/Org]" -> `advisor_to`

**Inferred Relationships** (origin_type: "inferred", ceiling: 0.5) Co-mentioned or contextually implied:

• Two people mentioned in the same file -> `mentioned_with`
• People in the same project file -> `collaborates_on`
• Same city + same industry -> `likely_connected`
• Same organization -> `colleagues`
• Same community group -> `community_connection`

4. Deduplicate and Resolve

Before creating entities: 1. Normalize names to canonical form (lowercase, no titles) 2. Check if entity already exists in memory via `claudia memory entities search --project-dir "$PWD"` 3. Merge new information with existing entity data 4. Track which entities are new vs updated

5. Store in Memory

Use `claudia memory batch` for efficiency:

claudia memory batch --project-dir "$PWD" <<'EOF'
[
  {"op": "entity", "name": "Sarah Chen", "type": "person", "description": "CEO at Acme Corp"},
  {"op": "entity", "name": "Acme Corp", "type": "organization"},
  {"op": "relate", "source": "Sarah Chen", "target": "Acme Corp", "relationship": "works_at", "strength": 1.0, "origin_type": "extracted"},
  {"op": "relate", "source": "Sarah Chen", "target": "Tom Miller", "relationship": "works_with", "strength": 1.0, "origin_type": "inferred"}
]
EOF

For relationship `origin_type`:

• Explicitly stated in the file ("Sarah is CEO of Acme"): `origin_type: "extracted"`
• Co-mentioned or contextually implied: `origin_type: "inferred"`
• User told you directly: `origin_type: "user_stated"`

The system automatically caps strength based on origin. You don't need to manually calibrate. Just be honest about how you know, and always use `strength: 1.0`.

When re-encountering existing relationships, the system strengthens them incrementally (scaled by origin). Repeated evidence builds trust organically.

6. Report Results

Output format:

## Connection Map Results

**Scan completed:** [timestamp]
**Files processed:** [count]

### New Entities ([count])

| Name | Type | Source |
|------|------|--------|
| Sarah Chen | person | people/sarah-chen.md |
| Acme Corp | organization | people/sarah-chen.md |
| Website Redesign | project | projects/website-redesign.md |

### New Relationships ([count])

| Source | Relationship | Target | Origin |
|--------|--------------|--------|--------|
| Sarah Chen | works_at | Acme Corp | extracted |
| Sarah Chen | collaborates_on | Website Redesign | extracted |
| Sarah Chen | mentioned_with | Tom Miller | inferred |

### Inferred Connections ([count])

| Entity A | Entity B | Reason | Origin |
|----------|----------|--------|--------|
| Sarah Chen | Jane Doe | Same city (Palm Beach) + industry (real estate) | inferred |

### Updated Relationships ([count])

| Relationship | Change |
|--------------|--------|
| Sarah Chen -> client_of -> Beta Inc | strengthened (re-encountered, extracted) |

### Summary

- **People:** [count] total ([new] new)
- **Organizations:** [count] total ([new] new)
- **Projects:** [count] total ([new] new)
- **Relationships:** [count] total ([new