Clover Framework · System, Human and AI working together for meaningful outcomes

cloverframework.com · Quickstart · AGENTS.md · Docs

Clover is a framework for working with System, Human, and AI to produce meaningful outcomes.

The framework itself is documented at cloverframework.com and in docs/.

This repository contains the documentation, practical guidance, case studies, and the implementation work around Clover.

• Clover Framework — understand the framework
• QUICKSTART.md — use Clover on real work
• AGENTS.md — AI agent operating guidance
• docs/README.md — documentation index
• case-studies/ — real work and outcomes
• Clover AI System Research Paper — step-by-step model optimization (Kimi K3, Nemotron 3.5 Super VL, LFM3-1.7B), the 7 layers, the 11 foundational papers (1943–2017), the 5 data-movement studies across CPU & GPU, and why standalone models (22.86%–47.14%) reach 70 / 70 (100.00%) under Clover
• Research — investigations, proposals and hypotheses, with their limits
• Clover AI v4 release notes — the current seven-layer system
• Observe experiment — the next experiment: reciprocal observation, mutual change, and distributed learning
• Run Clover — the 7-layer Clover system (CPU workstation engine & 8 × RTX 3090 GPU neuro-symbolic, compiler-verified, memory-accumulating stack): set it up, tune it to your machine, run it
• Repository map — where each kind of material belongs

Clover is both the operating methodology (Context → Direction → Execution → Outcome → Growth in AGENTS.md) and the unified open-source AI system built under it (clover-kimi-k3/) — designed to produce meaningful outcomes while remaining bounded, observable, verifiable, and accountable.

It began on a single CPU host from the Clover equation of Kimi K3 and from Fareed Khan's kimi-k3-in-c (with its first snapshot clover-k3 in git history), and currently stands as a 7-layer neuro-symbolic, compiler-verified, memory-accumulating system running across a single CPU workstation (Ryzen 9 7950X3D, 124 GB RAM), an 8 × NVIDIA RTX 3090 GPU server (192 GiB VRAM), laptops, and mobile (Samsung Galaxy S23), reproducibly bootstrapped from GitHub and Hugging Face (Santhoshsathish94/clover-ai-studio, organized under kimi/, nemotron/, and liquid-lfm3/):

