{"slug": "thoughts-a-skill-and-plugin-for-enhanced-long-living-memory", "title": "Thoughts: A skill and plugin for enhanced long-living memory", "summary": "A new open-source project called 'thoughts' provides coding agents with a selective, durable memory system that survives context loss by maintaining a searchable THOUGHTS.md scratchpad for non-obvious project knowledge. Created by EDM115, the project includes a portable agent skill and an optional Codex plugin that writes only high-value constraints, failed approaches, and implementation tradeoffs while excluding routine actions and already-documented facts. The system is designed to prevent agents from repeating costly work across sessions without retaining noise or sensitive data.", "body_md": "## Things Heard, Observed, Unclear, Guessed, Hacked, Tracked, or Suspected : A living document about non-trivial details\n\n**Selective project memory for coding agents, durable enough to survive context loss, disciplined enough not to become a log**\n\nLong agent sessions produce valuable details that rarely belong in polished documentation yet : undocumented constraints, failed approaches, implementation tradeoffs, unresolved risks and the one strange fact that will save an hour tomorrow. Context compaction, a new thread, or a different agent can erase them.\n\nSaving every transcript is not the answer. It retains noise, may retain sensitive data and leaves the next agent to rediscover what mattered. `thoughts`\n\nmaintains a deliberately selective `THOUGHTS.md`\n\n: a searchable scratchpad for non-obvious project knowledge that is not already authoritative elsewhere.\n\nThe project has two layers :\n\n**Portable agent skill**: decides what deserves to be written, supports explicit maintenance commands and works in agent skills-compatible harnesses**Optional Codex plugin**: watches lifecycle signals and asks the main model to run the skill after high-value turns or after compaction. The hook never writes project thoughts itself\n\nA candidate 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 :\n\n```\n## 2026-07-22 — GPT-5.6 Sol Ultra — Codex — \"Build selective project memory\"\n\n- `PreCompact` command hooks cannot invoke the model. Recovery must set a signal and inject `$thoughts append` through `SessionStart(source=compact)` after compaction.\n```\n\nRoutine actions, status narration, simple answers and facts already present in README, AGENTS, plans, code, comments, tests, or issues stay out.\n\n`thoughts`\n\npreserves conclusions and useful reasoning artifacts, it does **not** request or store hidden chain-of-thought.\n\nInstall the portable skill with the skills CLI :\n\n```\nnpx skills add EDM115/thoughts\n```\n\nYou can then invoke `$thoughts`\n\nexplicitly. Harnesses that support implicit skill selection may also load it on high-value turns based on its description.\n\nAdd the marketplace and plugin to your Codex installation :\n\n```\ncodex plugin marketplace add EDM115/thoughts\ncodex plugin add thoughts@edm115\n```\n\nThe plugin hooks require Node.js 20 or newer. The standalone skill does not. Node.js from the bundled runtime should be sufficient.\n\n| Command | Behavior |\n|---|---|\n`$thoughts` |\nSame as `append` : run the semantic write gate and write only if something qualifies |\n`$thoughts append` |\nRead only the resolved `THOUGHTS.md` , use current context to add or refine the current agent's entry |\n`$thoughts init` |\nScan the repository and create a useful initial scratchpad from verified, non-obvious facts |\n`$thoughts cleanup` |\nRescan, remove obsolete agent facts, merge duplicates and compress wording while protecting user-authored notes |\n\nExplicit invocation forces a check, not a mutation. A clean no-op is a valid result.\n\nThe skill resolves one canonical location :\n\n- Reuse the sole existing\n`THOUGHTS.md`\n\nat the repository root or established developer-documentation home - Stop if multiple candidates exist, never merge or choose silently\n- Otherwise use an established developer-documentation directory such as\n`docs/`\n\n,`documentation/`\n\n, or`developer-docs/`\n\n- Fall back to the repository root, never create\n`docs/`\n\nsolely for this file\n\nDuring ordinary work, only the main orchestrator edits the file. Exploration and review subagents never write it. A subagent owning substantial delegated work may return a concise `Thought candidates`\n\nsection for the parent to vet.\n\nAgent entries are scoped by date, exposed model/reasoning level, harness and conversation. User entries use `YYYY-MM-DD — User — \"Thought recap\"`\n\n, ordinary append never edits them and cleanup reports substantial proposed rewrites instead of applying them automatically.\n\nEvery new file starts with the exact template in [ skills/thoughts/assets/THOUGHTS.md](/EDM115/thoughts/blob/master/skills/thoughts/assets/THOUGHTS.md).\n\n``` php\nflowchart LR\n    A[\"Prompt + tool activity\"] --> B{\"High-value signal ?\"}\n    B -- \"No\" --> C[\"Finish normally\"]\n    B -- \"Yes\" --> D[\"Stop continuation : $thoughts append\"]\n    D --> E{\"Semantic write gate\"}\n    E -- \"Nothing durable\" --> C\n    E -- \"Useful in a fresh thread\" --> F[\"Main agent updates THOUGHTS.md\"]\n    G[\"PreCompact\"] --> H[\"Store pending boolean only\"]\n    H --> I[\"SessionStart : compact\"]\n    I --> E\n```\n\nThe hook uses deterministic signals to request a check when a prompt explicitly asks for thoughts persistence, large-scope work uses tools, two mutations occur, eight tool calls occur, delegation starts, or compaction recovery is pending. These thresholds do not force a write, the skill's semantic gate remains authoritative.\n\n: returns a one-time continuation prompt that behaves like a new user prompt.`Stop`\n\n`stop_hook_active`\n\nprevents a continuation loop.: stores a pending boolean and allows compaction to continue. Command hooks cannot call the model here.`PreCompact`\n\n: injects developer context once after compaction, then clears the marker. A short unrelated prompt still produces no write.`SessionStart(source=compact)`\n\n: tells subagents not to edit`SubagentStart`\n\n`THOUGHTS.md`\n\nand allows candidate reporting for substantial work.\n\nThe behavior follows OpenAI's current [Codex hooks contract](https://learn.chatgpt.com/docs/hooks).\n\nHook state lives under Codex's `PLUGIN_DATA`\n\ndirectory in a file named from a SHA-256 hash of the session ID. It contains only :\n\n- turn ID\n- explicit and large-scope booleans\n- tool and mutation counts\n- delegation and thoughts-touched booleans\n- a compaction-pending boolean\n\nPrompts, assistant messages, tool inputs and outputs, source paths, transcripts, source code and `THOUGHTS.md`\n\ncontents are never persisted. Corrupt or unavailable state fails open so Codex can continue. Writes use a temporary sibling file followed by rename to avoid partial JSON.\n\nPlugin-bundled command hooks are executable code. Codex therefore requires users to review and trust the exact hook definition before it runs and changed hooks require review again.\n\n- Implicit skill selection is model-controlled. Explicit\n`$thoughts`\n\ninvocation is the portable reliable path, the Codex plugin adds lifecycle enforcement where hooks are supported. `PreCompact`\n\ncannot send a model prompt. It can only run deterministic code, stop compaction, or set state, this plugin deliberately recovers after compaction instead of blocking it.- Mechanical thresholds are heuristics. They may request a semantic check after work that ultimately produces no entry.\n- Tool hooks cover supported local function-tool paths, not every possible hosted or specialized tool.\n- Conversation titles, model names and reasoning levels depend on what the harness exposes, the skill never invents missing metadata.\n- Lifecycle automation is Codex-specific. The standalone skill remains usable elsewhere.\n\nThe hook, tests and validator use Node built-ins only and have no third-party runtime or development dependencies.\n\n```\npnpm test\npnpm validate\n```\n\nCI runs both commands on Node.js 20 and 22. Tests cover classification, thresholds, trivial-turn skipping, thoughts-touch suppression, stop-loop prevention, compaction recovery, state corruption, privacy, subagent context, the command entrypoint and package structure.\n\nFocused bug reports and pull requests are welcome. Please keep new persistence behavior selective and include regression coverage.\n\n[MIT](/EDM115/thoughts/blob/master/LICENSE) © EDM115", "url": "https://wpnews.pro/news/thoughts-a-skill-and-plugin-for-enhanced-long-living-memory", "canonical_source": "https://github.com/EDM115/thoughts", "published_at": "2026-07-22 12:38:17+00:00", "updated_at": "2026-07-22 12:52:32.923264+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["EDM115", "thoughts", "Codex"], "alternates": {"html": "https://wpnews.pro/news/thoughts-a-skill-and-plugin-for-enhanced-long-living-memory", "markdown": "https://wpnews.pro/news/thoughts-a-skill-and-plugin-for-enhanced-long-living-memory.md", "text": "https://wpnews.pro/news/thoughts-a-skill-and-plugin-for-enhanced-long-living-memory.txt", "jsonld": "https://wpnews.pro/news/thoughts-a-skill-and-plugin-for-enhanced-long-living-memory.jsonld"}}