Proposal: migrate the canonical repository-memory OKF wiki from OpenKB + Graphify to OpenWiki

[rmonier]

Summary

This issue proposes evaluating—and, if the proof of concept succeeds, performing—a migration of the repository-memory pipeline from:

deterministically transformed docs and source code
    + Graphify graph/report
    → OpenKB compilation
    → large OKF concept wiki

to:

repository source, existing docs, tests, and Git history
    → OpenWiki code mode
    → compact, incrementally maintained, editable OKF wiki

The motivation is not that OpenKB or Graphify are intrinsically bad tools. They appear to solve different problems from the one this skill ultimately needs to solve.

The intended product is a reusable transformation skill that gives any repository a durable, version-controlled and agent-readable memory. The OKF wiki itself must be the canonical memory, not a disposable documentation export or a build artifact generated from another hidden source of truth.

The current OpenKB-based implementation works mechanically, but experiments on both this project and another large repository have exposed several architectural problems:

• approximately 500 concepts;
• an index.md exceeding 1,000 lines;
• overlapping or nearly synonymous concept pages;
• weak compression when source files are transformed to Markdown;
• a large catalog that agents must read before they know what is relevant;
• expensive full recompilation;
• generated pages that cannot safely serve as a durable manual editing surface;
• a lossy use of Graphify, where its queryable graph is reduced to a Markdown report and then summarized again by OpenKB.

OpenWiki now appears much closer to the intended model. Its repository mode explicitly aims to produce a small, human-shaped documentation hierarchy, starts from quickstart.md, avoids documenting every file, assigns one canonical home to each concept, and performs surgical updates based on Git changes. OpenWiki issue #84 requests OKF output, and OpenWiki PR #263 implements deterministic OKF v0.1 output for code and personal modes.

This issue asks us to validate that OpenWiki can replace OpenKB and remove Graphify from the mandatory memory-generation pipeline.

---

Original objective

The transformation skill should make a repository “agent ready” by creating and maintaining a durable repository memory.

That memory should:

1. explain the repository’s purpose, architecture, workflows, domain model, constraints, operations, tests and extension points;
2. work when a repository has substantial existing documentation;
3. also work when the repository has little or no human documentation and the implementation must be inferred from source code, tests, configuration and Git history;
4. remain useful to humans as ordinary Markdown;
5. remain directly editable by humans and coding agents;
6. be versioned and reviewed with normal Git diffs;
7. be consumable by Claude Code, Codex, OpenCode, Hermes, OpenClaw and other harnesses without requiring a proprietary runtime;
8. be portable as an Open Knowledge Format v0.1 bundle;
9. preserve source references and make implementation claims verifiable;
10. remain concise enough that agents can discover relevant context progressively instead of loading an exhaustive corpus into every conversation;
11. evolve incrementally as code and documentation change;
12. avoid repeatedly paying to rediscover or regenerate the entire repository context.

Important non-goal

The skill is not meant to implement a new general-purpose vector store, memory database, RAG engine or coding harness.

The goal is to select and orchestrate a tool that maintains a good repository-memory wiki.

---

Current implementation

The current design has approximately four levels:

Level 0
AGENTS.md router
    |
    | instructs the agent to read the OKF index
    v
Level 1
OKF index.md
~1,000 lines, ~500 concept descriptions
    |
    | links to generated knowledge
    v
Level 2
OpenKB summaries, concepts, entities and explorations
    |
    | links to raw evidence
    v
Level 3
Deterministically transformed Markdown sources
- original Markdown/docs
- Python source converted to Markdown
- TypeScript source converted to Markdown
- other supported files
- Graphify GRAPH_REPORT.md

The raw-source lifecycle is deterministic:

• new files are added;
• changed files are replaced;
• deleted files are removed;
• filenames and ordering are stable;
• the transformation avoids timestamps and other avoidable nondeterminism.

The wiki is then refreshed with OpenKB recompilation.

Graphify was added to improve code understanding:

• it builds a tree-sitter-derived structural graph;
• produces graph.json;
• produces a human-readable GRAPH_REPORT.md;
• can answer scoped graph queries;
• can expose its graph over MCP.

However, the current pipeline primarily submits GRAPH_REPORT.md to OpenKB as one more document.

---

Problems observed in practice

1. The root index has stopped functioning as a router

The intention was progressive discovery:

AGENTS.md
    → index.md
    → relevant concepts
    → supporting evidence

In practice, requiring the agent to read a 1,000-line catalog containing roughly 500 concepts means the entire concept taxonomy is broadcast before the agent has enough task-specific information to rank it.

This is not strong progressive discovery. It is exhaustive catalog injection followed by selective reading.

The agent must:

1. inspect hundreds of short descriptions;
2. distinguish overlapping concepts from each other;
3. select several potentially relevant pages;
4. resolve duplicated explanations;
5. often inspect the source code anyway.

