Zhi SangMy rolePersonal design; AI-assisted maintenance
StageIn ongoing local use
Tools & methods上下文组织 / 分层导航 / Markdown / 状态维护
It started with a new conversation
I did not plan the system in its current form from the beginning.
When I started using AI, I found that a chat could only hold so much context. A new conversation did not know the current state. I had to explain it again, or spend a large part of the context rereading documents.
Could I leave the essential background and progress in files, so the next conversation would know where the work stood and what to do next?
Three files inside a project
I created a project-local .agent/ directory with three responsibilities:
| File | What it keeps |
|---|---|
| memory.md | The entry point: project basics, material indexes and maintenance rules |
| progress.md | Current progress, active tasks, problems and next steps |
| completed_tasks_log.md | Completed tasks and their records |
The files also contain maintenance conventions. The AI uses the stage of the work to decide where to write: progress as a task advances, history when it finishes, and the entry when stable information or indexes change.
A new chat reads the entry and current progress first, then follows the history only when needed. I can continue without explaining the project from the beginning each time.
More tools and projects led to a Hub
As my tools and projects grew, work in one project often needed something from another.
Knowing the current directory was no longer enough, so I added a shared Hub index. At the beginning of a conversation, the AI can get an overview of my projects, available tools and the locations of relevant material.
For example, while preparing course notes, it can find the document-to-image or transcription tools through the shared entry, then return to the course directory to finish the work.
The shared index grew too
The AI does not need every detail on every task. Putting everything in one file created another problem.
I added layered indexes. Each directory’s .agent/memory.md navigates its own level; the parent mainly points to the next level, which maintains the internal detail.
Hub → Domain entry → Project entry → Documents relevant to the current task.
The AI starts with an overview and follows the relevant path. Parents keep the purpose, keywords and next entry; detailed files, commands and conventions stay with the directory they belong to. This reduces both unrelated loading and duplicate maintenance.
Keep the records moving with the work
Files are useful only when their contents keep up with the project.
I continued refining the rules: update the current state when work starts or advances; write history when a stage finishes, then refresh active tasks and handover information. Longer architecture and interface material belongs in context/, learning material in docs/, and retired material is archived when worth retaining.
I design these responsibilities and conventions, and the AI helps carry them out in everyday work. When indexes get too long, material is duplicated or progress becomes stale, I adjust the structure. This website uses it too.
It has become a foundation for how I work with AI: provide the necessary background, make related tools discoverable, and leave the next conversation somewhere to continue.