K-Ops: Sistema de Base de Conhecimento Orquestrado por Agentes
arnaudgelas/K-Ops
Wiki Obsidian inteligente com rastreamento de claims e detecção de contradições
Ver no GitHubK-Ops é um pipeline de pesquisa local baseado em agentes que transforma links, PDFs e arquivos em um vault Obsidian durável com rastreamento de claims e detecção de contradições. Diferencia-se de abordagens simples mantendo proveniência rigorosa, scorecards de qualidade e um loop de reparação automático para manter a consistência do conhecimento.
Instalação
npx convez-ai arnaudgelas/K-Ops1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir bases de conhecimento pessoais com proveniência rastreável de cada afirmação
- Pesquisa estruturada multi-agente com orquestração entre Claude, Gemini e ferramentas CLI
- Gerenciar contradições e conflitos em fontes através de registros machine-readable
Veredito

K-Ops é uma implementação ambiciosa e rigorosa de um wiki LLM com foco em governança de dados. Recomendado para quem precisa de pesquisa reproduzível com auditoria completa de claims, mas exige familiaridade com Python e pipelines de IA para máximo aproveitamento.
README
A tradução para o português deste README ainda está na fila.
K-Ops
Your research should not live in a graveyard of browser tabs.
K-Ops is a local, agent-first research pipeline for turning links, PDFs, notes, and files into a durable Markdown knowledge vault for Obsidian.
It keeps the Karpathy-style LLM wiki idea in view, but treats that as the starting point. K-Ops is more opinionated: sources are normalized, claims are tracked, contradictions are surfaced, and the vault stays honest about what it knows and what it does not.
Why K-Ops, and not just asking an LLM?
In April 2026, Andrej Karpathy published an LLM wiki gist — a three-folder pattern (raw sources, compiled wiki pages, a schema file) where an LLM maintains a personal knowledge base without a vector database. The post reached 16 million views and generated a wave of community implementations.
K-Ops was built before the gist was published, and shares the same core conviction. Where it goes further is governance: K-Ops is not just a wiki layout, it is a file-native knowledge substrate with claim tracking, contradiction handling, freshness controls, and a repair loop.
| Karpathy original gist | v2 gist (rohitg00) | Community implementations | K-Ops | |
|---|---|---|---|---|
| Status | Pattern / idea doc | Spec doc | Working code, narrow scope | Working system with Python CLI |
| Source types | Any (unspecified) | Any (unspecified) | Session transcripts or posts | URLs, PDFs, GitHub repos, local files |
| Pipeline structure | raw → wiki | raw → wiki | raw → atoms → wiki | raw → source summary → concept page |
| Provenance | Not specified | Proposed | Partial | Every claim tied to source summaries |
| Contradictions | Not addressed | Proposed | Lint check only | Contradiction registry (data/contradictions.json) |
| Claim registry | No | Proposed | No | Machine-readable data/claims.json |
| Quality scorecard | No | No | No | data/scorecard.json with health drift |
| Staleness | No | Confidence decay / forgetting curves | Lifecycle states | Freshness thresholds and revalidation flags |
| Multi-agent | Single model | Proposed mesh | Multiple adapters | Claude Code, Codex CLI, Gemini CLI |
| Obsidian integration | Not specified | Not specified | Symlink overlay | Native: .obsidian/ at repo root |
| Research runs | None | None | None | Resumable: brief → collect → review → report → archive |
| Bootstrap new vault | No | No | No | kb.py bootstrap --target <dir> |
The point of the comparison is not that one gist is right and the other is wrong. The point is that K-Ops turns the gist shape into an operating system: source summaries, concept pages, machine-readable claims, contradiction tracking, scorecards, and a CLI that runs the whole loop.
Compared With Mainstream Variants
The Karpathy-style fork space is useful to look at, but it still splits the problem into partial tools:
- Direct wiki forks such as cablate/llm-atomic-wiki make the atom layer explicit. That is a sensible move for claim granularity, and it is closer to K-Ops than a plain note app. K-Ops uses source summaries and claim extraction for the same reason, but keeps the operational focus on provenance, contradiction handling, and repair rather than on atomic page design alone.
- Session-history tools such as Pratiyush/llm-wiki narrow the scope to coding-assistant transcripts and expose a production-minded MCP surface. Useful, but narrower than a research vault that must absorb arbitrary sources and keep them auditable over time.
- Memory layers such as Mem0 optimize for persistent context across sessions. That is useful infrastructure, but it is not the same thing as a curated knowledge base with source summaries, claims, and contradiction tracking.
- Notebook tools such as NotebookLM ground answers in provided sources. They are good at source-grounded answering, but they are not designed as a file-native, repairable knowledge system.
One empirical result matters for positioning: arXiv 2605.15184, Is Grep All You Need? How Agent Harnesses Reshape Agentic Search, found that the harness mattered more than the retrieval strategy and that grep often beat vector retrieval in the tested setups. That supports K-Ops's design bias: text-first, file-native, and grep-aligned.
K-Ops is therefore not trying to be the fastest scratchpad, the most polished MCP server, or the most abstract memory API. It is trying to be the governed layer that makes knowledge durable enough to audit, repair, and reuse.
What You Get
- source ingestion for URLs, PDFs, local files, and note files
- GitHub repository ingestion with repository snapshot support
- normalized source artifacts under
data/raw/ - a source registry in
data/registry.json - an Obsidian-ready vault under
notes/ - prompt templates and role-based skills for ingestion, compilation, healing, Q&A, rendering, and research
- atomic claim and contradiction registries plus a vault scorecard for quality tracking
- a Python CLI in
scripts/kb.pythat orchestrates the workflow with Codex CLI, Claude Code, or Gemini CLI - repo-root
.obsidian/settings so the repository can be opened directly in Obsidian
The Loop
Capture -> Normalize -> Compile -> Ask -> Render
- Capture - drop in URLs, PDFs, GitHub repos, notes, or local files.
- Normalize - ingest them into
data/raw/and register them indata/registry.json. - Compile - agents turn raw content into source summaries, then merge them into concept pages under
notes/. - Ask - query the vault in natural language and file grounded answers back into
notes/Answers/. - Render - convert the current knowledge base into memos, outlines, slides, or reports.
Requirements
- Python 3.11+
uv- one supported agent CLI on your
PATHcodexclaudegemini
Common fallback executable names are detected automatically:
codex-cliclaude-codegemini-cli
You can override the detected command with environment variables:
export KB_CODEX_CMD="codex"
export KB_CLAUDE_CMD="claude"
export KB_GEMINI_CMD="gemini"
Setup
1. Install uv
If uv is not already installed:
brew install uv
or:
curl -LsSf https://astral.sh/uv/install.sh | sh
2. Sync the environment
uv sync
This project uses uv for dependency management. Use uv sync and uv run; do not use pip install.
3. Verify an agent CLI
The workflow expects one of these commands to be available:
codexclaudegemini
If the command name differs on your machine, set the override variables above.
Quick Start
1. Add sources
Use one of the example input files:
examples/links.txtexamples/kb-seed-sources.txtexamples/project-on-fire-sources.txt
Each line can point to a URL, local file, or note path:
https://example.com/article
https://arxiv.org/abs/1706.03762
https://github.com/owner/repo
./examples/sample-note.md
./papers/interesting-paper.pdf
2. Ingest sources
uv run python scripts/kb.py ingest --input examples/links.txt
The ingest flow automatically routes:
- GitHub repository URLs to the repository snapshot ingest path
- GitHub repo page URLs such as
.../tree/mainor.../blob/main/README.mdto the underlying repository - other URLs to the regular web/PDF ingest path
- local files to direct copy/normalization
This creates:
data/raw/<source-id>/original.*data/raw/<source-id>/normalized.mddata/raw/<source-id>/metadata.jsondata/registry.json
If you want to force a branch for GitHub repository URLs in the input list:
uv run python scripts/kb.py ingest --input examples/links.txt --branch main
3. Compile the vault
uv run python scripts/kb.py compile --agent codex
or:
uv run python scripts/kb.py compile --agent claude
uv run python scripts/kb.py compile --agent gemini
This uses templates/compile_prompt.md and updates:
notes/Sources/notes/Concepts/notes/Home.mdnotes/TODO.md
4. Ask a question
uv run python scripts/kb.py ask --agent codex --question "What are the main claims and open questions?"
This writes a timestamped answer memo to notes/Answers/.
5. Heal and lint
uv run python scripts/kb.py heal --agent claude
uv run python scripts/kb.py lint
heal surfaces contradictions, unsupported claims, and weak structure. lint checks vault consistency and backlink integrity.
6. Validate and inspect quality
uv run python scripts/kb.py validate
uv run python scripts/kb.py install-agent-assets --agent all --scope project
uv run python scripts/kb.py extract-claims
uv run python scripts/kb.py extract-contradictions
uv run python scripts/kb.py scorecard
validate confirms the vault paths load. The registry commands rebuild the machine-readable claim and contradiction layers, and scorecard summarizes health drift.
7. Render output
uv run python scripts/kb.py render --agent codex --format memo --prompt "Write a 1-page executive memo"
Supported render formats:
memoslidesoutlinereport
Rendered outputs are written under outputs/.
8. Install CLI runtime assets
uv run python scripts/kb.py install-agent-assets --agent all --scope project
This syncs the repo's Codex skills, Claude Code agents and commands, and Gemini CLI commands/context into the selected runtime locations.
9. Use agent-native entries
After installing runtime assets, you can run the same loop from Claude Code, Codex, or Gemini instead of only through scripts/kb.py. If you are already inside one of those tools, just say what you want:
| Workflow | Just say (with Claude-code, Codex, or Gemini) | Python CLI |
|---|---|---|
| Ingest source | ingest this source | uv run python scripts/kb.py ingest --input examples/links.txt |
| Consolidate vault | consolidate the vault | uv run python scripts/kb.py compile --agent <codex|claude|gemini> |
| Ask question | answer this question from the vault: ... | uv run python scripts/kb.py ask --agent <agent> --question "..." |
| Heal vault | heal the vault | uv run python scripts/kb.py heal --agent <agent> |
| Render output | render this as a memo: ... | uv run python scripts/kb.py render --agent <agent> --format memo --prompt "..." |
Use the Python CLI for mechanical fetching and registry updates. Use the agent-native entries when you are already inside Claude Code, Codex, or Gemini and want that runtime to perform the source-summary, Q&A, healing, consolidation, or rendering pass.
Command Reference
Ingest
ingest --input <file>: ingest URLs and local paths from a newline-separated input fileingest --branch <name>: override the branch for GitHub repository URLsingest --fail-fast: stop at the first ingestion erroringest-github --repo <url>: ingest one GitHub repository directlyingest-github --compile-agent <codex|claude|gemini>: compile immediately after ingesting the repositoryrefresh --agent <...>: re-fetch/re-clone every source indata/registry.json, then compile the vault
Vault Work
compile --agent <...>: compile source summaries into durable notescompile-large --source-id <id>: run the bottom-up summarization orchestrator for large sources (>50 nodes)ask --agent <...> --question <text>: generate an answer memo from the vaultheal --agent <...>: run the healing promptrender --agent <...> --format <memo|slides|outline|report> --prompt <text>: generate an output artifact
Maintenance
lint: check registry, source notes, concept links, and backlink consistencylint --strict: fail on backlink driftlint --fix-backlinks: append missing source backlinks into concept evidence sections where possiblenormalize-github-sources: align GitHub-backed metadata fieldsnormalize-github-sources --dry-run: preview GitHub metadata changesbackfill-source-notes: create or repair missing source-summary notesbackfill-source-metadata: backfill registry and raw metadata fieldsbackfill-concept-quality: backfill concept claim-quality metadatabackfill-answer-quality: backfill answer memo quality metadatainstall-agent-assets: sync skills and prompt templates into agent runtime locationsextract-claims: rebuilddata/claims.jsonclaim-search --query <text>: search the claim registryextract-contradictions: rebuilddata/contradictions.jsoncontradiction-search --query <text>: search contradiction recordsscorecard: computedata/scorecard.jsonstale-impact: list notes flagged for revalidationclear-stale-flags: removerevalidation_requiredflagsvalidate: confirm the vault config and required paths loadmaintenance: run the full mechanical maintenance passbootstrap --target <dir>: create a new blank starter knowledge base with the same scripts, templates, and note structurebootstrap --target <dir> --force: overwrite the starter scaffold even if the target already existsbootstrap --target <dir> --with-examples: add a tiny example input folder to the starter vault
maintenance --agent <...> optionally refreshes and recompiles before the maintenance passes run.
Graph and Export
export-vault: write a zip archive containing.obsidian/andnotes/export-index: export a structured vault manifestexport-index --format csv: write the manifest as CSVbuild-graph: build the vault graph and retention reportsearch --query <text>: search the graphgraph-traverse --start <id>: traverse the graph from a noderetention-report: write the retention report on its own
Research Runs
The repo supports a resumable research-run workflow in research/ for higher-stakes topics. Active run files live outside the curated vault so they can be resumed without polluting concept pages.
Core commands:
research-start --topic <text> --tier <fast|standard|deep>research-status [topic|all]research-collect --agent <codex|claude|gemini> --topic <text> --tier <...>research-review --agent <...> --topic <text> --tier <...>research-report --agent <...> --topic <text> --tier <...>research-import --topic <text> --path <file> --provider <gemini|openai|claude|perplexity|other> [--origin <label>]research-archive --topic <text>
Imported model-generated reports are treated as leads, not authority. They are copied into the active run workspace and summarized into notes/Sources/ with explicit provenance and a lead_only posture.
Recommended Workflow
uv sync
uv run python scripts/kb.py ingest --input examples/links.txt
uv run python scripts/kb.py compile --agent codex
uv run python scripts/kb.py ask --agent codex --question "Compare the approaches and identify unresolved issues"
uv run python scripts/kb.py heal --agent codex
uv run python scripts/kb.py lint
If you are refreshing an existing vault, use this instead:
uv run python scripts/kb.py refresh --agent codex
Repository Layout
K-Ops/
├── data/
│ ├── claims.json
│ ├── contradictions.json
│ ├── fetch_queue.json
│ ├── raw/
│ ├── registry.json
│ └── scorecard.json
├── examples/
├── notes/
│ ├── Answers/
│ ├── Attachments/
│ ├── Concepts/
│ ├── Indexes/
│ ├── Maintenance/
│ ├── Runbooks/
│ ├── Sources/
│ ├── _Archive/
│ ├── _Templates/
│ ├── Home.md
│ └── TODO.md
├── outputs/
├── research/
├── scripts/
├── skills/
├── templates/
├── .obsidian/
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── OPERATING_RULES.md
├── pyproject.toml
└── uv.lock
Notes
- The orchestrator lives in
scripts/kb.py. - Most synthesis work is delegated to the selected agent CLI.
- GitHub repo ingestion creates a markdown snapshot with links back to the repository and extracted key concepts, architectural decisions, and a small set of high-signal files across the repository tree.
- Open the repo root in Obsidian to browse the curated note graph directly.