The missing knowledge layer for self-improving AI agents.
WikiEvolve is a local-first memory and skill-evolution system for AI coding agents. It turns raw evidence into a grounded knowledge wiki, then uses execution traces to propose, evaluate, and safely roll back improvements to Agent Skills.
Grounded memory. Measured learning. Reversible change.
Install · Quick start · How it works · Security · Research foundations
WikiEvolve combines two independently installable skills:
- Knowledge Wiki turns documents, notes, research, and conversations into a compact Markdown wiki with immutable evidence and verifiable provenance.
- Evolve Agent Skills turns repeated successes and failures into one atomic skill proposal, evaluates it against a baseline, and restores the baseline when it does not improve.
Everything is local and inspectable. The CLIs use only the Node.js standard library. There is no hosted service, model lock-in, shell installer, postinstall hook, or hidden network request.
| Capability | Notes or prompt memory | Uncontrolled self-editing | WikiEvolve |
|---|---|---|---|
| Raw evidence with SHA-256 provenance | Rarely | Sometimes | Yes |
| Durable, source-grounded wiki | Partial | Partial | Yes |
| Learns from successes and failures | No | Yes | Yes |
| One atomic change per evaluation | No | Rarely | Yes |
| Equivalent baseline and candidate tests | No | Rarely | Yes |
| Automatic byte-identical rollback | No | Rarely | Yes |
| Retains rejected ideas | No | Rarely | Yes |
| Local, provider-neutral files | Sometimes | Varies | Yes |
WikiEvolve is useful for coding agents, research agents, support agents, internal knowledge systems, evaluation pipelines, and any workflow where agent memory must remain inspectable.
Normal knowledge work and skill evolution have different context and safety requirements. Keeping them separate prevents a large maintenance wiki from leaking into ordinary task inference and lets either skill be installed on its own.
flowchart TD
A["Raw evidence and traces"] --> B["Persistent wiki"]
B --> C["One staged skill change"]
C --> D["Equivalent evaluation"]
D -->|Improves| E["Accept candidate"]
D -->|Tie or regression| F["Restore baseline"]
E --> B
F --> B
The raw evidence and wiki are persistent. Only the active skill change is reversible.
- Node.js 20 or later
- An Agent Skills-compatible client for skill discovery
No npm install is needed to use the included scripts.
Install both skills with the open skills CLI:
npx skills add LeonardSEO/wikievolveInstall one skill globally for Codex:
npx skills add LeonardSEO/wikievolve --skill knowledge-wiki -a codex -g -y
npx skills add LeonardSEO/wikievolve --skill evolve-agent-skills -a codex -g -yOmit -g for a project-local installation. Review third-party skills before installing them.
The skills follow the open Agent Skills format and can be discovered by Codex, Claude Code, Cursor, and other clients supported by the skills CLI. OpenAI-specific display metadata remains isolated under agents/openai.yaml.
WikiEvolve follows the official .codex-plugin/plugin.json format and includes a repo marketplace.
codex plugin marketplace add LeonardSEO/wikievolveThen start Codex, enter /plugins, select the WikiEvolve marketplace, install the plugin, and begin a new session. ChatGPT desktop can also discover a cloned repo marketplace after restart.
There is intentionally no npx plugins command in this README. Codex plugin installation uses the official plugin browser and marketplace CLI; portable Agent Skills installation uses npx skills.
From an installed knowledge-wiki skill directory:
node scripts/wiki.mjs init --root C:\work\research --title "Research wiki"
node scripts/wiki.mjs ingest --root C:\work\research --file C:\inbox\report.txt --json
node scripts/wiki.mjs query --root C:\work\research --text "risk threshold" --json
node scripts/wiki.mjs lint --root C:\work\research --jsonOn macOS or Linux, use normal POSIX paths. The commands and scripts are otherwise identical.
The agent reads the registered source, classifies material as new, updated, disputed, or unchanged, and writes concise pages under wiki/ with references such as:
Confidence: high
The published threshold is 20 units. [source: `raw/sources/src-abc-report.txt`, page 7]From an installed evolve-agent-skills skill directory:
node scripts/evolve.mjs init --root C:\work\agent-project
node scripts/evolve.mjs trace add --root C:\work\agent-project --file C:\runs\failure.txt --outcome failure
node scripts/evolve.mjs trace sample --root C:\work\agent-project --jsonAfter the agent maintains a reusable pattern and prepares one reviewed replacement file:
node scripts/evolve.mjs proposal create --root C:\work\agent-project --skill C:\work\agent-project\skills\my-skill --target SKILL.md --replacement C:\work\candidate.md --rationale C:\work\rationale.md --json
node scripts/evolve.mjs proposal apply --root C:\work\agent-project --id <proposal-id>
node scripts/evolve.mjs evaluation record --root C:\work\agent-project --id <proposal-id> --baseline 0.62 --candidate 0.75
node scripts/evolve.mjs decision finalize --root C:\work\agent-project --id <proposal-id> --policy strict-improvement --jsonCreating a proposal does not modify the skill. Application is a separate, explicit action. A tie or regression under strict-improvement restores the byte-identical baseline and records the rejection in wiki/skill-impact.md.
| Layer | Purpose | Rollback behavior |
|---|---|---|
raw/ |
Immutable sources and bounded execution traces | Never rolled back |
wiki/ |
Grounded knowledge, reusable patterns, impact history | Never rolled back |
skills/ |
Active instructions and staged candidates | Candidate is reversible |
evaluations/ |
Cases, scores, snapshots, and decisions | Append and retain |
- Every factual conclusion remains traceable to raw evidence.
- Conflicts are represented, not silently flattened.
- Semantic synthesis is done by the agent; deterministic storage and checks are done by the CLI.
- Evolution uses a bounded failure-and-success sample.
- The proposer reads patterns and rejection history, then changes one behavior.
- Baseline and candidate use the same evaluation cases and scoring.
- Runtime work never executes wiki text, traces, candidates, or rationale as code.
See concepts for the underlying model and security for the trust boundary.
npm test
npm run checkThe test suite uses Node's built-in test runner and temporary directories. CI covers Node 20 and 22 on Linux, macOS, and Windows.
WikiEvolve is an original implementation informed by:
- Andrej Karpathy's LLM wiki concept
- WikiSkill: Persistent Knowledge for Self-Improving Agents
- sdyckjq-lab/llm-wiki-skill
- Astro-Han/karpathy-llm-wiki
The distinguishing design is the combination of a source-grounded knowledge system with a reversible, evaluation-gated Agent Skill evolution loop. See Third-party notices for licenses and the exact relationship.
Issues, focused pull requests, evaluation fixtures, and portability improvements are welcome. Read CONTRIBUTING.md before changing the on-disk schemas or safety boundaries.
MIT