Supported File Formats for Ingestion in Semantica: Markdown and Plain-Text Only

Semantica officially supports only Markdown (.md) and plain-text (.txt) files for ingestion, routing both through a unified Markdown parsing pipeline to generate graph entities.

The semantica-agi/semantica repository implements a lightweight ingestion system designed specifically for text-based knowledge sources. When considering supported file formats for ingestion in Semantica, developers should note that the platform intentionally limits input to Markdown and plain-text files, with all content ultimately processed through the same rendering pipeline regardless of extension.

How Semantica Handles File Ingestion

The ingestion system relies on a format hint mechanism that checks for an optional format property when files are loaded. If no hint is provided, Semantica defaults to treating content as Markdown. This design choice ensures backward compatibility while maintaining a simple architecture focused on text-based knowledge representation.

According to the source code, the system explicitly does not implement parsers for structured data formats. Files dropped via the UI or loaded through the API undergo immediate text extraction, with the nodeMarkdownSync engine handling all downstream processing.

Core Ingestion Files and Architecture

Two critical files define the ingestion behavior:

• explorer/src/workspaces/VocabularyWorkspace/types.ts — Declares the TypeScript interfaces including the optional format field that signals which parser to invoke.
• explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts — Contains the core synchronization logic that parses file content as Markdown and generates the corresponding graph nodes.

These files work in concert to ensure that only text-based formats are accepted into the knowledge graph.

Vocabulary Workspace Types

In explorer/src/workspaces/VocabularyWorkspace/types.ts, the interface definitions include an optional format property. This field accepts string values such as "md" or "txt", acting as a discriminator for the ingestion pipeline. When specified, it overrides automatic format detection; when omitted, the system falls back to Markdown parsing.

Node Markdown Sync Engine

The nodeMarkdownSync.ts file implements the actual ingestion logic. This module reads file content, processes it through the Markdown renderer, and maps the resulting structure to graph entities. Notably, this same pipeline handles both .md and .txt files—plain-text files simply pass through without special markup while maintaining identical downstream processing.

Loading Files via the API

Developers interact with the ingestion system through the loadGraphFromFile function exported from @semantica/explorer. This asynchronous function accepts a configuration object containing the file path and optional format specification.

Loading Markdown Files

To explicitly load a Markdown file, supply the format property:

import { loadGraphFromFile } from '@semantica/explorer';

await loadGraphFromFile({
  path: '/path/to/knowledge.md',
  format: 'md',               // explicit format hint
});

Loading Plain-Text Files

Plain-text files require no format specification, though they undergo identical processing:

import { loadGraphFromFile } from '@semantica/explorer';

await loadGraphFromFile({
  path: '/path/to/notes.txt', // .txt extension accepted
  // no format needed – defaults to Markdown parsing
});

Both examples route through nodeMarkdownSync.ts, demonstrating how Semantica unifies text ingestion regardless of the original file extension.

Unsupported Formats and Limitations

Semantica explicitly excludes binary and structured data formats from its ingestion stack. Attempting to load JSON, CSV, XML, or other non-text formats results in the system interpreting them as raw plain text. This parsing strategy does not produce structured graph data from these formats, effectively limiting their utility within the Semantica environment.

The architecture intentionally avoids format-specific parsers beyond the Markdown renderer, keeping the codebase lightweight and focused on textual knowledge representation.

Summary

• Semantica supports only Markdown (.md) and plain-text (.txt) files for ingestion.
• The ingestion pipeline defaults to Markdown parsing when no format hint is provided.
• explorer/src/workspaces/VocabularyWorkspace/types.ts defines the optional format field interface.
• explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts implements the core parsing and graph generation logic.
• Structured formats like JSON and CSV are not supported and will be treated as unstructured text.

Frequently Asked Questions

Can Semantica ingest JSON or CSV files?

No. According to the semantica-agi/semantica source code, JSON and CSV files are not part of the ingestion stack. If loaded, these files will be interpreted as plain text without producing structured graph data, as the system lacks dedicated parsers for tabular or structured JSON formats.

How does Semantica determine which parser to use?

Semantica checks for an optional format property in the load configuration, as defined in explorer/src/workspaces/VocabularyWorkspace/types.ts. If this hint is absent, the system automatically falls back to the Markdown parser implemented in explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts, treating all input as Markdown-compatible text.

Is there a difference between loading .md and .txt files?

Functionally, no. Both file extensions route through the same nodeMarkdownSync pipeline. Markdown files receive full markup parsing, while plain-text files are treated as Markdown without special formatting. Both generate identical graph entity structures within the Semantica visualization workspace.

What function is used to load files programmatically?

Use the loadGraphFromFile function imported from @semantica/explorer. This async function accepts a path and optional format parameter, ultimately invoking the nodeMarkdownSync logic to process the file and populate the knowledge graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}