Skip to content

docs(memory): expand memory chapter with long-term memory, patterns and pipelines - #59

Merged
Fernando de Oliveira (fedeoliv) merged 1 commit into
mainfrom
docs/memory
Aug 6, 2026
Merged

Fernando de Oliveira (fedeoliv) merged 1 commit into
mainfrom
docs/memory

Conversation

@rottathiago

Copy link
Copy Markdown
Collaborator

What

Evolves the memory section from an introduction stub plus a storage-focused STM page into a complete chapter. All existing STM content was preserved and re-framed, not rewritten.

Pages

Page Status Content
Memory.md expanded Memory types (STM, LTM, working memory), cognitive sub-types (semantic / episodic / procedural), memory vs. knowledge sources, key principles, chapter map
Memory-Architecture-Patterns.md new Storage strategies, retrieval patterns, vendor-neutral pattern archetypes, memory scoping, trade-offs (incl. the fading memory problem), token economics, metrics
Short-Term-Memory.md extended Existing design approaches and retention kept; adds context window management, working memory assembly, session end handling, multi-channel considerations
Long-Term-Memory.md new What to persist, memory entry data model, lifecycle, relevance scoring and decay, scope decision framework, governance, security risks, operations at scale, phased roadmap
Memory-Pipelines.md new Mermaid diagrams for the retrieval, session end, and STM → LTM promotion pipelines

Also: SUMMARY.md navigation updated (the empty long-term memory entry is now filled) and the Mem0 long-term memory benchmark paper added to docs/References.md.

Highlights for reviewers

  • Relevance scoring and decay (Long-Term-Memory.md): score composed from retrieval frequency, recency, importance and confidence; last_retrieved_at / retrieval_count write-back on the read path; use it or lose it decay; and tier demotion (hot → warm → cold → archived) instead of hard deletion, with retrieval promoting entries back up.
  • Pipelines (Memory-Pipelines.md): the three flows are authored in Mermaid, each with a stage table and design notes, plus an overview showing how the read path, session-end path and promotion path connect.
  • Market implementations are abstracted into neutral pattern archetypes (auto-injected layered, on-demand tool-based, permission-trimmed retrieval, extract-and-update, self-managed tiered) rather than named vendors, with a hybrid recommendation for enterprises.
  • Technology-agnostic first, with Azure services named only as concrete examples.
  • The adoption roadmap intentionally describes phases by objective and outcome, without time estimates.

Validation

  • markdownlint clean across docs/**/*.md
  • prettier --check clean (80 cols, proseWrap: always)
  • python scripts/update_references.py reports no new links
  • All 13 Mermaid blocks verified by rendering them with mmdc
  • All internal links and heading anchors resolve

Evolve the memory section from an intro stub plus a storage-focused STM page
into a complete chapter, reusing the existing STM content.

- Memory.md: memory types (STM, LTM, working memory), cognitive sub-types
  (semantic, episodic, procedural), memory vs. knowledge sources, key
  principles and chapter map.
- Memory-Architecture-Patterns.md (new): storage strategies, retrieval
  patterns, vendor-neutral pattern archetypes, memory scoping, trade-offs
  including the fading memory problem, token economics and metrics.
- Short-Term-Memory.md: keep existing design approaches and retention, add
  context window management, working memory assembly, session end handling
  and multi-channel considerations.
- Long-Term-Memory.md (new): what to persist, memory entry data model,
  lifecycle, relevance scoring and decay with tier demotion, scope decision
  framework, governance, security risks, operations at scale and a phased
  adoption roadmap.
- Memory-Pipelines.md (new): mermaid diagrams for the retrieval, session end
  and STM to LTM promotion pipelines.
- SUMMARY.md: add the new pages and fill the empty long-term memory entry.
- References.md: add the Mem0 long-term memory benchmark paper.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really nice content, thank you Thiago Rotta (@rottathiago)!

@fedeoliv
Fernando de Oliveira (fedeoliv) merged commit 9e6a75e into main Aug 6, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants