[FEATURE]: Native auto-memory for cross-session learning

[lleontor705]

Verification

• I searched existing issues and found related proposals: [FEATURE] Persistent Session Memory #16077, Feature Request: Model-Agnostic Memory Layer (Global & Per-Project) #8043, [FEATURE]: Advanced Dual-Scope Memory System for OpenCode #9211
• This issue adds a specific, focused implementation approach not covered in those

Problem

OpenCode has no native mechanism to persist learnings across sessions. Users have to manually add everything to AGENTS.md. Related issues (#16077, #8043, #9211) discuss this conceptually but none have an implementation PR.

Proposed Solution

A lightweight memory module that:

1. Extracts patterns from session events (repeated build commands, error+fix sequences, user corrections)
2. Stores in SQLite + auto-generates .opencode/MEMORY.md
3. Injects MEMORY.md into system prompt at session start

Configurable:

{ "memory": { "enabled": true, "auto_extract": true, "max_memory_lines": 200 } }

Why now

I'm working on a PR for this and want to link it properly per the issue-first policy.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• Feature requests must use the feature request template, which requires a verification checkbox confirming the feature hasn't been suggested before, and the title must start with [FEATURE]:
• The issue appears to be an AI-generated wall of text with an elaborate multi-phase architecture proposal — we ask that issues reflect genuine, personally-authored requests rather than AI-generated content

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

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

• [FEATURE] Persistent Session Memory #16077: Persistent Session Memory — same core concept of persisting context/learnings across sessions
• Feature Request: Model-Agnostic Memory Layer (Global & Per-Project) #8043: Model-Agnostic Memory Layer — similar memory extraction, storage, and injection architecture
• [FEATURE]: Advanced Dual-Scope Memory System for OpenCode #9211: Advanced Dual-Scope Memory System — similar persistent memory system proposal (closed)

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! It now meets our contributing guidelines. The feature request is clear, focused, and well-structured. Good luck with the PR!

[kuitos]

https://github.com/kuitos/opencode-claude-memory Take a look about this plugin, perhaps it can be helpful😃

[QuantumEdu]

Comment for Issue #20322

A structured approach to cross-session memory could significantly enhance the proposed implementation. Here's a design proposal based on effective patterns for persistent learning across AI coding sessions:

Proposed Core Operations

Primary memory functions:

• mem_save - Store observations with structured metadata (title, type, scope, topic_key, content)
• mem_search - Full-text search across all sessions with filtering
• mem_context - Retrieve recent session history and relevant observations
• mem_session_summary - Mandatory session closure with structured summary

Structured observation format:

title: Verb + what (short, searchable)
type: decision | bugfix | architecture | discovery | pattern | config | preference
scope: project | personal
topic_key: Stable key for evolving topics (e.g., "architecture/auth-model")
content:
  What: One sentence - what was done
  Why: What motivated it
  Where: Files or paths affected
  Learned: Gotchas, edge cases, decisions made (omit if none)

Proactive save triggers (auto-detected events):

• Architecture/design decisions made
• Team conventions documented
• Bug fixes completed (with root cause)
• Non-obvious discoveries about codebase
• Configuration changes or environment setup
• Patterns established (naming, structure, convention)
• User preferences or constraints learned

Mandatory session closure protocol:

## Goal
[What was being worked on]

## Instructions
[User preferences or constraints discovered]

## Discoveries
- Technical findings, gotchas, non-obvious learnings

## Accomplished
- Completed items with key details

## Next Steps
- What remains for next session

## Relevant Files
- path/to/file — [what changed/role]

Key Design Principles

1. Topic upserts - Use stable topic_key for evolving topics. Same topic → same observation updated over time, preventing duplicates.

2. Type-based organization - Filter by decision, bugfix, pattern, discovery for context-specific retrieval.

3. Scope separation - project scope persists within codebase; personal scope carries user preferences across all projects.

4. Proactive saves - Auto-detect and save immediately after important events, not requiring explicit user prompts.

Suggested Enhancements for #20322

Building on the current proposal, the implementation could include:

1. Structured observation types - Support multiple observation types beyond generic "learnings", each with appropriate metadata fields.

2. Topic key management - Auto-suggest stable keys for evolving topics (e.g., architecture decisions) to prevent duplicate observations.

3. Proactive trigger detection - Auto-detect when a save is needed (e.g., after git commit, after bug fixes, after config changes) rather than requiring explicit calls.

4. Session closure enforcement - Require a structured summary before session end to capture work context.

5. Compaction recovery - Automatically capture session summary when context is compacted to preserve work before losing context.

6. Scope-aware search - Default to project scope with option to expand to personal for broader retrieval.

Trade-offs to Consider

• Size limits: Consider per-observation size limits for performance at scale.
• Privacy: Some observations might be project-specific or contain sensitive info - scope and access controls are important.
• Duplication prevention: Implement near-duplicate detection before saving similar observations.
• Storage backend: SQLite (as proposed) vs. other solutions for FTS5 full-text search performance.

Example Use Case

Without persistent memory:

• Session 1: Fix N+1 query in UserList → knowledge lost
• Session 2: Same bug appears → wasted time re-investigating

With structured persistent memory:

• Session 1: Fix N+1 query → auto-saves observation with type: bugfix, topic_key: "database/n-plus-one"
• Session 2: mem_search("n+1") → retrieves fix immediately with What/Why/Where/Learned context

This approach would significantly reduce re-work across sessions and improve the agent's ability to learn from past interactions.

---

Let me know if you'd like more details on any specific aspect of this proposal.