Focowiki

Markdown-native, file-first enterprise knowledge base for people, applications, and Agents.

Documentation · Docker Compose · Developer OpenAPI · Agent Integration · File Cleaning Guide

English · 中文

Focowiki turns cleaned Markdown files into an OKF-style knowledge base for people, applications, and Agents. It follows Google's Open Knowledge Format approach, which builds on Andrej Karpathy's LLM-Wiki concept: knowledge should be organized as readable files with metadata, links, indexes, and update logs.

We tested RAG-style search first. Chunk recall often missed document context, cross-file relationships, update status, and domain structure. It also required repeated tuning of embeddings, rerankers, and chunking strategies for each dataset. That led us toward a file-first knowledge base system.

Focowiki uses readable Markdown as the core knowledge representation. It preserves metadata, generates indexes and graph files, records related links, and gives Agents a corpus they can explore in a loop: read the index, open files, follow leads, search again, compare evidence, and answer with cited sources.

In a generated bundle, pages/ is the authoritative readable content, _index/ contains path-linked page indexes, and _graph/ contains path-linked page relationships. Markdown links are relative and per-file graph resources mirror page paths, so the complete directory remains navigable after it is copied without the service or API.

Quick Start

Run Focowiki with Docker Compose and the published images on GHCR.

Before installing Focowiki, make sure your machine meets these requirements:

• Minimum: CPU >= 4 cores, RAM >= 8 GiB
• Recommended with semantic enrichment enabled: CPU >= 6 cores, RAM >= 12 GiB or more

git clone https://github.com/farozerolabs/focowiki.git && cd focowiki
cp .env.example .env
cp docker-compose.yml.example docker-compose.yml
docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d

Agent-assisted Deployment

If you use Codex, Claude Code, or a similar coding agent, you can ask it to read this repository and help deploy Focowiki with Docker Compose.

Review the farozerolabs/focowiki repository:
https://github.com/farozerolabs/focowiki

Read README.md and help me deploy Focowiki with Docker Compose.

The Docker Compose template uses latest by default. To pin a release, set the image tags in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:<release-tag>
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:<release-tag>

Pin both images to the same release tag.

Read the Docker Compose deployment guide for configuration details.

Documentation

Full documentation is available at docs.focowiki.com.

• Project introduction
• Docker Compose deployment
• Agent-assisted deployment
• Developer OpenAPI
• Agent integration
• Open Knowledge Format guide
• Source-file evidence and graph guide
• File cleaning and ingestion guide

What Focowiki Provides

Focowiki takes Markdown files and folders and turns them into a knowledge base that people, applications, and AI agents can explore.

• Upload documents and folders. Add individual Markdown files or complete folder trees. Focowiki keeps their paths, names, metadata, links, and content.
• Browse organized knowledge. Open documents from a file tree, move or rename files and folders, replace content, and remove outdated material.
• Navigate an interconnected document collection. Generated indexes, relationship views, and source pages use navigable document links, so readers can move between directories, related files, and supporting context instead of treating each document as an isolated item.
• Search, then read the complete source. Ask a full natural-language question with hybrid retrieval and optional reranking. Focowiki uses search to locate relevant documents and always leads back to readable Markdown; it does not use traditional chunk-only RAG output as the final knowledge-reading mode.
• Give AI agents a native reading workflow. Agents can browse indexes, open complete Markdown files, follow document links and relationships, search again, and compare source evidence through the Developer OpenAPI or the portable linked knowledge bundle.
• Connect applications and AI agents. Use the Developer OpenAPI to upload content, browse the file tree, read full Markdown files, search, follow relationships, and manage document changes.
• Manage the system from the Admin UI. Create knowledge bases, monitor file processing, configure models and runtime settings, and manage API keys.
• Deploy on your own infrastructure. Run Focowiki with Docker Compose, PostgreSQL, Redis, OpenSearch or Meilisearch, and S3-compatible storage.

Admin UI Preview

Agent Demo Result

The demo shows a third-party Agent reading a Focowiki-backed legal knowledge base through a demo backend and Skill.

See the Agent demo result documentation for the integration context.

Why File-First

Google's OKF 0.2 announcement describes portable provenance, verification, lifecycle, and Attested Computation signals for Markdown knowledge. Focowiki pins the OKF 0.2 specification at revision 930b65fc.

Focowiki turns this model into an open-source product workflow. Teams upload cleaned Markdown files, Focowiki parses document signals, generates an OKF-style knowledge base, stores every generated file, and exposes the result through the Admin UI and Developer OpenAPI.

Markdown Input

Uploads accept .md files only. A file can be plain Markdown or include YAML frontmatter. OKF 0.2 standard fields are optional product inputs; safe missing or malformed standard fields do not by themselves block upload or reading.

---
okf_version: "0.2"
type: "Guide"
title: "Customer Support Playbook"
description: "How the support team handles priority customer requests."
tags:
  - support
  - operations
sources:
  - id: "support-handbook"
    resource: "references/support-handbook.md"
verified:
  - by: "human:support-reviewer"
    at: "2026-06-16T01:00:00Z"
status: "stable"
stale_after: "2026-12-16"
---

# Customer Support Playbook

Use this playbook when a priority customer request arrives.

Additional safe frontmatter fields are preserved as pass-through metadata. Developer OpenAPI exposes raw frontmatter plus nullable derived okfSignals, and file search can optionally filter by normalized status, trust tier, or freshness. Detailed input guidance is documented in the project introduction.

Local Development

Focowiki uses pnpm, TypeScript, Vite, React, Hono, PostgreSQL, Redis, and S3-compatible storage.

pnpm install
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r apps/api/python/requirements.lock
cp .env.dev.example .env
cp docker-compose.local.yml.example docker-compose.local.yml
docker compose -f docker-compose.local.yml up -d postgres redis minio minio-init opensearch
pnpm --filter @focowiki/api db:migrate
pnpm dev

pnpm dev starts the Admin UI, both API listeners, and the unified worker. Keep the Python virtual environment active while the development runtime is running.

Local service URLs:

• Admin UI: http://127.0.0.1:43100
• Admin API: http://127.0.0.1:43000
• Developer OpenAPI: http://127.0.0.1:43200

The local environment template selects OpenSearch by default. To use the bundled Meilisearch service, uncomment the complete meilisearch service block in the Compose template, set both SEARCH_PROVIDER and COMPOSE_PROFILES to meilisearch, then start meilisearch search-init instead of opensearch. The template exposes Meilisearch only on loopback at MEILI_PORT (default 57700) for the host development runtime.

License

Focowiki is distributed under a modified Apache License 2.0. See LICENSE.

References

• Open Knowledge Format 0.2 announcement
• OKF 0.2 specification, pinned revision
• Focowiki documentation

_{Related links: linux.do · V2EX}