1. Governance & Discernment Kernel (AGENTS.md): Operates under Context → Direction → Execution → Outcome → Growth, keeping epistemic states (observed, externally_verified, hypothesis, user_stated_belief, unresolved) distinct.
2. File-Based Memory Tree & Relational Knowledge Graph (k3_memory_graph.py, context): Human-readable Markdown memory files with YAML front matter (32 canonical seed entries, 65 typed cross-branch relationships), a closed-loop staging/ promotion gate, and six mechanisms from the 11 foundational AI papers (foundations-11-papers-human-guide.md & clover-foundations-to-clover-gpu-context.md).
3. Ontology-Guided Neuro-Symbolic GraphRAG & Symbolic Verifier (k3_ontology_graph.py, context): Deterministic property graph + 4 Horn inference rules + Newell–Simon CSm/VCt signature pruning + [E#] / [P#] provenance + CloverSymbolicVerifier.
4. HybridAgent Continuous <latent> Reasoning & Live Tools (k3_agent_engine.py, context): 14-step continuous <latent> reasoning (K3NativeHybridLink 7,168 → 7,168), live <search> (arXiv, Wikipedia, DuckDuckGo, URL fetch), sandboxed <python> (math, unit tests, charts), and MoonViT3d vision.
5. On-the-Fly Generative Compilation for Python & Rust (k3_generative_compiler.py, context): Statement-boundary partial-program sealors ($\mathcal{S}{\text{PY}}, \mathcal{S}{\text{RS}}$ via rustc) that catch syntax, arity, prefix-shadowing, stagnant loops, doctests, and Rust borrow/type errors mid-generation and roll back the KV cache.
6. 93-Layer 2.78T MoE GPU/CPU Engine, Validated Rust Host Path & Direction B Data Movement (k3_gpu_experts_lib.cu, clover-kimi-k3/src/rust/, context): Full 93-layer Kimi K3 backbone + 8 validated Rust host-path crates (slotcache, poolinit, supply, copyq, routetable, planner, loader, engcfg — 213/213 unit tests, max_abs_diff = 0.0 C++ vs. Rust parity) + five Direction B data-movement upgrades (95.22%–95.29% overall VRAM hit rate, 0 PCIe D2H writebacks on cold/warm reads, 148.5 K3 tok/s across 93 GPU layers).
7. 11-Pass Parallel Next-Concept Modeling (NCM) & Native Web / VS Code Agent Surfaces (k3_chat_server.py, extension.js): 11-level multiscale residual VQ-VAE and NextConceptTransformer emitting 64-token windows in 11 parallel passes (17,869.8 tok/s 8-GPU DDP ceiling), serving both the Clover Web UI (256K session context) and the native VS Code Agent extension.

Clover is a systems-level experiment, not a model-selection contest. We deliberately chose Kimi K3—a normal, open-weights model that scored 33 of 70 tasks (47.14%) when evaluated on its own in our custom suite—instead of choosing the strongest available model and treating its raw score as the result. The question was not, “Which model scores highest?” It was, “What can an AI system accomplish when a model is one component of a larger, structured system?”

The model provides underlying capability. Clover organizes how that capability is applied through context, direction, action, verification, memory, ontology, tools, generative compilation, and governance. The system can inspect the problem, gather relevant context, make and apply changes, test its work, and use evidence to determine whether the intended outcome was achieved. The model is important, but the system's ability to coordinate and verify work is the object of this research.

Our current 70-task evaluation across all three switchable foundation models in clover-ai-system/ (kimi-k3, nemotron-3.5-super-vl, and lfm3-1.7b, spanning 1.73B to 2.78T parameters) provides a concrete result (clover_3_models_without_vs_with_clover_70_task_report.json):

The point is not that any single model is the best model. All three models fail over half the suite when run on their own (22.86%–47.14%), and all three solve all 70 tasks (70 / 70 = 100.00%) when governed by the Clover cycle. That is evidence worth investigating about system design—not a universal measure of intelligence or proof that every model, task, or environment will produce the same result.

A stronger model may also benefit from Clover's surrounding architecture. That is a reason to study model portability and complete-system capability, not to make model rankings the central claim. Standalone frontier-model results are not direct comparisons between complete systems because those models were not run with Clover's surrounding layers attached.

We welcome independent reproduction, held-out tasks, scrutiny of the evaluation protocol, alternative scoring, and published failures as well as successes. The broader claim must remain proportional to the evidence: these results are from a custom 70-task suite and need independent validation before they can support general conclusions.

The model provides a capability. The system organizes, extends, and verifies how that capability is used to solve problems.

Clover's research goal is to make AI systems more capable—not to prove that one model is the winner. The practical goal is to publish an architecture and evidence that researchers can challenge, reproduce, and extend.

Clover organizes its operating methodology as five connected stages:

Context → Direction → Execution → Outcome → Growth

• Context — establish relevant information, memory, and constraints.
• Direction — define the objective and choose a path.
• Execution — determine and carry out the means within Direction and system boundaries.
• Outcome — establish what actually happened through evidence from the System.
• Growth — use validated experience to improve future work.

Growth is part of the framework's cycle; claims of persistent learning or general improvement require their own evidence.

We ran the exact same 70 prompts (run_real_ai_benchmark_suite.py) through Clover AI (v4) on our 8 × RTX 3090 server and through GPT-6 Astra, Claude Opus 5.5, and Gemini 4 Argon. For the three frontier models, our benchmark harness called their raw models directly without attaching Clover's surrounding layers (tools, compiler, ontology, and memory graph). The full 3-arm ablation (Arm 0: 33/70 → Arm 1: 57/70 → Arm 2: 70/70) and per-category breakdown live in the full evaluation report and clover-kimi-k3/README.md:

Three takeaways:

1. On the 58 public tasks, frontier models are already near-perfect (96.6%–98.3%) from their weights alone. When Clover's own local model is run the same way without its surrounding layers (Arm 0), it scores 30 / 58 (51.7%) on public tasks and 33 / 70 (47.1%) overall (full 3-arm ablation).
2. Why the 12 Ontology + Memory tasks require the surrounding layers: Those 12 tasks test organization-specific records and prior session measurements stored in Clover's local ontology and memory files. Because our harness did not attach Clover's Ontology and Memory layers to the frontier model calls, they rightly abstained on records not present in the prompt (7/12–8/12).
3. What Clover adds (33/70 → 57/70 → 70/70): Surrounding Clover's local open-weights model with Tools + Generative Compilation (57/70 = 81.4%) and Ontology + Persistent Memory (70/70 = 100.0%) lifts it by +52.9 percentage points while cutting GPU-seconds per solved task by 2.04× (details & raw JSON artifacts).

Its central principle is:

The model can propose.
The system decides.
The tools enforce.
Evidence verifies.
Humans remain accountable.

The implementation follows the Clover cycle:

Context → Direction → Execution → Outcome → Growth

Upstream work: FareedKhan-dev/kimi-k3-in-c · moonshotai/Kimi-K3 · togethercomputer/HybridAgent · HazyResearch/ncm · CosmoIknosLab/ontology-guided-graphrag.

• Single-workstation CPU engine (clover-kimi-k3): A 2.78-trillion-parameter model runs on a single Ryzen 9 7950X3D with 124 GB of RAM (status log). The recorded 1,000-token prompt takes 297.5–301.0 s (~0.3 s per input token) and is bit-identical to the reference chain (1,000/1,000 embeddings, 1,000/1,000 layer-92 outputs, 8,000/8,000 snapshots); decoding costs 3.1–3.5 s per output token plain, and 2.7 s per token with DSpark speculative decoding.
• 8 × RTX 3090 GPU 7-layer stack (clover-kimi-k3/src/tools/hybrid-ncm-k3/): Bootstrapped from GitHub and Hugging Face (set-up-new-machine.sh, download-hybrid-ncm-datasets.sh), verified across the 70-task suite (benchmarks/results/1936d4eb0d53/gpu/).
• Multi-domain SWE-Bench Pro V2 (HARD-51) verification suite (benchmarks/swebench-pro-v2/): Reproducible, domain-by-domain engineering challenges from SWE-Bench Pro V2 (HARD-51, 0/9 frontier baseline in traj/*) showing what fails when a model acts without surrounding system verification (Attempt 1, REWARD=0) and how the full Clover AI v4 system resolves and re-grades each problem in a pristine sandbox (REWARD=1), with one-command reproduce.sh scripts.
• Historical & research material:
  • clover-k3/, first version — historical snapshot at commit 013cbc8 (~5.9 s per generated token on CPU)
  • K3 investigation & Model equation — grouped derivations, measurements, and float-for-float verification
  • Observe experiment — the next experiment (reciprocal observation, mutual change, and distributed learning; tracked separately from Clover AI v4)
  • docs/framework/07-outcome.md & docs/governance/08-governance.md — what counts as evidence, accountability, and governance

Clover is an open, evidence-driven project. Corrections, disagreements, evidence, implementation experiments, and practical improvements are welcome.

See CONTRIBUTING.md.