edm115/thoughts

THOUGHTS is a memory system for AI coding agents. When an AI assistant works on a long coding session, it picks up useful details: failed approaches, hidden constraints, unresolved risks, implementation tradeoffs. These details rarely make it into formal documentation, but they are too valuable to lose. If the session ends, the context gets compacted, or a different agent takes over, all of that knowledge disappears. THOUGHTS solves this by maintaining a selective file called THOUGHTS.md, which acts as a searchable scratchpad for non-obvious project knowledge. The project has two layers. The first is a portable agent skill that decides what deserves to be written down and supports explicit maintenance commands. The second is an optional plugin for Codex, which is an AI coding tool. The plugin watches lifecycle signals and asks the main model to run the skill after high-value turns or after compaction. The plugin itself never writes to the thoughts file, only the main agent does that. Not everything gets saved. A piece of information passes the write gate only when a capable agent starting a fresh thread would otherwise make a worse decision or repeat costly work. Good entries capture a durable constraint and why it matters. Routine actions, status narration, simple answers, and facts already present in documentation or code are excluded. The project does not store hidden chain-of-thought reasoning. The skill supports four commands: append, which reads the existing file and adds or refines an entry, init, which scans the repository to create an initial scratchpad from verified facts, and cleanup, which removes obsolete facts, merges duplicates, and compresses wording while protecting user-authored notes. A clean no-op, where nothing qualifies for writing, is a valid result. The file location follows strict rules. The skill reuses an existing THOUGHTS.md at the repository root or an established documentation directory. If multiple candidates exist, it stops and never merges or chooses silently. Only the main orchestrator edits the file during ordinary work, while subagents can return candidate entries for the parent to review. The full README is longer than what was shown.