Research supports being cautious about this pattern:

• Lost in the Middle found that models do not use all positions in long contexts equally and can perform worse when relevant information is buried in the middle.
• ContextBench evaluated 1,136 repository tasks across 66 repositories and eight programming languages and found that coding agents generally favor recall over precision, retrieve substantial unused context, and still have large gaps between explored and effectively used context.
• Claude Code loads only the first 200 lines or 25 KB of its memory index at startup and leaves detailed topic files for on-demand reads. Claude Code memory documentation
• Codex caps the combined project instruction chain at 32 KiB by default and recommends nested, scope-specific guidance. Codex AGENTS.md documentation
• OpenClaw keeps detailed memory files behind search rather than injecting them all at bootstrap. OpenClaw memory documentation
• Hermes limits its always-loaded durable memory to approximately 1,300 tokens. Hermes memory documentation

These systems are not directly equivalent to an OKF repository wiki, but they consistently demonstrate the same principle:

Keep the bootstrap context small and route toward detailed material only when it is relevant.

OpenKB also has an open request for integration with a search engine such as QMD, which confirms that selective text retrieval is not currently part of the core wiki-navigation path: OpenKB issue #63.

2. Five hundred concepts are not necessarily bad, but the present topology is

A wiki can legitimately have hundreds or thousands of pages. The problem is not the number alone.

Five hundred concepts can remain useful when they are:

• organized hierarchically;
• searchable;
• assigned to clear domains or modules;
• reached through compact local indexes;
• sufficiently distinct;
• useful enough to compress several source locations.

The current result is problematic because:

• all concepts appear in one large global routing surface;
• several concepts overlap semantically;
• some pages largely restate one source file;
• descriptions are not always discriminative enough to route reliably;
• new source ingestion can create another nearby concept instead of consolidating an existing one.

The useful quality test is:

Does this page connect and compress knowledge that would otherwise require inspecting several files, tests, configurations or documents?

A page explaining an authentication lifecycle across middleware, services, configuration, failure handling and tests is valuable.

A page that paraphrases one small auth_service.py file is usually not valuable enough to justify a persistent wiki page.

3. Converting source code to Markdown makes it ingestible, but not structurally understood

OpenKB is primarily a heterogeneous document compiler. It accepts Markdown, PDF, Word, PowerPoint, HTML, Excel, CSV, text and URLs. It summarizes documents, reads existing concept/entity pages, and creates or updates concepts across sources. OpenKB README

Transforming .py and .ts files to Markdown allows them to enter that pipeline, but it does not give OpenKB native knowledge of:

• symbol identity;
• imports;
• callers and callees;
• inheritance;
• type relationships;
• public versus private APIs;
• test-to-implementation relationships;
• module boundaries;
• change-impact paths.

Fine-grained evidence addressing is also not yet fully built into the format: OpenKB issue #72 requests stable, addressable paragraph identifiers so that concepts and external systems can reference precise passages rather than entire pages.

The code remains text placed inside a document-oriented workflow.

OpenKB also currently sends Markdown through its short-document path without a general heading-aware chunking fallback. OpenKB issue #73 documents that Markdown sources are sent as one complete LLM message regardless of their size, with no heading-aware, token-aware or hierarchical fallback. The reporter reproduced this against a corpus of 475 Markdown documents and several documents that could not fit into a practical model context. Large-document processing with local models has also produced timeout pressure for users, as documented in OpenKB issue #132.

4. OpenKB’s compilation strategy encourages concept accumulation

According to the OpenKB documentation, each ingested document:

1. receives a summary;
2. is compared with existing concept and entity pages;
3. may create or update multiple concepts;
4. may touch approximately 10–15 wiki pages;
5. updates the global index and log.

This is useful for accumulating knowledge from heterogeneous papers, specifications and business documents.

For a repository containing many implementation files, however, source-by-source compilation can repeatedly ask an LLM to decide whether a code concern:

• belongs in an existing concept;
• deserves a new concept;
• is a subtopic;
• should be merged with an existing page;
• should be renamed;
• should remain merely a source reference.

Those decisions are probabilistic. At larger scales, previous probabilistic taxonomy choices become state that influences later compilation.

OpenKB itself lists the following work on its roadmap:

• scaling to large collections with nested folder support;
• hierarchical concept/topic indexing for massive knowledge bases;
• a database-backed storage engine.

Those roadmap entries align closely with the limitations currently being observed. OpenKB README

5. Full recompilation is not a satisfactory maintenance model

openkb recompile --all reruns compilation for all indexed sources, regenerates summaries and rewrites concept pages. The OpenKB documentation explicitly warns that manual edits to managed concept pages are overwritten. OpenKB README

This has several consequences:

