Ontofelia

The AI agent gateway with a semantic soul.

An open-source, self-hosted agent gateway that gives your AI a persistent identity, structured long-term memory powered by OWL ontologies, and secure multi-channel communication.

Getting Started · Architecture · Documentation · Contributing

---

⚠️ v0.0.1 — early research preview

Ontofelia is an active research project in neuro-symbolic AI: it studies whether coupling an LLM with an OWL reasoner and a governed RDF knowledge graph yields a more reliable agent than an LLM with conventional string/vector memory. It is under heavy development and not production-ready — APIs, behaviour, and results will change.

Built by AI — a "vibe coding" experiment. Ontofelia was implemented end-to-end with AI coding agents — Claude Code, Codex, and Gemini — under human direction. It is as much an experiment in AI-assisted, vibe-coded development as it is a neuro-symbolic AI study. Expect the rough edges, inconsistencies, and AI-generated artifacts that come with that.

On competitor comparisons — please read. We have not run a validated, controlled head-to-head against the real Hermes or OpenClaw products, and we make no claim to have beaten them. The evaluation below is against a fair RAG baseline inside our own harness (a research proxy for string/vector memory) — not the shipped competitor binaries. An exploratory real-agent run we attempted surfaced harness and scoring problems (and a bug in our own forgetting path, since fixed), so it is not a published result. Treat every number here as preliminary research, not a verdict.

---

Why Ontofelia?

Most AI agents are stateless parrots — they forget everything between sessions, can't reason about what they know, and store context as opaque embeddings. Ontofelia is different.

Feature	Typical Agent	Ontofelia
Memory	Vector embeddings / flat text	RDF triples + OWL ontology
Reasoning	None	OWL inference (via Oxigraph + Reasonable)
Knowledge query	Fuzzy similarity search	SPARQL 1.1 — precise, structured
Self-awareness	None	Ontology reflection — the agent can inspect and explain its own knowledge model
Channels	Single platform	Multi-channel — WebChat, Telegram, Discord, WebSocket nodes
Tools	Basic function calling	Governed execution — policy engine, Guardian approval, audit log
Extensibility	Hardcoded	Skills + Plugins — hot-loadable ESM modules

Ontofelia doesn't just remember — it understands.

The research question

Most agents — including OpenClaw and Hermes — store long-term memory as strings or vectors that don't reason. Ontofelia's research hypothesis is that a governed, reasoning knowledge graph can offer truth-maintenance a retrieval index cannot guarantee:

Hypothesis (under test): an agent whose memory reasons can forget completely when told to, and reliably flag contradictions — where a retrieval-augmented agent is unreliable.

This is a hypothesis we are testing, not a settled claim, and explicitly not a head-to-head result against the OpenClaw or Hermes products. On plain recall a good vector-RAG already matches us; the open question is the part a retrieval index structurally cannot offer — deletion you can trust, contradictions caught, and beliefs you can audit (memory_explain — "why do I believe this?").

📊 Evaluation — honest & reproducible

Scope: this is a controlled research benchmark against a RAG baseline — a fair, strong vector-RAG that stands in for the string/vector memory style of agents like OpenClaw and Hermes. It is not a benchmark of those products themselves. The harness swaps only the memory behind one LLM — Ontofelia's governed knowledge graph vs the RAG baseline vs no memory — across 3 models, scored H0–H6 with McNemar/Wilcoxon significance (Holm-corrected). Pilot run pilot-2026-06-25:

Capability	Ontofelia	fair vector-RAG	Verdict
Recall (H1)	0.99	1.00	tie — we don't claim a win
Multi-hop (H2)	1.00	0.94	~tie (not significant)
Forget on command (H6)	1.00 — 0% leak	0.54 — leaks the "forgotten" fact 31–62%	decisive win, every model (p<0.001)
Contradiction flagging (H3)	0.93	0.20	decisive win, every model (p<0.001)
Auditable provenance (H4)	0.89	0.64	win (pooled, p=0.014)
Constraint/consistency (H5)	1.00	0.89	modest

