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. Node types depend on the node's meaning level:

IDENTITY Layer — The 4 Paradigm Types

When meaning_level is IDENTITY, nodes must use one of four semantic types:

• 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

DATA / CONTEXT Layers — Free-Text Types

When meaning_level is DATA or CONTEXT, nodes accept any free-text node_type string. This allows flexible data modeling for non-identity data:

• document, note, recipe, meeting_notes, log, bookmark, transcript, etc.
• You can also use the 4 Paradigm types at DATA/CONTEXT level (e.g., a DATA-level EXPERIENCE)

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	string	IDENTITY layer: EXPERIENCE, BELIEF, ENTITY, or GOAL. DATA/CONTEXT layers: any string
meaning_level	enum	DATA, CONTEXT, or IDENTITY (defaults to CONTEXT if omitted)
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

Free-Text Node Types (DATA/CONTEXT)

For DATA and CONTEXT layers, you can use any string as node_type. This is useful for:

• Import pipelines: document, transcript, log, csv_row
• App-specific data: recipe, bookmark, meeting_notes, habit_entry
• AI agent outputs: extraction_result, summary, analysis

# DATA-layer node with free-text type
node = client.nodes.create(
    title="Weekly Team Standup Notes",
    node_type="meeting_notes",        # Any string for DATA/CONTEXT
    meaning_level="DATA",
    graph_view="identity",
    tags=["work", "meetings"]
)

# Later, if this becomes identity-significant, elevate it
client.nodes.update(
    node_id=node['id'],
    node_type="EXPERIENCE",           # Must use Paradigm type for IDENTITY
    meaning_level="IDENTITY",
    metadata={
        "properties": {
            "significance": "This meeting changed the direction of the project"
        }
    }
)

When to use free-text vs Paradigm types

• IDENTITY nodes: Always use EXPERIENCE, BELIEF, ENTITY, or GOAL
• DATA/CONTEXT nodes: Use whatever type makes sense for your app's data model
• If you're unsure, start with a descriptive free-text type at DATA/CONTEXT level, then promote to a Paradigm type when elevating to IDENTITY

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