• update cost grows with both corpus size and wiki size;
• unchanged sources are reconsidered;
• large existing concepts are repeatedly rewritten;
• compilation order and model behavior can affect ontology decisions;
• a correction made directly to a concept page may disappear;
• a model or prompt update can cause large unrelated diffs;
• the wiki is difficult to treat as a durable collaborative memory.

OpenKB has also had an issue where length-truncated model responses could be repaired into parseable JSON and written as partial concept pages. OpenKB issue #148 documents concept pages being silently truncated while the command still completed successfully. The specific defect was addressed by OpenKB PR #161, which rejects malformed or truncated model output before committing page mutations, but the incident still illustrates the risk inherent in repeatedly rewriting large generated pages.

6. The wiki is not a sufficiently safe editing surface

The desired contract is:

The committed OKF wiki is the memory.
Humans and agents may improve it.
Future maintenance should preserve valid improvements.

The present OpenKB contract is closer to:

Raw documents are compiler inputs.
Managed wiki pages are compiler outputs.
Manual changes to generated pages may be overwritten.

This makes the wiki more like a compiled artifact than the canonical memory desired by this project.

Customizing OpenKB’s wiki instructions can influence future generations, but it does not turn arbitrary page edits into durable source data.

7. Graphify is currently used through its weakest interface

Graphify provides:

• deterministic tree-sitter extraction for many languages;
• a queryable graph.json;
• scoped graph queries;
• community detection;
• confidence distinctions such as EXTRACTED, INFERRED and AMBIGUOUS;
• optional MCP access;
• a broad GRAPH_REPORT.md. Graphify README

Our pipeline does this:

AST-derived/queryable graph
    → global Markdown report
    → OpenKB summarization
    → concept page
    → agent reads generated prose

This collapses a rich, queryable representation into static prose, then summarizes it again.

If Graphify remains in the project, the more appropriate usage is:

agent needs exact structural information
    → graphify query / MCP
    → relevant graph neighborhood
    → current source verification

It should not be mandatory merely to produce a report that another LLM compiler ingests.

---

What current repository-documentation research suggests

The strongest recent repository-documentation systems converge on several ideas that differ from the current OpenKB pipeline.

RepoAgent

RepoAgent builds dependency information and generates code documentation in dependency-aware order. It demonstrates the value of repository structure over independent file summarization, but its original implementation is strongly Python-oriented and tends toward fine-grained code documentation.

It is not a direct replacement for a concise, heterogeneous, editable repository-memory wiki.

CodeWiki

CodeWiki uses hierarchical decomposition, recursive processing and architectural synthesis across multiple programming languages. Its reported CodeWikiBench quality score is 68.79% with proprietary models and 64.80% with an open model configuration, compared with 64.06% for DeepWiki.

Its hierarchy-first strategy is more appropriate than a flat file-to-concept process.

However, CodeWiki is primarily a documentation generator. Its generated documentation remains an output derived from its analysis pipeline. That does not align as closely with the requirement that the committed OKF wiki itself remain the primary editable memory.

HCGS / Code-Craft

Hierarchical Code Graph Summarization constructs bottom-up summaries over a code graph. It reports up to an 82% relative improvement in top-1 retrieval precision on its evaluated codebases.

Its important lesson is not necessarily that we should adopt that exact implementation. It is that summaries should be attached to structural scopes and retrieved hierarchically—not generated as hundreds of globally competing concepts.

RepoDoc

RepoDoc is the closest research architecture to the ideal code-documentation lifecycle:

1. construct a repository knowledge graph;
2. cluster code into cohesive hierarchical modules;
3. generate scoped, cross-referenced documentation;
4. propagate source changes through the graph;
5. regenerate only affected documentation.

Its authors report, across 24 repositories and eight languages:

• 32.5% higher API coverage;
• 10.4% higher completeness;
• three times faster initial generation;
• 85% fewer generation tokens;
• 73% less update time;
• 77% fewer update tokens;
• 10.2% higher update recall.

These are author-reported benchmark results and still need independent replication. The public implementation is also currently young.

RepoDoc nevertheless strongly validates the principle that repository documentation should be organized around cohesive modules and semantic change impact rather than flat source ingestion.

Structural memory remains useful, but it is complementary

Codebase-Memory builds a persistent tree-sitter-based repository graph and exposes it over MCP. Its authors report 83% answer quality versus 92% for file exploration, while using ten times fewer tokens and 2.1 times fewer tool calls across 31 repositories.

This suggests:

• structural indexes can be excellent routing tools;
• they can dramatically reduce exploration cost;
• they do not fully replace source verification;
• structural navigation and semantic wiki memory are complementary.

This supports making Graphify or another code graph optional runtime tooling, rather than feeding its global report into the wiki compiler.

---

Tool comparison for this project