The two effects that held on every model tested were forgetting (H6) and contradiction detection (H3). This supports the hypothesis against a RAG baseline — it is not evidence about the OpenClaw or Hermes products, which we have not benchmarked. Pilot-scale, preliminary.

Run it yourself:

# offline, no API key — proves the harness end-to-end
pnpm --filter @ontofelia/eval build && pnpm --filter @ontofelia/eval test

# the real multi-model benchmark (needs an OpenRouter key)
export OPENROUTER_API_KEY=sk-or-...
EVAL_PROVIDER=openrouter EVAL_MODELS="deepseek/deepseek-v4-flash,openai/gpt-4o-mini,anthropic/claude-haiku-4.5" \
  EVAL_EMBEDDINGS_URL=https://openrouter.ai/api/v1 EVAL_EMBEDDINGS_KEY=$OPENROUTER_API_KEY \
  EVAL_EMBEDDINGS_MODEL=text-embedding-3-small EVAL_JUDGE=llm EVAL_JUDGE_MODEL=openai/gpt-4o-mini \
  node packages/eval/dist/pilot.js   # → packages/eval/out/pilot-<ts>.{json,md}

Status: pilot-scale (127 probes/model × 3 models, synthetic personas) — no human-adjudicated κ yet, and not a head-to-head against the shipped OpenClaw/Hermes binaries. We say "in our pilot evaluation," not "we proved." The reasoner's advantage is regime-specific (truth-maintenance and auditable, expensive errors), not universal.

✨ Features

🧠 Semantic Memory

• Store knowledge as RDF triples in a local embedded triplestore (Oxigraph)
• Store facts as real RDF triples (not reified meta-data) — entities become OWL individuals
• Build and evolve an OWL ontology (TBox) with automatic class/property extension
• KnowledgeEngine — entity resolution, property resolution, ABox insertion, provenance
• OWL 2 RL reasoning (Reasonable) — rule-based materialisation of inferred triples; not an OWL-DL reasoner and no full consistency check. A separate SPARQL check flags entities in two disjoint classes as conflict records
• SPARQL 1.1 queries for precise, structured knowledge retrieval
• Provenance tracking — every triple knows when/where/how it was learned

🤖 Agent Runtime

• Multi-provider LLM support — OpenRouter, OpenAI (API key + OAuth/ChatGPT Plus), Ollama (local), any OpenAI-compatible API
• Autonomous tool-calling loop with up to 100 rounds per conversation turn (autonomy budget)
• Token streaming — real-time token-by-token responses via WebSocket
• Intelligent LLM fallback — automatic retry with configurable backup models on empty responses
• User-configurable fallback order — set Fallback A/B models directly in the Settings UI
• Intelligent onboarding — Named Graph gap-detection drives step-by-step user profiling
• Context assembly from Named Graphs (user, identity, soul)
• Session persistence with JSONL transcripts + SQLite index

🧩 Cognitive Layer

