Technical Specification: Decentralized Semantic Knowledge Graph for Repositories

Abstract

This specification defines a decentralized architecture for semantic code intelligence using RDF knowledge graphs, versioned in git repositories, and queryable via SPARQL. The system enables autonomous repository discovery, semantic matching, and inter-repository communication while maintaining privacy and data sovereignty.

Motivation

Existing code intelligence systems are centralized (GitHub Copilot, Sourcegraph), proprietary, and lack semantic understanding. The Semantic Web vision failed for human-centric applications but becomes practical when AI agents are the primary consumers of structured data.

Key Problems Solved

Semantic Code Search: Find code by meaning, not string matching
Cross-Repository Discovery: Identify related projects via semantic similarity
Automated Dependency Analysis: Semantic diff between API versions
Privacy-Preserving Collaboration: Share knowledge without exposing source
Decentralized Intelligence: No central platform required

Architecture Overview

Components

Local Knowledge Graph (Oxigraph)
- RDF triple store containing repository semantics
- Generated from code analysis (AST, entities, metrics)
- Stored as versioned n-triples in repository
Entity Extraction Pipeline (GLiNER2)
- Extracts entities from code, comments, documentation
- Entity types: Person, Organization, Topic, DefinedTerm, Activity
- Generates confidence scores and provenance metadata
Graph Server (Oxigraph HTTP)
- SPARQL endpoint for querying knowledge graphs
- Aggregates graphs from multiple repositories
- Supports both local (personal) and server (community) deployment
MCP Interface (Model Context Protocol)
- Tool-based API for AI agents
- Operations: post, query, list, update
- Enables Claude, GPT, and other LLMs to interact natively
GitHub Integration
- GitHub App or Action for automated processing
- Watches repository pushes
- Generates/updates n-triples files
- Posts to graph server

Data Flow

Commit → GitHub Event → Entity Extraction → N-Triples Generation
                              ↓
                         Commit .nt file
                              ↓
                    Push to Graph Server
                              ↓
                      SPARQL Queryable

RDF Schema

Namespaces

slop: - https://slop.at/ontology#
know: - https://know.dev/
schema: - https://schema.org/
nfo: - http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#
dcterms: - http://purl.org/dc/terms/

Core Entities

File Metadata

<https://github.com/user/repo/blob/main/file.py>
  a nfo:FileDataObject, slop:Slop ;
  nfo:fileName "file.py" ;
  dcterms:title "Module Title" ;
  dcterms:creator "username" ;
  dcterms:created "2026-01-17T12:00:00Z" ;
  slop:slopId "a1c09e7b" .

Entity

<https://slop.at/entity/{hash}/{name}>
  a know:DefinedTerm ;
  schema:name "FastAPI" ;
  slop:confidence "0.95"^^xsd:float ;
  slop:lineStart "42"^^xsd:integer ;
  slop:lineEnd "42"^^xsd:integer .

Mention Relationship

<https://github.com/user/repo/blob/main/file.py>
  slop:mentions <https://slop.at/entity/{hash}/fastapi> .

Named Graphs

Each file/document exists in its own named graph:

GRAPH <https://slop.at/graph/username/repo/fileid> {
  # All triples for this file
}

This enables:

Provenance tracking: Which file mentioned which entity
Co-occurrence analysis: Entities in same graph co-occur
Temporal queries: Graph creation timestamps
Access control: Graph-level permissions

Entity Co-Occurrence

Entities appearing in the same named graph are considered co-occurring. This enables semantic similarity matching:

# Find repositories that mention both "FastAPI" and "Oxigraph"
SELECT ?repo (COUNT(*) as ?mentions)
WHERE {
  GRAPH ?g {
    ?repo slop:mentions ?e1 ;
          slop:mentions ?e2 .
    ?e1 schema:name "FastAPI" .
    ?e2 schema:name "Oxigraph" .
  }
}
GROUP BY ?repo

Privacy Model

Three-Tier Architecture

Local Graph (private)
- Full knowledge graph on user's machine
- Contains all entities, relationships, source code references
- Never leaves local system
Shape Metadata (fuzzy, optional sync)
- Aggregated statistics: entity type distributions, top entities
- K-anonymity: only entities appearing in k+ repositories
- Differential privacy: noise added to rare entity counts
- Published to discovery server
Public Graph (opt-in)
- Explicitly shared triples (e.g., public API definitions)
- WebACL-controlled access
- Useful for open source collaboration

Example Shape Metadata

{
  "author": "goodlux",
  "entity_types": {
    "DefinedTerm": 42,
    "Activity": 18,
    "Topic": 12
  },
  "top_entities": ["Python", "FastAPI", "RDF"],
  "co_occurrence_patterns": [
    ["FastAPI", "Pydantic"],
    ["RDF", "SPARQL"]
  ]
}

GitHub Integration

Workflow: MCP Client

User writes markdown/code
MCP client calls post_slop()
GLiNER2 extracts entities locally
N-triples generated with provenance
Git commit includes:
- Original file
- Generated .nt file
Push to GitHub
Optional: POST to graph server

Workflow: Direct Git Commit

User commits markdown/code to GitHub
GitHub Action triggers on push
Action checks: does .nt file exist? Is it newer than source?
If stale/missing:
- Run entity extraction
- Generate n-triples
- Commit back to repo
POST to graph server

GitHub Action Configuration

name: Generate Semantic Graph
on:
  push:
    paths:
      - '**.md'
      - '**.py'
jobs:
  generate-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for stale n-triples
        run: |
          # Compare timestamps
      - name: Extract entities
        run: |
          # Run GLiNER2 pipeline
      - name: Generate RDF
        run: |
          # Build n-triples
      - name: Commit graph
        run: |
          git add *.nt
          git commit -m "Update knowledge graph"
      - name: Push to graph server
        run: |
          curl -X POST $GRAPH_SERVER/store \
            -H "Content-Type: application/n-triples" \
            --data-binary @graph.nt