Concern	OpenKB	Graphify	OpenWiki
Primary abstraction	Heterogeneous document knowledge base	Structural/queryable knowledge graph	Human-shaped repository knowledge wiki
Main input	Documents converted to Markdown/PageIndex	Source, docs and other artifacts parsed into graph nodes/edges	Repository source, existing docs, tests, configuration and Git history
Native code structure	No general AST/code graph	Yes	No persistent AST graph
Output	Summaries, concepts, entities, explorations and index	graph.json, report, visualization, queries/MCP	quickstart.md plus a compact hierarchy of repository pages
Initial granularity	Potentially many concepts per source	Nodes, edges and communities	At most eight documentation pages initially
Duplication policy	Prompt asks model to reuse existing concepts	Graph identity and edge model	One canonical page per concept; link instead of repeating
Update strategy	Source recompile; --all rewrites managed pages	Graph rebuild/incremental structural updates	Git-aware documentation impact plan and surgical page edits
No-change behavior	Recompile still invokes compilation when requested	Structural rebuild possible	No-op preflight skips the agent when repository state is unchanged
Human editing	Markdown is editable, but recompilation overwrites managed pages	Graph/report are primarily generated outputs	Existing pages are read as update input and accurate wording should be preserved
Canonical memory fit	Weak for fully editable canonical wiki	Not a semantic wiki	Strong
OKF	Supported	No	Implemented in open PR #263
Best role	Papers, specifications and heterogeneous document corpora	Exact structural exploration	Compact, durable repository memory

---

Why OpenWiki appears to fit the requirement better

OpenWiki’s current repository-mode instructions explicitly require the agent to:

• use quickstart.md as the entry point;
• explain architecture, workflows, domain concepts, data models, integrations, operations, testing and extension points;
• explain why important code exists, not only where it is;
• organize documentation like human documentation rather than a file inventory;
• avoid thin pages;
• avoid repeating concepts;
• give each concept one canonical home;
• use existing README files, docs trees, runbooks and skills as primary material;
• summarize and link to existing documentation rather than duplicating it wholesale;
• inspect representative source files instead of reading every file;
• use at most eight documentation pages on the initial run and track deferred coverage in the quickstart.md backlog. OpenWiki prompt

For updates, it requires:

• reading the existing wiki before editing;
• constructing a source-change-to-document impact plan;
• modifying only pages directly affected by repository changes;
• preserving useful structure and wording when still accurate;
• replacing one stale sentence instead of adding broad new prose when possible;
• keeping each concept in one canonical page;
• avoiding formatting-only changes;
• avoiding broad refreshes;
• normally touching only one or two pages when fewer than approximately five source files changed;
• permitting a complete no-op when the wiki is already current. OpenWiki prompt

OpenWiki previously performed a complete agent run even when no repository change existed. OpenWiki issue #44 reported a zero-diff update taking 759 seconds, compared with 117 seconds for an update with a real source diff. The behavior was corrected by OpenWiki PR #57, which skips model and agent initialization when Git HEAD is unchanged and there are no meaningful worktree changes.

These rules directly address the pathologies observed in the current wiki.

---

OpenWiki’s pending OKF support

OpenWiki issue #84 requests Open Knowledge Format support. OpenWiki PR #263 implements OKF v0.1 as the standard output for code and personal modes.

The implementation must comply with the actual OKF v0.1 specification.

For every non-reserved .md concept document:

• a parseable YAML frontmatter block is mandatory;
• the frontmatter must contain a non-empty type;
• title, description, resource, tags and timestamp are optional but recommended where applicable;
• producer-defined additional keys are permitted;
• unknown additional fields should be preserved when round-tripping.

The reserved files have separate rules:

• index.md is an optional OKF directory inventory for progressive disclosure and must follow the index structure defined by the specification when present;
• log.md is an optional chronological update log and must follow the date-grouped structure defined by the specification when present;
• index files normally contain no frontmatter, except that the bundle-root index.md may contain okf_version: "0.1" as the specification’s explicit versioning exception.

PR #263 proposes a useful ownership split.

Model/human/agent-owned

• concept page bodies;
• repository explanations;
• architectural rationale;
• workflows;
• source references;
• curated content.

Code-owned

• mandatory, valid YAML frontmatter on every non-reserved Markdown page;
• the required non-empty type;
• recommended title, description and timestamp metadata;
• reserved indexes and logs;
• OKF version declaration;
• conformance validation.

The pull request states that:

• the model writes page bodies rather than attempting to generate conformance metadata;
• a deterministic post-run pass adds or normalizes frontmatter;
• the post-run pass owns type, title, description and timestamp;
• timestamps change only when page bodies change;
• log.md changes only when content changes;
• writes are atomic;
• no-op updates leave the bundle byte-identical;
• a conformance fixture is validated in tests. OpenWiki PR #263

This is compatible with treating the OKF wiki as canonical memory.

