# How VitaeContext is built

This document explains the thinking behind VitaeContext: the problem it targets, the agentic-AI concepts it deliberately applies, the knowledge-graph structure that holds it together, and how that design has evolved release by release.

It is written for a reader who wants to understand the project quickly, including engineers and recruiters evaluating the work, without reading the whole codebase. For the maintainer-facing edit map, see [architecture-map.md](./.assets/docs/architecture-map.md). For the public overview, see [README.md](./README.md).

## At a glance

- **What it is:** a standard Agent Skills bundle and stateless MCP server that integrates into AI coding assistants (Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, Cursor, Windsurf, Roo Code, IBM Bob, Grok) and helps a person build and maintain a private, reusable source of truth about their career.
- **The problem:** most agents can already rewrite a CV or a bio, but the output drifts between tools, invents facts, and ignores platform constraints. Consistency and grounding are the hard parts.
- **The core idea:** use a compact Career Context file for fast positioning and an optional, separate VitaeGraph for deep hierarchical records. Skills and downstream tools progressively load only the private context needed for a task.
- **What makes it interesting:** the project is not a prompt collection. It is a small system that applies current ideas from agentic AI, an LLM-readable knowledge layer, progressive context loading, a cross-referenced knowledge graph, explicit evidence labeling, and Model Context Protocol (MCP), shipped as a validated, versioned package.

## Agentic-AI concepts applied

VitaeContext is, in part, a place to apply and pressure-test ideas from the agentic-AI field. Each concept below is implemented in the repository, not just described.

The following table maps each concept to its origin and to where it lives in the source tree.

| Concept | One-line idea | Where it lives |
| --- | --- | --- |
| Career Context file | A private `AGENTS.md` for a person: verified facts, stated goals, growth direction, and constraints an agent reads before writing | [`vitaecontext-build`](./skills/vitaecontext-build/SKILL.md) |
| VitaeGraph | A separate local Markdown graph of deep hierarchical career records, containment and cross-record relationships, and deterministic retrieval artifacts | [`vitaegraph/`](./vitaegraph/), [`vitaecontext-vitaegraph`](./skills/vitaecontext-vitaegraph/SKILL.md) |
| Stateless MCP Server | Standard Model Context Protocol interface allowing any agent workspace to query private Career Context and VitaeGraph without repo file copies | [`src/mcp/`](./src/mcp/), [`mcp/`](./mcp/), [`bin/vitaecontext-mcp.mjs`](./bin/vitaecontext-mcp.mjs) |
| LLM Wiki | A knowledge base a maintainer agent compiles from sources and keeps current, read by runtime agents rather than re-derived per query | [`*/wiki/`](./skills/vitaecontext/wiki/vitaecontext.md), [`llms-full.txt`](./llms-full.txt) |
| Progressive disclosure | Load one module, then only the references and wiki a task needs | `## Wiki context` and token-discipline sections in each `SKILL.md` |
| Markdown knowledge graph | Cross-referenced `.md` files with one entrypoint and explicit edges | [`references/`](./skills/vitaecontext/references/) link graph, [`llms.txt`](./llms.txt) |
| Evidence and confidence labels | Mark each claim as verified, inferred, or needing evidence | `Boundaries` sections and `wiki/` confidence metadata |
| One source, many adapters | Keep one portable source of truth in `skills/`, generate or link per-provider layouts | [`skills/`](./skills/) plus [`providers/`](./providers/) |

### Career Context file as an `AGENTS.md` for a person

Developers already accept that a repository should carry a context file so an agent understands the codebase before editing it. VitaeContext applies that pattern to a career: a private Markdown file holds verified identity facts, roles, projects, metrics, links, target roles, growth direction, evidence boundaries, claims to avoid, and positioning. Agents and downstream tools read that file first, then adapt the same facts and direction to each task. This keeps output consistent across surfaces instead of rebuilding a professional history in every chat.

### VitaeGraph as the deeper career graph

