Nodes

Nodes are the fundamental unit of identity data in the Paradigm SDK. They represent compressed semantic structures of your experiences, beliefs, entities, and goals.

What is a Node?

In Paradigm, nodes follow a structured ontology for compressed narrative identity. Each node represents one of four fundamental types of information that constitute your identity:

• EXPERIENCE - Things that happened at specific points in time
• BELIEF - What you think is true (about yourself or the world)
• ENTITY - Who/what you connect to (people, places, practices, ideas)
• GOAL - What you're trying to achieve or become

Paradigm Node Structure

{
  "id": "223845bf-4397-4135-899f-c72f84289ca",
  "title": "First day teaching my own university class",
  "value": "This was the moment everything clicked...",
  "node_type": "EXPERIENCE",
  "meaning_level": "IDENTITY",
  "owner_id": "user_123",
  "graph_view": "identity",
  "importance_score": 0.98,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "properties": {
      "when": {
        "type": "instance",
        "status": "done",
        "start": "2020-09-15"
      },
      "where": "University lecture hall, room 304",
      "significance": "This was the moment I knew teaching was what I'm meant to do"
    }
  },
  "agent_metadata": {
    "agent_id": "0c59fea4-fe7e-41af-a246-e3eb1819be13",
    "agent_name": "Memory Extraction Agent v2.1",
    "agent_type": "experience_extractor",
    "confidence_score": 0.92,
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "last_modified_by_agent_id": "0c59fea4-fe7e-41af-a246-e3eb1819be13",
  "tags": ["formative", "career", "teaching"]
}

Core Node Fields

Field	Type	Description
id	UUID	Unique identifier
title	string	Primary description/content of the node
value	string	Additional notes or context (optional)
node_type	enum	EXPERIENCE, BELIEF, ENTITY, or GOAL
meaning_level	enum	DATA, CONTEXT, or IDENTITY
owner_id	UUID	User who owns this node
graph_view	string	identity (neutral deprecated)
importance_score	float	0.0 to 1.0 relevance score
metadata	object	Contains properties with type-specific fields
agent_metadata	object	Agent that last modified this node
last_modified_by_agent_id	UUID	Agent ID for traceability
created_at	datetime	Creation timestamp
updated_at	datetime	Last modification timestamp
tags	array	Associated tags

The Four Node Types

EXPERIENCE: Things That Happened

Decision Test: Can you answer "When did this happen?" If yes → EXPERIENCE

Properties (in metadata.properties):

{
  "when": {
    "type": "instance | series",     // Single event or recurring
    "status": "done | ongoing | future",
    "start": "2020-09-15",           // Date/timestamp
    "end": "2020-09-16"              // Optional
  },
  "where": "string",                 // Location (optional)
  "significance": "string"           // Why this matters (recommended for IDENTITY level)
}

Examples:

• "First day of college"
• "My father died when I was 12"
• "Started my company in 2020"
• "Had breakthrough in therapy"

BELIEF: What You Think Is True

Decision Test: Can you put "I believe..." or "I think..." in front of it? If yes → BELIEF

Properties (in metadata.properties):

{
  "category": "about_self | about_world",  // Optional
  "strength_of_belief": 8,                 // 1-10 scale (optional)
  "status": "active | outdated"            // Optional
}

Examples:

• "I am introverted" (about_self)
• "Education changes lives" (about_world)
• "I procrastinate when anxious" (pattern, about_self)
• "Systems thinking explains most phenomena" (framework, about_world)

ENTITY: Who/What You Connect To

Decision Test: Can you answer "Who/what is this?" and point to something outside yourself? If yes → ENTITY

Properties (in metadata.properties):

{
  "name": "string",                        // Required
  "category": "person | place | idea | practice | community | organization"  // Required
}

Examples:

• "Dr. Sarah Chen" (person - my PhD advisor)
• "Teaching" (practice - my vocation)
• "Bay Area" (place - where I live)
• "Stoic philosophy" (idea - framework guiding my life)

Note: Relationships to entities are created via relationship connections, not stored directly in the node.

GOAL: What You're Trying to Achieve

Decision Test: Am I working toward this? Have I achieved this yet? If yes → GOAL

Properties (in metadata.properties):

{
  "motivation": "string",                  // Why this matters (optional)
  "time_horizon": "immediate | short_term | long_term | lifelong",  // Optional
  "status": "active | paused | achieved | abandoned"  // Optional
}

Time horizons:

• immediate: This week/month
• short_term: This year
• long_term: 2-5 years
• lifelong: Ongoing aspiration

Examples:

• "Build an educational platform for underserved communities"
• "Be fully present for my kids during their childhood"
• "Overcome my social anxiety"

The Three Meaning Levels

Meaning levels represent narrative depth - how central this information is to your compressed identity story.

The Compression Test

Imagine someone asks "Who are you?" with different time constraints:

