Standardizing self-updating institutional memory using MDX, hierarchical compression, and semantic retrieval.

Open Memory Spec (OMS) — RFC v0.1

Status: Draft · Date: 2025-09-06

Motivation

Institutional knowledge is often lost across tickets, PRs, reviews, chat, and wikis. Static docs rot; teams forget why decisions were made. OMS defines a universal, open format and lifecycle for capturing, compressing, and retrieving organizational memory so AI systems can keep documentation accurate and alive.

Principles

• Open Format: Knowledge stored as MDX with YAML frontmatter.
• Hierarchical Memory: Raw → Summary → Meta-summaries.
• Composable Sources: Tickets, PRs, docs, Slack, email.
• Semantic Retrieval: Embeddings over chunks for search.
• Auditable: Human-readable MDX, version-controlled.
• Extensible: Agents and tools plug into the same standard.

File Format: MDX + Frontmatter

Each memory entry is an .mdx file with frontmatter. Example:

---
id: "mem-1234"
type: "ticket" # ticket | conversation | doc | faq | summary | meta
source: "github"
ticket: "TCK-234"
pr: 57
level: 0 # 0=raw, 1=summary, 2=meta
date: "2025-09-06"
tags: ["beta", "routing", "ai-fix"]
---

### Problem
Users reported incorrect routing when a beta flag was active.

### Solution
AI generated a fix (branch: codec/fix-beta-routing). PR reviewed and merged.

### User Docs
> To join beta, go to Settings → Beta Features and opt in.

Memory Levels

• Level 0 (Raw): Source transcripts, ticket details, diffs.
• Level 1 (Summary): Daily/weekly compression across multiple entries.
• Level 2 (Meta): Quarterly/annual summaries for strategic memory.

APIs

• GET/POST /api/context/search — semantic search.
• POST /api/context/rollup — compress raw → summary → meta.
• GET /api/context/export — export MDX archive.

Compression Pipeline

A ContextCompressor job periodically:

• Groups N raw docs → produces an MDX summary.
• Recursively compresses summaries into meta-summaries.
• Updates a vector index for retrieval.

Vector Indexing

Every MDX doc is chunked and embedded into a vector DB (pgvector, Pinecone, Weaviate). Retrieval merges raw and compressed layers for high signal, low token cost.

Extensibility

Agents (DocAgent, PRAgent, FAQAgent) both consume and produce OMS MDX. New frontmatter fields can be added via RFCs.

Governance

• License: Apache-2.0
• Process: RFCs via GitHub issues and PRs
• Roadmap: Public, community-driven

Vision

OMS becomes the standard for AGI memory — like Git for code and Kubernetes for orchestration, OMS standardizes knowledge.