VitaeGraph avoids forcing every detail into the compact context file. Stable `type:slug` records model projects and roles in dedicated folders, with thesis and university courses nested under their degree. Explicit parent and cross-record links preserve both hierarchy and graph traversal, while `VITAEGRAPH.md` and `index.md` provide progressive retrieval. The CLI validates structural references and builds deterministic graph and lexical JSON under `.generated/`; it does not authenticate real-world claims or guarantee retrieval quality.

### Model Context Protocol (MCP) Integration

With the native MCP server implementation, agents operating across multiple client tools (Claude Desktop, Claude Code, Cursor, Windsurf, Roo Code, IBM Bob, Grok) can instantly read resources like `career-context://current` and `vitaegraph://index`, execute tools like `get_career_context` and `search_vitaegraph`, and invoke prompts like `cv_tailoring` directly without needing repository-level duplication.

### LLM Wiki: knowledge the model reads, not writes

The wiki layer follows the LLM Wiki framing associated with Andrej Karpathy: a maintainer agent compiles knowledge from official sources and keeps it current, and runtime agents read that compiled knowledge rather than re-deriving it from training data on every query. Without it, an agent guesses platform constraints, ATS parser behavior, field limits, and ranking signals, and produces confident but wrong advice. Each module ships `wiki/` entries with canonical definitions, platform constraints, known failure modes, and review dates, bundled for tools as [`llms-full.txt`](./llms-full.txt).

This adapts Karpathy's design to a shipped package. His LLM Wiki is a personal, ever-growing second brain an agent accumulates from a user's own ingested sources; VitaeContext instead ships a curated, versioned knowledge pack about external platform behavior, refreshed by the maintainer-only `vitaecontext-wiki-maintenance` skill (ingest and lint) rather than mutated during end-user sessions. It keeps the faithful core, compile-once and keep-current instead of per-query retrieval, while deliberately dropping per-user accumulation that does not fit a distributed package.

### Progressive disclosure and token discipline

Loading every skill into context is wasteful and noisy. Each `SKILL.md` declares, in a `## Wiki context` section, exactly when deeper wiki or reference files should be loaded, so an agent pulls detail only when the current task needs it. The orchestrator routes a request to a single module by default and asks for the smallest missing input set rather than demanding every asset upfront.

### A Markdown knowledge graph

The repository is organized as a navigable graph of Markdown files rather than a flat folder. A single runtime entrypoint, the root wiki, points to module skills, which point to their references and wiki entries, which point to human-readable playbooks and source notes. The edges are explicit relative links, so both humans and agents can traverse from a broad question down to a specific constraint without loading everything.

### Evidence and confidence labeling

Career advice is only useful if its certainty is visible. Cross-surface output labels major claims as verified, from context, from a supplied source, official or current source, inference, needs evidence, or inaccessible. Wiki entries carry confidence values and `last_reviewed` dates, and the `doctor` command validates that metadata. The goal is to separate documented platform behavior from inference instead of presenting everything as fact.

### One portable source, thin provider adapters

Runtime methodology lives once in [`skills/`](./skills/). Provider folders stay thin: install notes, command wrappers, and metadata. The export CLI generates each provider's required layout from the single source, so the same methodology installs across many environments without separate copies drifting out of sync.

## The knowledge graph

The intended read path is hierarchical. A broad question enters at the root and narrows to one module and one constraint, instead of loading the whole system.

```mermaid
flowchart TD
  CTX["Career Context file (private source of truth)"]
  VG["VitaeGraph (private hierarchical career graph)"]
  MCP["MCP Server: stdio JSON-RPC 2.0"]
  README["README.md"]
  ROOT["root runtime wiki: vitaecontext/wiki/vitaecontext.md"]
  SKILL["vitaecontext-(module)/SKILL.md"]
  REF["references/*.md"]
  WIDX["wiki/index.md"]
  WKNOW["wiki/knowledge.md"]
  HUB["hub/(module)/README.md"]
  SRC["hub/(module)/sources.md"]
  LLMS["llms.txt and llms-full.txt"]

  README --> ROOT
  README --> HUB
  HUB --> SRC
  ROOT --> SKILL
  ROOT --> LLMS
  SKILL --> REF
  SKILL --> WIDX
  WIDX --> WKNOW
  CTX -. read before writing .-> SKILL
  VG -. selected records .-> SKILL
  MCP -. provides resources and tools .-> CTX
  MCP -. provides resources and tools .-> VG
```