Solid Pods Integration

Each repository can be associated with a Solid Pod providing:

WebID (Identity)

<https://repo.solid.example.com/profile/card#me>
  a foaf:Agent ;
  solid:oidcIssuer <https://solid.example.com> ;
  ldp:inbox <https://repo.solid.example.com/inbox/> ;
  solid:publicTypeIndex <https://repo.solid.example.com/settings/publicTypeIndex.ttl> .

Type Index (Capabilities)

<https://repo.solid.example.com/settings/publicTypeIndex.ttl>
  a solid:TypeIndex ;
  solid:forClass slop:SecurityAnalysis ;
  solid:instance <https://repo.solid.example.com/capabilities/security> .

LDN Inbox (Notifications)

Repositories can receive notifications:

POST /inbox/
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Announce",
  "actor": "https://other-repo.solid.example.com/profile/card#me",
  "object": "https://repo.solid.example.com/graph.nt",
  "summary": "Found breaking change in dependency API"
}

WebACL (Access Control)

<https://repo.solid.example.com/graph.nt.acl>
  a acl:Authorization ;
  acl:mode acl:Read ;
  acl:accessTo <https://repo.solid.example.com/graph.nt> ;
  acl:agentClass foaf:Agent .  # Public read
  
<https://repo.solid.example.com/private/internal.nt.acl>
  a acl:Authorization ;
  acl:mode acl:Read ;
  acl:accessTo <https://repo.solid.example.com/private/internal.nt> ;
  acl:agent <https://teammate.solid.example.com/profile/card#me> .  # Private

Use Cases

1. Semantic Code Search

# Find all Python projects using FastAPI and PostgreSQL
SELECT ?repo ?title
WHERE {
  GRAPH ?g {
    ?repo dcterms:title ?title ;
          slop:mentions ?fastapi, ?postgres .
    ?fastapi schema:name "FastAPI" .
    ?postgres schema:name "PostgreSQL" .
  }
}

2. Find Similar Projects

# Projects with similar entity profiles to mine
SELECT ?other_repo (COUNT(?shared_entity) as ?similarity)
WHERE {
  GRAPH <https://slop.at/graph/goodlux/myproject/main> {
    <https://github.com/goodlux/myproject> slop:mentions ?e1 .
  }
  GRAPH ?g {
    ?other_repo slop:mentions ?e2 .
    ?e1 schema:name ?name .
    ?e2 schema:name ?name .
    BIND(?e1 as ?shared_entity)
  }
  FILTER(?other_repo != <https://github.com/goodlux/myproject>)
}
GROUP BY ?other_repo
ORDER BY DESC(?similarity)

3. Dependency Breaking Change Detection

# Compare API surface between versions
SELECT ?removed_function
WHERE {
  GRAPH <https://slop.at/graph/lib/v1.0> {
    ?lib slop:mentions ?func .
    ?func a know:Function .
  }
  FILTER NOT EXISTS {
    GRAPH <https://slop.at/graph/lib/v2.0> {
      ?lib slop:mentions ?func2 .
      ?func schema:name ?name .
      ?func2 schema:name ?name .
    }
  }
  ?func schema:name ?removed_function .
}

4. Find Expertise

# Who writes about ontology gardening?
SELECT ?author (COUNT(DISTINCT ?g) as ?posts)
WHERE {
  GRAPH ?g {
    ?slop dcterms:creator ?author ;
          slop:mentions ?entity .
    ?entity schema:name "ontology gardening" .
  }
}
GROUP BY ?author
ORDER BY DESC(?posts)

Performance Considerations

Caching Strategy

Pre-compute co-occurrence matrices for top N entities
Materialize common queries as views
Store shape metadata separately from full graph
Update incrementally on new commits

Scaling

Partition by repository: Each repo graph independent
Federation: Multiple graph servers, query routing
Eventual consistency: Async graph updates acceptable
CDN for n-triples: Static files, globally distributed

Implementation Roadmap

Phase 1: Core Infrastructure

Entity extraction pipeline (GLiNER2)
RDF graph generation
Local Oxigraph storage
MCP interface
GitHub Action for auto-generation

Phase 2: Discovery & Matching

Graph server deployment
Shape metadata extraction
Semantic similarity queries
Privacy-preserving aggregation

Phase 3: Solid Pods Integration

WebID setup for repositories
Type Index for capabilities
LDN inbox for notifications
WebACL for access control
Repo-to-repo messaging

Phase 4: Advanced Features

Relationship extraction (beyond entity mentions)
Temporal analysis (topic evolution)
Visual knowledge graphs
Federated query across servers

Open Questions

Ontology Evolution: How to handle schema changes over time?
Entity Disambiguation: "Python" the language vs "Python" the snake?
Relationship Extraction: Beyond co-occurrence, extract semantic relationships?
Query Optimization: SPARQL performance at scale?
Standard Vocabularies: Extend know.dev or create new ontology?

References

Solid Specification: https://solidproject.org/TR/protocol
Linked Data Notifications: https://www.w3.org/TR/ldn/
WebACL: https://solidproject.org/TR/wac
RDF 1.1: https://www.w3.org/TR/rdf11-primer/
SPARQL 1.1: https://www.w3.org/TR/sparql11-query/
Model Context Protocol: https://modelcontextprotocol.io/

License

This specification is released under CC BY 4.0.

Authors

goodlux (https://github.com/goodlux)
spacegoatai (https://github.com/spacegoatai)

This is a living document. Feedback welcome via GitHub issues or Solid Pod inbox.