[FEATURE]: Advanced Dual-Scope Memory System for OpenCode

[furqanahmadrao]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

📋 Summary

I have developed and tested a robust Memory System for OpenCode that solves the issues of context pollution, manual file management, and unsafe edits. This system introduces a Dual-Scope Architecture (Global vs. Project), ID-Based Management, and Automatic Templating.

I propose integrating this system (or similar logic) into OpenCode to transform it from a stateless CLI into a persistent, context-aware Engineer.

---

🛑 The Problem

Currently, managing long-term context in OpenCode is manual and fragile:

1. Global Pollution: Saving project-specific facts (e.g., "This app uses Vite") to the global AGENTS.md clutters the agent's brain for all future sessions.
2. Unsafe Edits: Asking the AI to "remove the memory about testing" often leads to fuzzy text matching that deletes the wrong lines.
3. Context Amnesia: Starting a new project requires manually teaching the agent the architecture every time, or manually creating a ./AGENTS.md file.

---

🛠️ The Solution: Dual-Scope Memory Engine

I have built a custom toolset (memory.ts) and Agent Protocol that implements the following architecture:

1. Dual-Scope Context

The system distinguishes between User Wisdom and Project Facts.

Scope	Location	Purpose	Example
Global	~/.config/.../AGENTS.md	User preferences, Life lessons	"Always use Dark Mode", "I prefer concise code"
Project	./AGENTS.md	Architecture, Tech Stack, patterns	"Auth is handled by Clerk", "API is at /v1"

Why this matters:

• Switching projects gives the Agent a "Fresh Brain" for code, but keeps the "Personality" of the user.
• No more "hallucinating" React code while working in a Vue project.

2. ID-Based Management (CRUD)

Instead of fuzzy text search, every memory is assigned a deterministic short-hash ID (e.g., a1b2).

• Read: Returns [ID:a1b2] - Content...
• Update: memory_update(id='a1b2', content='...') → Atomic, safe updates.
• Remove: memory_remove(target='a1b2') → 100% precision deletion.

3. Smart Auto-Templating

If a user asks to save a project fact ("Remember this stack") and no ./AGENTS.md exists, the tool automatically initializes the file with a professional template:

# 📂 Project Context: [Name]
## 🏗️ Architecture
## 📝 Code Standards
## 🧠 Project Context System (Auto-managed)

4. Protected "Safe Zones"

The tool respects a specific block in the markdown file:

<!-- MANAGED BY TOOLS - DO NOT EDIT MANUALLY -->
   [... Memory Tool only touches lines here ...]
<!-- END MEMORY SYSTEM -->

This ensures the tool never overwrites the user's manual instructions or custom rules outside this block.

---

🧠 The Workflow

1. User: "Remember this is a Next.js app."
2. Agent: Detects this is a code fact → Selects scope='project'.
3. System: Checks for ./AGENTS.md. If missing, creates it with the Template. Saves memory.
4. Result: Next session, the Agent reads ./AGENTS.md and instantly knows the stack.

---

🎯 Impact

This transforms OpenCode from a "Smart CLI" into a "Senior Partner" that:

1. Remembers your preferences everywhere (Global).
2. Understands your specific project deeply (Project).
3. Manages its own knowledge base safely (ID/Protected Blocks).

I have been using this system successfully to manage complex refactors and architecture planning. I believe it would be a valuable standard feature or official plugin for the community.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Server Registry & Auto-Discovery for Persistent Sessions #8948: Server Registry & Auto-Discovery for Persistent Sessions - addresses persistent agent state across sessions
• [FEATURE]: Allow pinning important instructions/messages per session to keep them after compaction. #8932: Allow pinning important instructions to keep them after compaction - similar context preservation concept
• [FEATURE]: adopt .agents as default project directory #8919: Adopt .agents as default project directory - related to standardized project-scoped agent configuration
• [FEATURE]: Hot-reload agents, skills and commands. #8751: Hot-reload agents, skills and commands - addresses dynamic knowledge management
• [FEATURE]: support config.d/ directory for modular configuration #9062: Support config.d/ directory for modular configuration - addresses project-level configuration management
• [FEATURE]: Allow custom skills directories #8533: Allow custom skills directories - related to project-scoped skill management

Feel free to ignore if none of these address your specific case.