Two properties matter here. First, there is one entrypoint: the root wiki decides which module to load before any module detail is read. Second, the deepest knowledge, module `wiki/knowledge.md`, is only reached when a task actually needs it, which keeps routine work cheap in context.

## How the design evolved

The project is also a record of continuous study: each release line adopted a new idea once it proved useful. The full history is in [CHANGELOG.md](./CHANGELOG.md); the summary below traces the concepts rather than the patches.

- **0.1.x, foundations.** Shipped the package with tag-based npm publishing, a guided context-file template, install manifests, and a `doctor` validation command. The bet here was context-first work plus reproducible packaging.
- **1.5.x, distribution as adapters.** Hardened multi-provider install and export, added the Gemini-compatible extension layout and the Antigravity plugin layout, and kept one source of truth behind thin adapters.
- **1.6.x, the knowledge layer.** Added the LLM Wiki layer for every module, the root self-description, conditional wiki loading, shared evidence labels, and `llms.txt` and `llms-full.txt`. This is where the project became a navigable knowledge graph rather than a set of prompts.
- **1.7.x, operational rigor.** Added a manifest-driven lifecycle to the CLI: `update` compares an installed bundle against the npm registry, and `uninstall` removes exactly what an install created. Reproducibility and clean removal became first-class.
- **1.8.x, groundedness and direction.** Added weighted triage scorecards (`audit-scoring.md`), persona lenses, self-review procedures, career direction & goals targeting in the context builder, and the tokenless GitHub public-profile fetcher.
- **1.9.x, the deep career graph.** Added VitaeGraph as an optional structured subsystem with hierarchical degree, course, thesis, project, role, and certification records, deterministic local JSON indexes under `.generated/`, and dedicated `graph init/validate/index` commands.
- **2.0.0, VitaeContext rebranding.** Repositioned the umbrella identity from AgentKit SEO to VitaeContext (career-context infrastructure for grounded AI work), retaining backwards-compatible forwarding aliases and the `agentkit-seo` compatibility package.
- **2.1.0, Career Context lifecycle & transactional installation.** Shipped `context init/validate/summary` CLI lifecycle with JSON diagnostics and bounded task packets, added transactional multi-provider installation with automatic preflight conflict detection and rollback, and packaged the native Codex plugin marketplace.
- **2.2.0, standard architecture & MCP.** Migrated to open Agent Skills root standard (`skills/`), unified binaries under `bin/`, native ESM engine in `src/`, added 5 new provider adapters (Cursor, Windsurf, Roo Code, IBM Bob, Grok), and delivered a native Model Context Protocol (MCP) server for stateless cross-project career context access.

## Sources and influences

These are influences rather than guarantees. VitaeContext does not claim ranking outcomes; it applies documented patterns and labels uncertainty.

- The LLM Wiki framing, knowledge the model reads rather than writes, is associated with Andrej Karpathy's commentary on building knowledge for language models.
- The context-file pattern follows the repository `AGENTS.md` and `CLAUDE.md` convention for giving agents project context before they act.
- Progressive disclosure follows the agent-skill design idea that an agent should load instructions and reference material only when a task needs them.
- Model Context Protocol (MCP) specification by Anthropic provides a standardized open transport for connecting AI models to private data sources and tools.
- The audit scoring pattern (weighted categories rolled into a 0-100 band with a fix-first ranking) is adapted from open generative-engine-optimization tooling such as the geo-optimizer skill, and used here strictly as an internal prioritization heuristic, not a platform metric.
- `llms.txt` and `llms-full.txt` follow an emerging community convention for exposing an AI-readable map of a site or package.

---

See also: [README.md](./README.md), [architecture-map.md](./.assets/docs/architecture-map.md), [project.md](./.assets/docs/project.md), and [MAINTAINING.md](./MAINTAINING.md).