Ask HN: How do you maintain personal annotations for code you don’t control?

I spend a lot of time reading and understanding codebases that I have no control over (open source libraries, internal legacy systems, etc.). As I build understanding, I need to document my insights, gotchas, and mental models – but these notes are purely personal and should not be part of the actual codebase.

My challenges:

1. These annotations must be tightly coupled to specific locations in the source code (specific functions, variables, or even specific lines)

2. The underlying code is constantly changing (new versions, updates from maintainers) which breaks the connection between my notes and the code

3. My notes are private – they include half-formed thoughts, questions, and sometimes critical observations that are not appropriate as public comments.

4. I want to preserve this knowledge in different machines and working environment

I tried different methods: – Local IDE bookmarks (lost between sessions) – Separate markdown files (hard to maintain proper code references) – Private forks with comments ( becomes unsustainable while the source changes)

I wonder how others have solved this problem. Do you have a systematic approach to maintaining personal annotations in code that you do not control? How do you handle the challenge of code development while keeping your notes relevant?

Would especially love to hear from people who work with large codebases or those who often need to dive deep into external dependencies.