link

Create relations between resources

Overview

The link() method creates directional relations between resources, enabling you to build a knowledge graph of connected contexts. Relations help organize information and improve retrieval.

Relations are directional: linking A → B does not automatically create B → A.

Method Signature

Python SDK

def link(
    from_uri: str,
    uris: str | List[str],
    reason: str = ""
) -> None

Parameters

from_uri · string · required

Source URI to link from

uris · string | List[string] · required

Target URI(s) to link to. Can be a single string or list of URIs.

reason · string · default: ""

Human-readable explanation of why resources are related

Examples

Link Single Resource

Python SDK

from openviking import OpenViking

client = OpenViking(path="./data")

# Link code file to its documentation
client.link(
    from_uri="viking://resources/code/auth.py",
    uris="viking://resources/docs/authentication.md",
    reason="Implementation documentation for auth module"
)

Link Multiple Resources

# Link documentation to multiple examples
client.link(
    from_uri="viking://resources/docs/quickstart.md",
    uris=[
        "viking://resources/examples/basic.py",
        "viking://resources/examples/advanced.py",
        "viking://resources/examples/async.py"
    ],
    reason="Example code referenced in quickstart"
)

Build Knowledge Graph

# Create a network of related concepts
concepts = {
    "viking://agent/memories/concepts/rag": [
        "viking://resources/papers/rag-survey.pdf",
        "viking://resources/code/retriever.py"
    ],
    "viking://agent/memories/concepts/llm": [
        "viking://resources/papers/transformers.pdf",
        "viking://resources/docs/model-config.md"
    ]
}

for concept_uri, related_uris in concepts.items():
    client.link(
        from_uri=concept_uri,
        uris=related_uris,
        reason="Related reading and implementation"
    )

Link Documentation Chain

# Create navigation path through documentation
docs = [
    "viking://resources/docs/introduction.md",
    "viking://resources/docs/quickstart.md",
    "viking://resources/docs/advanced.md"
]

# Link each doc to the next
for i in range(len(docs) - 1):
    client.link(
        from_uri=docs[i],
        uris=docs[i + 1],
        reason="Next in documentation sequence"
    )

Response

{
  "status": "ok",
  "time": 0.003
}

Use Cases

1. Code-to-Docs Mapping - Link implementation files to their documentation
2. Citation Networks - Connect papers, articles, and references
3. Example Organization - Link tutorials to their example code
4. Concept Graphs - Build semantic networks between ideas
5. Navigation Hints - Create “see also” or “related” connections

Best Practices

Use descriptive reasons to make relations self-documenting and easier to understand.

# Good: Descriptive reason
client.link(
    from_uri="viking://resources/code/database.py",
    uris="viking://resources/docs/data-model.md",
    reason="Schema definitions and usage examples"
)

# Less useful: Generic reason
client.link(
    from_uri="viking://resources/code/database.py",
    uris="viking://resources/docs/data-model.md",
    reason="related"
)

Notes

• Relations are directional: A → B ≠ B → A
• Relations are stored persistently in the context database
• Relations improve retrieval: related resources can be discovered during semantic search
• Use relations() to query existing links
• Use unlink() to remove relations

Related Methods

• relations() - Query relations for a URI
• unlink() - Remove relations
• find() - Semantic search uses relations for context