<!--
metadata:
  title: "Why build a personal agent context file"
  platform: "general"
  objective: "Explains the problem that a personal agent context file solves and why it outperforms the alternatives a user would otherwise rely on."
  status: "draft"
  last_updated: "2026-04-24"
  tags: ["context-file", "motivation", "workflow", "productivity"]
  agent_priority: "low"
-->

# Why build a personal agent context file

> Every time you ask an agent to write a cover letter or update your LinkedIn profile, it starts from zero — with no knowledge of who you are, what you have done, or how you want to be positioned. A personal agent context file ends that problem permanently.

---

## 1. Overview

This file explains the practical problem that a personal agent context file solves. It also covers what the file changes about the daily workflow of using an agent for career tasks, and why it outperforms the workarounds most people currently use. It is written for a human who has not yet built a context file and is deciding whether to do so. Agents loading this folder do not need to read this file to perform their tasks.

## 2. The problem: every session starts from scratch

Each time you open a new agent session and ask for a career-related output, the agent has no memory of previous conversations. It does not know your name, your degree, your work history, your strongest skills, or the role you are targeting. You have to supply that information every time. In practice, this means one of three things happens.

You paste raw text into the chat. A CV export, a LinkedIn profile dump, a copy of old cover letters. The agent works with whatever you give it. The problem is that raw text is unstructured. There is no clear separation between a course you took in 2019 and your current thesis work. There are no explicit signals about which project was most technically demanding, which role was most recent, or what your target positioning is. The agent does its best, but it is guessing at structure and priority.

You rely on the agent's memory. Some providers offer a memory feature, but it is unreliable across sessions, resets periodically, and cannot be inspected or corrected in a systematic way. You do not know what the agent actually remembers, whether it is accurate, or whether it will produce consistent outputs tomorrow.

You write a long prompt from scratch. You describe yourself every time: your background, your skills, the role you are applying for, the tone you want. This is the most reliable approach, but it is also the most wasteful. The same facts get rewritten in every session, with small variations that introduce inconsistency over time.

All three approaches produce the same outcome: generic, loosely grounded outputs that require heavy editing before they are usable.

## 3. What the context file changes

A personal agent context file is a single Markdown document you maintain in your own file system. It contains your complete professional record: education, experience, projects, skills, certifications, and languages, structured according to a consistent schema defined in [context-file-spec.md](./context-file-spec.md).

When the file exists and is up to date, the workflow for any career task collapses to three steps.

Load the context file into the agent's context window. State the task. Receive an accurate, specific output.

That is the entire process. The agent does not need to ask what degree you hold, what grade you received, which technology you used, or what the result of a project was. Every fact is already in the file, in a structure the agent can navigate without confusion.

The outputs this enables are qualitatively different. A cover letter generated from a context file names the specific project most relevant to the job description. It cites the actual grade or competition result that demonstrates the claim, and positions you precisely rather than generically. A LinkedIn About section rewrite reflects your actual current positioning, not a paraphrased version of whatever text you pasted in. A CV variant for a specific role selects and emphasises the right subset of your experience, because the full record is available for the agent to choose from.

## 4. What you can do with the file

The examples below are the kinds of prompts you write once the file exists. Each one assumes the context file is loaded into the session alongside any relevant Skill submodule.

```text
Using my context file, write a cover letter for this job description.
Target role: Senior Security Engineer. Keep it under 400 words.
Emphasize the eBPF kernel research and the Huawei PQC thesis.
```

```text
Update the About section of my LinkedIn profile based on my current
positioning in the context file. Apply the rules in the linkedin submodule.
Target audience: security research groups and senior engineering recruiters.
```

```text
Generate a one-page CV tailored for a cryptography research internship.
Use only the content from my context file that is directly relevant.
Format it for ATS compatibility following the cv-ats submodule rules.
```

```text
Using my context file, prepare five interview questions and model answers
for a security analyst role. Base the answers strictly on verified facts
in the file, not on general knowledge.
```

These are not special prompts that require new skills to write. They are the natural result of having all your facts organized in one place. The context file is the input. The Skill submodules in this repository are the rules. The agent is the executor.

## 5. Why this outperforms the alternatives

The table below compares the personal agent context file against the three workarounds described in section 2.

The approach being compared and why each falls short is summarized here.

**Copy-pasted raw text** is unstructured. Semester boundaries are invisible to the agent. Project importance is undefined. Positioning is implicit rather than declared. Every session produces slightly different outputs because the input is slightly different each time.

**Agent memory** is opaque and unreliable. You cannot inspect what the agent has retained. You cannot correct a fact that was remembered incorrectly. You cannot audit whether the output is grounded in what you actually told it. Memory also resets without notice, which means it cannot serve as a stable source of truth.

**Per-session prompts** are accurate when written carefully, but they are a maintenance burden. You are re-doing the same work repeatedly. There is no canonical version of your career record. Different sessions produce outputs that are inconsistent with each other because the prompts differ slightly each time.

The context file solves each of these problems. It is structured, so the agent can locate any fact by navigating the section tags. It is canonical, so every output is grounded in the same source of truth. It is version-controlled, so you can see exactly what changed between the version you used for one application and the version you are using now.

## 6. The file is a living document, not a one-time artifact

The context file is not something you build once and archive. It is a document you feed whenever your career changes. A new grade is confirmed: add it to the relevant course entry and update the QUICK REFERENCE block. A project is completed: add the TL;DR, the technologies, the outcome. A new role starts: add the role entry with the TL;DR and the initial scope.

Each update is small. The average update takes less time than explaining the new fact from scratch in an agent session. Over time, the file becomes a complete, accurate, and always-current record of your professional history — one that any agent can use immediately, without prompting, without clarification, without guessing.

That is the case for building it.

---

*Next step: Learn the required architecture in the [Agent context file specification](./context-file-spec.md).*