• A per-message cognitive cycle on top of the knowledge graph: working memory, episodic memory with per-user recall, a goal stack, learned skills, metacognition and a queryable self-model, all stored as RDF in named graphs
• On by default for new installs; existing installs keep their current settings and opt in with the owner command /cog defaults apply (/cog defaults shows the difference first)
• Retention stays off. The retention sweep deletes old episode payloads, so it is never part of the defaults. The initiative flag (self-started work, which makes model calls of its own) stays off as well, and so does the preference consolidation (it writes a derived preference about a user into that user's graph, so the owner opts in on purpose)
• The default-on set adds no model call per message: it uses SPARQL and rules only
• The reasoning in the graph is OWL 2 RL materialisation (Reasonable), not an OWL-DL reasoner, and there is no consistency check
• Rollback: /cog flag <name> off turns one flag off, /cog cycle off turns the whole layer off, with no restart. Nothing is deleted by turning it off: episodes, goals, skills and the other records stay in the store and are read again when you switch back on. Only /cog cleanup, the retention sweep (if you enable it) or a factory reset removes them. The episodic graph holds the message text of every user and, while episodic memory is on, the button offers and presses of Telegram replies (choice-offered and choice-made episodes: the button values and labels, the offer reference and the user; Guardian approval buttons are never recorded)
• Upgrading: nothing changes for an existing install. /cog health (owner only) reports soak numbers: persist latency p50 and p95, graph sizes, the impasse rate and dumps per turn
• Details: Cognitive Architecture, flags, rollout and rollback in doc 09

🔧 Tools & Security

• 8 memory tools: memory_store, memory_query, memory_ask, memory_explain, memory_retract, memory_reflect, ontology_inspect, ontology_propose
• System tools: datetime, calculator, exec, fs_read, fs_write, fs_list, web_fetch, cron_manage
• Tool Policy Engine — role-based permissions, rate limiting, argument validation
• Guardian Policy — requires explicit owner approval via configured channels for dangerous tools when the sandbox is inactive
• Strict Auditing — every tool invocation is logged with context, and sensitive secrets are masked
• Sandboxing — Docker isolation for dangerous tools; insecure NoopSandbox is automatically blocked in production if dangerous tools are allowed

📡 Multi-Channel Communication

• WebChat UI — built-in React app with real-time WebSocket, Ontofelia owl avatar, model info per message
• Telegram and Discord adapters (with pairing & allowlist)
• WebSocket node protocol — connect IoT devices, desktop apps, headless nodes
• Webhooks — receive events from GitHub, CI/CD, external services
• Cron jobs — schedule recurring agent tasks

🔌 Extensibility

• Skills — prompt extensions with custom tool bundles (summarize, translate, explain)
• Plugins — ESM modules that extend gateway, tools, commands, and UI
• Media system — file upload, thumbnail generation, signed URL access

🚀 Getting Started

Prerequisites

The one-command installer below (install.sh / install.ps1) installs all of these for you automatically. You only need to set them up by hand for the manual install.

• Node.js 20+ (LTS) — download from nodejs.org
• pnpm v9+ — npm install -g pnpm or see pnpm.io
• C/C++ toolchain + Python 3 — native modules (better-sqlite3) compile from source when no prebuilt binary matches your Node version. On Debian/Ubuntu: sudo apt-get install build-essential python3. On macOS: Xcode Command Line Tools (xcode-select --install).
• Rust toolchain (cargo) — the @ontofelia/reasoner N-API addon is compiled from source (packages/reasoner/src/lib.rs) during pnpm build; its binary is not committed to the repo. Install via rustup.rs. The one-command installer below does this for you.

The default triplestore is Oxigraph, an embedded npm dependency — no Java and no separate server download are required.

Quick Start (one command)

The installer handles everything — Node.js, pnpm, build tools, dependencies, the build, the ontofelia CLI link, onboarding (gateway token + config), and starting the gateway.

Linux / macOS / WSL:

git clone https://github.com/semantification-org/Ontofelia.git
cd Ontofelia
bash install.sh

Windows (PowerShell):

git clone https://github.com/semantification-org/Ontofelia.git
cd Ontofelia
pwsh -ExecutionPolicy Bypass -File .\install.ps1

Then open http://127.0.0.1:18780 in your browser. That's it.

Try this first

Installed, gateway running — now make it show off. The examples/ directory has three copy-paste recipes (~2 minutes each) that demonstrate what the knowledge-graph memory actually does:

1. Why do you believe that? — teach the agent a fact, then trace it to its claim + evidence chain
2. Contradiction detected — contradict a fact and watch the old belief get superseded, not duplicated
3. Career history — the ontology decides: worksAt accumulates, livesIn replaces

Heads-up: the recipes need a real LLM provider (fact extraction runs through the LLM) — the mock provider from a non-interactive install won't produce triples. examples/README.md explains the one-minute setup.

Manual install (advanced)

If you already have Node.js 20+ and pnpm and prefer to run each step yourself:

git clone https://github.com/semantification-org/Ontofelia.git
cd Ontofelia
pnpm install
pnpm build

# In a fresh clone the CLI is not yet on your PATH — invoke it directly:
node apps/cli/dist/index.js onboard        # interactive setup (gateway token + config)
node apps/cli/dist/index.js gateway start

Tip: to use the short ontofelia <command> form everywhere, link the CLI globally once: pnpm --filter @ontofelia/cli link --global.

Configure an LLM Provider

The memory and reasoner layers work without an LLM key, but to use the chat/LLM path you must bring your own API key — or run a local model via Ollama (no key needed).

The onboard wizard writes your config to ~/.ontofelia/ontofelia.json5. You can also set the key via environment variable (see .env.example at the repo root) or edit the config directly:

nano ~/.ontofelia/ontofelia.json5

The provider section looks like this:

{
  // ... existing config ...
  provider: {
    name: "openrouter",
    apiKey: "sk-or-v1-YOUR-KEY",       // ← your key here
    defaultModel: "deepseek/deepseek-v4-flash:free",
    aliases: {
      fast: "deepseek/deepseek-v4-flash:free",
      smart: "google/gemma-4-26b-a4b-it:free"
    }
  }
}

The fastest way to get started is OpenRouter — it offers free-tier models so you can try Ontofelia without spending anything.

Prefer fully local? Pick Ollama in the wizard (name: "ollama", no API key, default baseUrl http://localhost:11434/v1). Note that small local models often struggle with the structured JSON the semantic memory pipeline needs — see LLM Providers for honest caveats.

Restart the gateway after changing the config.

Alternative: Use Your ChatGPT Plus Account

# Login with your OpenAI account (opens browser)
node apps/cli/dist/index.js auth login

This uses OAuth PKCE to authenticate with your ChatGPT Plus/Pro subscription — no API key needed.

🏗 Architecture

┌─────────────────────────────────────────────────────────┐
│                      Gateway                             │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────┐    │
│  │ Channels │  │  Agent   │  │  Semantic Memory   │    │
│  │          │  │ Runtime  │  │  ┌──────────────┐  │    │
│  │ WebChat  │  │          │  │  │ Oxigraph(RDF)│  │    │
│  │ Telegram │──│ Provider │──│  │ OWL Reasoner │  │    │
│  │ Discord  │  │ Tools    │  │  │ SPARQL 1.1   │  │    │
│  │ Webhook  │  │ Sessions │  │  └──────────────┘  │    │
│  │ Cron     │  │ Skills   │  │                    │    │
│  └──────────┘  └──────────┘  └────────────────────┘    │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────┐    │
│  │ Security │  │ Plugins  │  │  Media / Sandbox   │    │
│  │ Policies │  │ Registry │  │  Docker Isolation   │    │
│  └──────────┘  └──────────┘  └────────────────────┘    │
└─────────────────────────────────────────────────────────┘
         │              │               │
    ┌────┴────┐    ┌────┴────┐    ┌─────┴─────┐
    │   CLI   │    │ Web UI  │    │   Nodes   │
    │         │    │ (React) │    │ (WS/IoT)  │
    └─────────┘    └─────────┘    └───────────┘

Monorepo Structure

ontofelia/
├── apps/
│   ├── cli/                 # Command-line interface (Commander.js)
│   ├── gateway/             # HTTP/WS server (Fastify 5)
│   └── web-ui/              # Browser UI (React 19 + Vite 6)
├── packages/
│   ├── core/                # Shared types & interfaces
│   ├── config/              # JSON5 config loader with Zod validation
│   ├── agent-runtime/       # LLM orchestration, tool loop, sessions
│   ├── session-store/       # SQLite index + JSONL transcripts
│   ├── semantic-memory/     # RDF/SPARQL adapters, Oxigraph/Fuseki backends
│   ├── reasoner/            # OWL reasoner integration (Reasonable)
│   ├── providers/           # LLM providers (OpenRouter, OpenAI, OAuth)
│   ├── tools/               # Tool registry, built-in tools, audit log
│   ├── security/            # Policy engine, RBAC, rate limiting
│   ├── channels/            # Channel adapters (WebChat, Telegram, Discord)
│   ├── skills/              # Skill system (prompt extensions + tools)
│   ├── plugins/             # Plugin registry (ESM hot-loading)
│   ├── scheduler/           # Cron jobs & webhook handling
│   ├── sandbox/             # Docker-based sandboxing
│   ├── media/               # File storage, thumbnails, signed URLs
│   ├── nodes/               # WebSocket node protocol for IoT/devices
│   ├── testkit/             # MockProvider & test utilities
│   └── eval/                # Neuro-symbolic evaluation & benchmark harness
└── docs/                    # Architecture, interfaces, decisions

Technology Stack

Layer	Technology	Why
Language	TypeScript 5.7 (strict)	Shared types across gateway, CLI, and UI
Runtime	Node.js 20+ LTS	Modern ESM, native fetch, stable
HTTP	Fastify 5 + WebSocket	High performance, schema validation
CLI	Commander.js 13	Battle-tested, zero config
UI	React 19 + Vite 6	Fast builds, modern DX
Database	SQLite (better-sqlite3)	Zero-config, embedded, fast
Triplestore	Oxigraph (embedded) + Reasonable	Fast embedded RDF store with OWL reasoning, no separate server
RDF Library	N3.js	Turtle/JSON-LD serialization in Node.js
Build	Turborepo + pnpm workspaces	Parallel builds, intelligent caching
Testing	Vitest	Fast, native ESM support
Logging	Pino	Structured JSON, high throughput

📖 Documentation

Document	Description
Architecture	System design and component overview
Configuration	Complete configuration reference
Knowledge Graph Concept	How the RDF/OWL memory system works
Tools & Security	Tool system, policies, sandboxing
Channels	Multi-channel setup (Telegram, Discord, etc.)
Skills & Plugins	Extending Ontofelia with custom capabilities
LLM Providers	Configuring OpenRouter, OpenAI, OAuth, Ollama
API Reference	HTTP and WebSocket API documentation
CLI Reference	All CLI commands
Deployment	Production deployment guide
Interface Contracts

🧪 Development

# Build all packages
pnpm build

# Run all tests (70+ test suites)
pnpm test

# Lint everything
pnpm lint

# Build a single package
pnpm --filter @ontofelia/agent-runtime build

# Run tests for a single package
pnpm --filter @ontofelia/tools test

Project Stats

• 21 workspace packages in the monorepo (18 libraries + 3 apps)
• ~35,000 lines of TypeScript (~27,000 excluding tests)
• 70+ test suites (Vitest) covering the core modules
• 0 external LLM dependencies — bring your own provider

🗺 Roadmap

• Core architecture (Gateway, CLI, Agent Runtime)
• WebChat UI with real-time WebSocket
• Semantic Memory with embedded Oxigraph triplestore
• OWL 2 RL reasoning, ontology versioning, reflection
• Tool system with policy engine and audit log
• Multi-channel support (Telegram, Discord)
• Skills and plugin system
• Cron jobs and webhooks
• Docker sandboxing for dangerous tools
• Media system with signed URLs
• OpenRouter and OpenAI provider integration
• OAuth PKCE login (ChatGPT Plus)
• Token streaming in Web UI
• Persistent model switching (via UI + API)
• Intelligent LLM fallback with configurable model order
• Intelligent onboarding (Named Graph gap-detection)
• Ontofelia owl avatar in chat
• systemd service management
• Guardian Layer for exec commands
• Playwright E2E test suite
• Extended channel adapters (Slack, WhatsApp, Matrix)
• Docker Compose deployment
• Web UI: Memory browser and ontology visualization
• Multi-agent orchestration
• Vector search hybrid (SPARQL + embeddings)

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run pnpm build && pnpm test && pnpm lint
5. Commit (git commit -m 'Add amazing feature')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a Pull Request

📜 License

Ontofelia is open source software licensed under the Apache License 2.0.

🙏 Acknowledgments

• Oxigraph — the embedded RDF triplestore at the heart of our semantic memory
• Reasonable — the Rust OWL reasoner powering inference
• Apache Jena / Fuseki — the optional legacy triplestore backend
• OpenRouter — affordable access to the best LLMs
• Fastify — blazing fast HTTP framework
• N3.js — RDF processing in JavaScript

---

Built by Semantification.org

Knowledge is not data. Knowledge is structure.