• 30 seconds → You mention only IDENTITY level nodes
• 5 minutes → You include IDENTITY + key CONTEXT
• 30 minutes → You include everything (+ DATA)

DATA: Just a Fact

Test: Is this just a fact with no story significance?

Examples:

• "I am 5'10" tall" (unless height significantly affected your life)
• "My blood type is O negative"
• "I bought groceries yesterday"

CONTEXT: Useful Background

Test: Would you mention this in 5 minutes but not in 30 seconds?

Examples:

• "Lived in Seattle for two years" (true but not defining)
• "Went to a teaching conference last month" (might become formative, not yet)
• "I prefer morning workouts" (preference but not deep)

IDENTITY: Story-Constitutive

Test: Would you mention this in 30 seconds of "Who are you?"

Examples:

• "My father died when I was 12" (shaped who you became)
• "I have ADHD that affects everything I do"
• "Teaching is my calling - it's who I am"
• "Build an educational platform" (life mission)

Key Insight: IDENTITY nodes are those you can't explain yourself without. Remove them and you're not you anymore.

Agent Metadata & Traceability

Paradigm supports multi-agent collaboration with full traceability. Each node tracks which agents contributed to it.

Agent Metadata Structure

{
  "agent_id": "uuid",
  "agent_name": "Memory Extraction Agent v2.1",
  "agent_type": "experience_extractor",
  "agent_version": "2.1.0",
  "processing_time_ms": 1850,
  "confidence_score": 0.92,
  "source_models": ["gpt-4", "claude-3-sonnet"],
  "extraction_method": "narrative_analysis",
  "validation_status": "verified",
  "timestamp": "2024-01-15T10:30:00Z",
  "session_id": "sess_exp_1234567890",
  "contribution_details": {
    "fields_extracted": ["when", "where", "significance"],
    "verification_passed": true,
    "quality_score": 0.92
  }
}

Node Ledger

Track all agents that have contributed to a node over time:

# Get ledger showing all agent contributions
ledger = client.nodes.get_ledger(node_id="node_abc")

# Returns:
{
  "node_id": "node_abc",
  "total_agents": 3,
  "agents": [
    {
      "agent_id": "agent_1",
      "agent_name": "Memory Extraction Agent v2.1",
      "agent_type": "experience_extractor",
      "contribution_count": 1,
      "last_contribution": "2024-01-15T10:30:00Z"
    },
    {
      "agent_id": "agent_2",
      "agent_name": "Content Enhancement Agent v2.5",
      "agent_type": "content_enhancer",
      "contribution_count": 2,
      "last_contribution": "2024-01-16T14:20:00Z"
    }
  ]
}

Working with Nodes

Create a Node

node = client.nodes.create(
    title="First day teaching my own class",
    value="This was the moment everything clicked...",
    node_type="EXPERIENCE",
    meaning_level="IDENTITY",
    graph_view="identity",
    importance_score=0.98,
    metadata={
        "properties": {
            "when": {
                "type": "instance",
                "status": "done",
                "start": "2020-09-15"
            },
            "where": "University lecture hall",
            "significance": "Moment I knew teaching was my calling"
        }
    },
    agent_metadata={
        "agent_id": "agent_001",
        "agent_name": "Memory Extraction Agent",
        "confidence_score": 0.92
    },
    last_modified_by_agent_id="agent_001",
    tags=["formative", "career"]
)

List Nodes with Filters

# Filter by type
experiences = client.nodes.list(node_type="EXPERIENCE")

# Filter by meaning level
identity_nodes = client.nodes.list(meaning_level="IDENTITY")

# Combined filters
core_beliefs = client.nodes.list(
    node_type="BELIEF",
    meaning_level="IDENTITY"
)

# With pagination
page1 = client.nodes.list(page=1, per_page=50)

Get Node with Full Metadata

node = client.nodes.get(node_id="node_abc")

# Access type-specific properties
if node['node_type'] == 'EXPERIENCE':
    when = node['metadata']['properties']['when']
    print(f"Happened: {when['start']}")
    print(f"Significance: {node['metadata']['properties']['significance']}")

# Check agent information
print(f"Last modified by: {node['agent_metadata']['agent_name']}")
print(f"Confidence: {node['agent_metadata']['confidence_score']}")

Update Node (Multi-Agent)

# Update with different agent
updated = client.nodes.update(
    node_id="node_abc",
    value="Enhanced description with additional context...",
    agent_metadata={
        "agent_id": "agent_002",
        "agent_name": "Content Enhancement Agent",
        "agent_type": "content_enhancer",
        "confidence_score": 0.88
    },
    last_modified_by_agent_id="agent_002"
)

# This creates a new history entry with the new agent

Get Node History

# Get complete version history
history = client.nodes.get_history(node_id="node_abc")