The semantic content remains directly editable Markdown, but the frontmatter itself is not optional. Every concept page must remain a conformant OKF document. Mechanical normalization should preserve the human-authored body and unknown producer-defined metadata rather than treating the page as disposable output.

Important current limitation

As of July 13, 2026, OpenWiki PR #263 is still open and awaiting an approving review.

A migration should therefore either:

1. wait for the pull request to merge and use a released OpenWiki version containing it; or
2. temporarily pin the exact reviewed commit SHA rather than a floating pull-request branch.

The branch has already been force-pushed during development, so relying on the branch name alone would not provide a reproducible dependency.

---

Is the OpenWiki wiki really canonical and editable?

The answer appears to be yes, with one qualification.

OpenWiki updates read the existing wiki and edit it in place. The existing pages are therefore state used by the next update—not merely an export regenerated from a separate database.

Humans and normal coding agents can directly:

• correct a technical explanation;
• add architectural rationale;
• record a non-obvious invariant;
• improve navigation;
• add a missing workflow;
• clarify a source reference;
• consolidate duplicated explanations.

Future update runs are instructed to preserve those changes when they remain accurate.

Current OpenWiki code mode explicitly treats /openwiki/INSTRUCTIONS.md as the shared, user-authored repository brief. It must be read to understand scope and priorities and must not be modified during normal init, update or chat runs unless the user explicitly requests a brief change. OpenWiki prompt

Because openwiki/INSTRUCTIONS.md is a non-reserved Markdown file inside the OKF tree, it must itself remain conformant: it needs parseable YAML frontmatter with a non-empty type. The deterministic OKF post-pass should normalize its required metadata without overwriting its user-authored body or additional producer-defined fields.

The qualification is that edit preservation is partly enforced through agent instructions rather than an immutable merge algorithm.

An OpenWiki update could still accidentally rewrite or omit valuable manual material. For that reason:

• updates should always produce reviewable Git diffs;
• CI should open a PR/MR rather than push directly;
• the memory contract must be explicit in openwiki/INSTRUCTIONS.md;
• preservation of manual edits must be tested during the proof of concept.

This is still materially closer to the required model than OpenKB recompilation, which explicitly treats managed pages as replaceable compiler output.

---

Why quickstart.md, not the complete OKF index.md, should be the agent entry point

The router should no longer require agents to read a 1,000-line global catalog.

The target navigation should be:

AGENTS.md
    → openwiki/quickstart.md
    → one or two relevant architecture/domain/workflow pages
    → current source and tests when verification is needed

quickstart.md should be a compact semantic router written for humans and agents.

The OKF index.md can remain a mechanically generated bundle inventory and progressive-disclosure aid, but it should not automatically be injected into every repository task when it enumerates more information than the task requires.

OpenWiki currently maintains bounded blocks in root AGENTS.md and CLAUDE.md files so coding agents are directed toward the repository wiki while non-OpenWiki content remains untouched. OpenWiki README

The desired routing contract is:

## Repository memory

The canonical repository memory is under `openwiki/`.

For questions involving architecture, workflows, domain behavior,
operations, tests or repository conventions:

1. Read `openwiki/quickstart.md`.
2. Open only the linked pages relevant to the current task.
3. Verify implementation details against current source code and tests.
4. Treat the wiki as canonical project context and rationale, while
   treating current source and tests as authoritative for implementation.
5. Update the relevant wiki page when a task reveals durable missing or
   stale project knowledge.

---

Why OpenClaw memory-wiki and Hermes are not direct replacements

OpenClaw and Hermes provide useful examples of bounded runtime memory, but neither is primarily a repository-wiki compiler.

OpenClaw’s memory architecture keeps a compact bootstrap memory and places detailed files behind search. Its memory-wiki functionality can consume and manage synthesized knowledge, but it does not replace the need to understand a repository and author the initial architectural wiki. OpenClaw memory documentation

Hermes provides a very small persistent memory plus searchable session history. It is a harness-specific runtime memory mechanism, not a tool for generating and incrementally maintaining repository architecture documentation. Hermes memory documentation

They reinforce OpenWiki’s compact-entry-point model but should not become mandatory dependencies of the transformation skill.

---

Why CodeWiki and RepoDoc are not the proposed primary migration target

CodeWiki has stronger explicit structural decomposition than OpenWiki and is an important comparison point.

However, this project requires the committed wiki to remain the primary editable source of memory. CodeWiki is more naturally treated as a generator whose documentation is derived from its repository-analysis process.

RepoDoc is the strongest research match for graph-based incremental documentation, but its public implementation is currently too young to become a foundational dependency without additional validation.

OpenWiki provides the better immediate fit because:

• its wiki is maintained in place;
• it explicitly starts updates from the existing pages;
• it prioritizes preservation and surgical edits;
• it uses a compact human documentation hierarchy;
• it supports a user-owned repository brief in openwiki/INSTRUCTIONS.md;
• it now has an active OKF implementation.

---

Proposed target architecture

                        ┌─────────────────────────┐
                        │ Existing repository docs│
                        │ README, ADRs, runbooks  │
                        └───────────┬─────────────┘
                                    │
Repository source ──────────────────┤
Tests/config/Git history ───────────┤
                                    ▼
                            OpenWiki code mode
                                    │
                   reads and edits existing wiki in place
                                    │
                                    ▼
                     Canonical repository OKF memory
                               openwiki/
                     ├── quickstart.md
                     ├── architecture/
                     ├── domain/
                     ├── workflows/
                     ├── operations/
                     ├── testing/
                     ├── INSTRUCTIONS.md
                     ├── index.md
                     └── log.md
                                    │
                     ┌──────────────┴──────────────┐
                     ▼                             ▼
              Human/agent editing           Agent consumption
                                            via AGENTS.md router

Optional structural tooling may exist beside this:

agent requires exact callers, dependencies or impact analysis
    → Graphify query/MCP or another structural index
    → current source verification

It should not feed a global report into the wiki compiler by default.

---

Proposed repository-memory contract

openwiki/INSTRUCTIONS.md should be committed as the shared, user-authored OpenWiki brief for the repository. Because it is a non-reserved concept file inside the OKF tree, it must include valid frontmatter with a non-empty type.

---
type: Repository Memory Contract
title: Repository memory contract
description: Editorial and maintenance rules for the canonical repository memory.
---

# Repository memory contract

The `openwiki/` directory is the canonical, editable memory of this
repository. It is not a disposable documentation export.

## Editorial requirements

- Preserve accurate human- and agent-authored content during updates.
- Do not recreate the wiki from scratch after initialization.
- Modify existing wording only when repository evidence makes it stale,
  incomplete, misleading or contradictory.
- Give each architectural or domain concept one canonical home.
- Link to canonical explanations instead of repeating them.
- Prefer cohesive architecture, workflow, domain, operations and testing
  pages over file-by-file documentation.
- Do not create Markdown mirrors of source files.
- Keep `quickstart.md` compact and use it as the primary semantic router.
- Keep the page set intentionally small and factorized.
- Reference relevant source paths, symbols, tests and existing docs.
- Treat current source and tests as authoritative for implementation
  behavior.
- Preserve design rationale, constraints, decisions and maintainer
  knowledge that cannot be reconstructed from code alone.
- Flag contradictions instead of silently deleting important curated
  knowledge.
- A normal update may make no changes.

---

Proposed migration plan

Phase 0 — dependency decision

• Track OpenWiki issue #84 and PR #263.
• Prefer a released version containing OKF support.
• If evaluation must begin before merge, pin an exact reviewed commit SHA.
• Record the OpenWiki version/commit and target OKF version in the skill.
• Verify that every non-reserved Markdown file receives valid YAML frontmatter with a non-empty type.
• Verify that reserved index.md and log.md files follow the OKF specification.
• Verify that valid producer-defined metadata survives normalization and updates.
• Confirm that code mode reads and preserves openwiki/INSTRUCTIONS.md in local and CI runs.
• Consider enabling a run-iteration guard once OpenWiki issue #51 and PR #273, or an equivalent mechanism, are resolved. The issue reports approximately 12× cost variance between repeated initializations of the same repository, and the PR introduces a configurable maximum number of LangGraph iterations.

Phase 1 — preserve the current implementation as an evaluation baseline

Before removing anything:

• retain a snapshot of the current OpenKB bundle;
• record its page and concept count;
• record index.md size and approximate token count;
• record duplicate/overlap examples;
• record initialization and recompilation token/cost figures;
• prepare representative questions and repository tasks;
• record how often agents need to inspect source after reading the wiki.

The old bundle should be used for comparison, not automatically migrated concept by concept.

Phase 2 — OpenWiki proof of concept

On this repository and at least one large Python/TypeScript repository:

• create a conformant openwiki/INSTRUCTIONS.md;
• run openwiki code --init --print exactly once;
• inspect the generated quickstart.md;
• review architecture, domain, workflows, testing and operations coverage;
• manually add or correct important durable knowledge;
• commit the resulting wiki;
• verify OKF conformance;
• run an update after a small source change;
• run an update after a cross-cutting source change;
• run an update after a documentation-only change;
• run a no-change update;
• verify whether accurate manual edits survive each update;
• verify whether valid additional frontmatter fields survive each update.

Phase 3 — agent routing

• replace the OpenKB skill/router instructions;
• point the OpenWiki-managed AGENTS.md and CLAUDE.md blocks to openwiki/quickstart.md;
• stop instructing agents to read a complete global concept catalog;
• require source/test verification for implementation claims;
• allow normal coding agents to improve durable wiki knowledge;
• ensure updates to wiki content remain reviewable in the same PR as code where appropriate.

Phase 4 — lifecycle automation

• add a deterministic installation/configuration procedure;
• add the normal openwiki code --update --print command;
• add CI support that proposes wiki changes through a PR/MR;
• validate OKF output;
• fail clearly on invalid bundles;
• avoid direct pushes from automated wiki maintenance;
• store the last successful source revision;
• verify no-op behavior;
• document model/provider selection without committing credentials.

OpenWiki currently ships example GitHub Actions, GitLab CI and Bitbucket Pipelines update workflows. OpenWiki README

Phase 5 — retire the existing mandatory pipeline

After successful evaluation:

• remove OpenKB as a mandatory dependency;
• remove the .openkb-project/raw/ source-mirroring lifecycle;
• remove deterministic .py/.ts-to-Markdown duplication;
• stop running openkb recompile --all;
• remove Graphify report ingestion;
• remove the old 500-concept global index;
• keep the old wiki only as temporary migration evidence, then archive or delete it.

Phase 6 — decide Graphify’s optional status

Run separate tests for questions such as:

• “Who calls this function?”
• “What modules depend on this package?”
• “What is the impact radius of changing this interface?”
• “What path connects these two components?”
• “Which symbols are structurally central?”

If normal harness source tools are sufficient, remove Graphify entirely.

If Graphify materially improves those cases:

• keep it as an optional structural-navigation integration;
• expose scoped graphify query or MCP usage;
• do not require agents to read GRAPH_REPORT.md on every task;
• do not feed the report into OpenWiki by default;
• treat the graph as derived structural state, not canonical semantic memory.

---

Acceptance criteria

The migration should not be accepted only because the OpenWiki output looks cleaner. It should satisfy measurable requirements.

Memory shape

• quickstart.md is a compact router, not an exhaustive content dump.
• The initial wiki contains a small number of substantive pages.
• Pages correspond to architecture, domain, workflows, operations, testing or other durable concerns—not individual source files by default.
• Each concept has one identifiable canonical home.
• Repeated explanations are linked rather than copied.
• The repository source is not mirrored wholesale into Markdown.
• Existing authoritative documentation is linked or synthesized rather than duplicated.
• Every non-reserved .md file has parseable YAML frontmatter.
• Every concept frontmatter block contains a non-empty type.
• Optional OKF metadata is retained or deterministically normalized without deleting unknown producer-defined keys.
• Reserved index.md and log.md files conform to their OKF-defined structures.

Editability and durability

• The committed openwiki/ directory is the canonical memory.
• Humans and coding agents can edit semantic page bodies directly.
• Accurate manual edits survive normal update runs.
• openwiki/INSTRUCTIONS.md remains user-owned and is consumed by code mode.
• Changes are reviewable through ordinary Git diffs.
• Automated updates never push directly without review.
• No-op updates do not alter the bundle.
• Mechanical metadata does not create noisy timestamp-only diffs.
• Frontmatter normalization does not erase valid producer-defined metadata.
• Manually added conformant concept pages remain present unless an update has an evidence-backed reason to remove them.

Incremental maintenance

• Small source changes produce small documentation diffs.
• Unrelated pages remain byte-identical where possible.
• Deleted behavior is removed from the relevant wiki page.
• Renamed or moved components update references without broad wiki rewrites.
• Documentation-only changes can update the wiki without requiring full source rediscovery.
• Update time and token use are materially below OpenKB full recompilation.

Agent usefulness

Prepare at least 30 representative questions/tasks covering:

• architecture;
• domain behavior;
• end-to-end workflows;
• configuration;
• error handling;
• testing;
• extension points;
• code-change impact;
• project rationale.

Compare:

1. source tools only;
2. current OpenKB/Graphify bundle;
3. OpenWiki OKF;
4. OpenWiki OKF plus optional Graphify queries.

Record:

• correctness;
• files ultimately inspected;
• time to identify the correct subsystem;
• number of tool calls;
• prompt/input tokens;
• wiki pages opened;
• stale or contradicted claims;
• hallucinated symbols;
• whether the agent used the wiki or bypassed it;
• whether the wiki reduced raw-source exploration.

The OpenWiki migration should improve context efficiency without reducing answer or implementation correctness.

---

Risks and open questions

1. OpenWiki OKF support is not merged yet

Do we wait for OpenWiki issue #84 to be closed by PR #263, or temporarily pin the PR’s current reviewed commit?

2. Manual edit preservation is prompt-enforced

How reliably does OpenWiki preserve manually curated content and conformant producer-defined frontmatter across:

• small updates;
• cross-cutting changes;
• model changes;
• prompt changes;
• page moves and consolidations?

This must be tested explicitly.

