goldmem: A Persistence Framework for Operator Instructions in Human-AI Collaborative Workflows

goldmem is an embedded instruction storage system designed specifically for AI agent workflows with human-in-the-loop participation. It addresses the structural issue of agents forgetting or repeatedly asking the same questions across multiple sessions by capturing, indexing, and enforcing references to operators' original instructions, placing the operator's time cost at the core of system design.

Current AI agent frameworks have a fundamental cost asymmetry: operator time is scarce and non-renewable, while agent computing resources are relatively cheap and scalable. However, existing frameworks often prioritize agent convenience over operator time. For example, in a 13-hour autonomous coding session in May 2026, the agent was instructed to implement a new UI according to design drafts without using legacy code. Yet, over 7 hours and 34 sprint cycles, it ignored parts of the design drafts and built an incorrect architecture, exposing the framework's lack of a mechanism to enforce instruction review and wasting operator time.

goldmem is designed around three core principles: 1. Capture rather than infer: Only content intentionally input by the operator counts as instructions; implicit rules are extracted only in special error scenarios. 2. Bi-temporal tracking: Each instruction records both effective time and recording time, preserving the complete timeline without silent overwrites. 3. Mechanical reference: Through a hook mechanism, the agent is forced to check instructions before editing files or asking questions, ensuring non-bypassability.

The storage layer uses human-readable Markdown files (trackable via git) plus the embedded graph database LadybugDB (supporting full-text search, vector similarity, etc.); instructions are strictly isolated by project, and cross-project adoption requires explicit declaration; guided initialization is supported, allowing import of relevant instructions from existing agent session histories.

Integration methods include: 1. Hook integration (e.g., Claude Code's PreToolUse hook); 2. MCP protocol server (providing tools and resources via stdio); 3. CLI shell calls (supporting commands like init, capture, inject, and their shorthand slash commands).

goldmem represents a shift in design philosophy: placing humans at the center and proposing a collaborative contract (agents must mechanically reference instructions to gain access privileges). Implications for AI engineering practice: Constraints as code (instructions are version-controlled like code), failure mode analysis (design based on real failures), and cost-aware design (explicitly accounting for human time costs).

The current v1.0-alpha version has limitations: the instruction conflict resolution mechanism needs improvement, semantic understanding needs enhancement, cross-session consistency support is insufficient, and operator experience needs optimization. Future directions include introducing complex conflict resolution, using vector similarity to improve semantic matching, enhancing cross-session consistency, and developing more visual management tools.

goldmem is an innovative solution to structural problems in human-AI collaborative workflows, changing the power balance between agents and operators through enforced instruction references. It does not aim for a perfect agent but rather builds a constraint framework to ensure operator instructions are respected, protect human time resources, and provide a new paradigm for complex AI workflows.