for entry in history['items']:
    print(f"{entry['version']}: {entry['change_type']}")
    print(f"  Changed by: {entry['changed_by_type']}")
    if entry['agent_metadata']:
        print(f"  Agent: {entry['agent_metadata']['agent_name']}")

Get Node Ledger

# See all agents that contributed
ledger = client.nodes.get_ledger(node_id="node_abc")

print(f"Total agents: {ledger['total_agents']}")
for agent in ledger['agents']:
    print(f"- {agent['agent_name']}: {agent['contribution_count']} edits")

Decision Framework

Choosing Node Type

Ask yourself:

1. "When did this happen?" → EXPERIENCE
2. "Can I say 'I believe...'?" → BELIEF
3. "Is this someone/something external?" → ENTITY
4. "Am I trying to achieve this?" → GOAL

Choosing Meaning Level

Ask yourself:

1. "Would I skip this when explaining who I am?" → DATA
2. "Would I mention in 5 minutes but not 30 seconds?" → CONTEXT
3. "Can I explain myself without this?" → If no: IDENTITY

Common Patterns

Experience → Belief → Goal Chain

# Formative experience
exp = client.nodes.create(
    title="First day teaching - realized my calling",
    node_type="EXPERIENCE",
    meaning_level="IDENTITY"
)

# Shaped a belief
belief = client.nodes.create(
    title="Education expands possible futures",
    node_type="BELIEF",
    meaning_level="IDENTITY"
)

# Which supports a goal
goal = client.nodes.create(
    title="Build educational platform for underserved communities",
    node_type="GOAL",
    meaning_level="IDENTITY"
)

# Connect them with relationships
client.relationships.create(
    from_node=exp['id'],
    to_node=belief['id'],
    relationship_type="shaped"
)

client.relationships.create(
    from_node=belief['id'],
    to_node=goal['id'],
    relationship_type="supports"
)

Elevating Significance

# Start as CONTEXT
node = client.nodes.create(
    title="Went to teaching conference",
    node_type="EXPERIENCE",
    meaning_level="CONTEXT"
)

# Later realized it was formative - elevate to IDENTITY
client.nodes.update(
    node_id=node['id'],
    meaning_level="IDENTITY",
    metadata={
        "properties": {
            "significance": "Had breakthrough insight that changed my teaching approach"
        }
    }
)

Best Practices

1. Use the Decision Tests

Don't guess at node types - follow the decision framework:

• EXPERIENCE: "Did this happen at a specific time?"
• BELIEF: "Can I put 'I believe...' in front?"
• ENTITY: "Can I point to something external?"
• GOAL: "Am I working toward this?"

2. Start with CONTEXT, Elevate to IDENTITY

When unsure about meaning level, start with CONTEXT. You can always promote later when significance becomes clear.

3. Include Significance for IDENTITY Experiences

For formative experiences, always explain why they matter:

# Good - explains significance
{
  "title": "First day teaching",
  "significance": "Moment I knew this was my calling, not just a job"
}

# Incomplete - what made this formative?
{
  "title": "First day teaching"
}

4. Track Agent Contributions

Always include agent metadata for traceability:

{
  "agent_metadata": {
    "agent_id": "agent_001",
    "agent_name": "Memory Extraction Agent",
    "confidence_score": 0.92,
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "last_modified_by_agent_id": "agent_001"
}

5. Use Type-Specific Properties

Each node type has recommended properties - use them:

• EXPERIENCE: Always include when, add significance for IDENTITY level
• BELIEF: Consider adding category and strength_of_belief
• ENTITY: Always include name and category
• GOAL: Include motivation and time_horizon

Migration from Legacy Node Types

If you have legacy nodes with types like note, document, memory:

Mapping Legacy Types

Legacy Type	Paradigm Type	Guidance
note	EXPERIENCE or BELIEF	Did it happen (EXPERIENCE) or is it what you think (BELIEF)?
document	Varies	Depends on content - could be any type
memory	EXPERIENCE	Memories are things that happened
task	GOAL	Tasks are goals (things to achieve)
entity	ENTITY	Direct mapping if person/place/thing

Migration Script Pattern

# Get legacy nodes
legacy_nodes = client.nodes.list(node_type="memory")

for node in legacy_nodes:
    # Analyze content to determine new type
    if is_past_event(node):
        new_type = "EXPERIENCE"
        properties = extract_when_where(node)
    elif is_belief_statement(node):
        new_type = "BELIEF"
        properties = extract_belief_properties(node)
    
    # Update to Paradigm structure
    client.nodes.update(
        node_id=node['id'],
        node_type=new_type,
        meaning_level=determine_meaning_level(node),
        metadata={"properties": properties}
)

Next Steps

• Relationships - Connect nodes with causal/support/conflict relationships
• Tags - Organize nodes thematically
• Agent Infrastructure - Learn about multi-agent collaboration
• History & Auditing - Track changes over time