3. Initial exploration cost can vary

OpenWiki is an autonomous repository explorer rather than a deterministic AST-first analyzer. OpenWiki issue #51 reports approximately 12× cost variance between repeated initial runs of the same repository. OpenWiki PR #273 proposes a --max-iterations guard that bounds a run by LangGraph graph steps.

We should define:

• a supported model;
• a maximum iteration/work budget;
• a maximum acceptable initial cost;
• failure/retry behavior;
• whether a local repository map should be supplied as optional evidence.

4. Lack of native structural graph

OpenWiki may miss relationships that a deterministic AST/LSP graph exposes directly.

We need to determine whether:

• normal Claude Code/Codex source discovery is sufficient;
• Graphify remains useful as optional runtime tooling;
• another lightweight structural index should replace it;
• none of this is necessary for the semantic-memory objective.

5. Migration of valuable existing knowledge

The existing OpenKB wiki may contain useful synthesis and explorations.

It should not be copied wholesale into the new wiki, because doing so would preserve its duplication and taxonomy problems.

A migration procedure should:

1. initialize OpenWiki from current repository evidence;
2. compare the new wiki with the old bundle;
3. identify valuable rationale, decisions or cross-cutting explanations absent from the new wiki;
4. curate those items into the appropriate canonical OpenWiki pages;
5. discard redundant concepts and source paraphrases.

6. index.md versus quickstart.md

The OKF PR mechanically owns reserved indexes. The project should explicitly define:

• quickstart.md as the semantic entry point;
• index.md as the OKF inventory/progressive-disclosure structure;
• AGENTS.md and CLAUDE.md as minimal routing and behavior contracts.

7. Generated versus curated content

OpenWiki does not impose a hard generated/curated directory split.

Do we need:

• an explicit frontmatter field indicating provenance;
• a convention for manually curated sections;
• a claim/evidence format;
• or is normal Git ownership plus INSTRUCTIONS.md sufficient?

The preference should be to avoid adding complexity unless testing demonstrates a real need.

8. OKF frontmatter ownership and preservation

PR #263 makes frontmatter code-owned to guarantee conformance, while the OKF specification permits producer-defined fields and recommends preserving unknown keys during round-tripping.

The proof of concept must verify that deterministic normalization:

• always adds the required non-empty type;
• keeps concept bodies directly editable;
• does not remove valid custom metadata;
• handles manually added concept pages;
• respects the special rules for index.md and log.md;
• leaves no-op bundles byte-identical.

---

Proposed decision

Proceed with an OpenWiki proof of concept and treat it as the preferred migration target.

The expected end state is:

Mandatory:
- OpenWiki code mode
- OKF v0.1 output
- openwiki/ committed as canonical memory
- compact AGENTS.md/CLAUDE.md → quickstart.md routing
- Git-reviewed incremental updates

Removed from mandatory pipeline:
- OpenKB
- full source-to-Markdown conversion
- recompile --all
- global Graphify report ingestion
- 500-concept flat index

Optional:
- Graphify or another structural code index for exact graph-native queries

The migration should be finalized only after the edit-preservation, OKF-conformance, incremental-update, cost and agent-usefulness acceptance criteria have been tested on both this project and at least one large mixed Python/TypeScript repository.

---

References

Specifications and tools

• Open Knowledge Format v0.1 specification
• OpenKB repository and architecture
• OpenKB issue #63: QMD/text-search integration request
• OpenKB issue #72: addressable paragraph identifiers
• OpenKB issue #73: no chunking for Markdown sources
• OpenKB issue #132: configurable timeout for larger local-model workloads
• OpenKB issue #148: truncated concept updates could be committed
• OpenKB PR #161: reject malformed and truncated concept mutations
• Graphify repository
• OpenWiki repository and usage
• OpenWiki repository prompt and maintenance rules
• OpenWiki issue #44: zero-diff updates previously ran the full agent
• OpenWiki PR #57: skip unchanged update runs
• OpenWiki issue #51: repeated initialization cost variance
• OpenWiki PR #273: maximum agent-run iteration guard
• OpenWiki issue #84: request OKF output
• OpenWiki PR #263: deterministic OKF v0.1 output

Harness memory strategies

• Claude Code memory
• Codex AGENTS.md discovery and size limits
• OpenClaw memory architecture
• Hermes persistent memory

Research

• Lost in the Middle: How Language Models Use Long Contexts
• ContextBench: A Benchmark for Context Retrieval in Coding Agents
• RepoAgent: Repository-Level Code Documentation Generation
• CodeWiki: Automated Repository-Level Documentation at Scale
• Code-Craft / Hierarchical Code Graph Summarization
• RepoDoc: Knowledge-Graph-Based Documentation and Incremental Updates
• Codebase-Memory: Tree-Sitter-Based Knowledge Graphs via MCP