Architecture Decisions

This page catalogs the architectural decision records (ADRs) that document key design choices in MIF. Each ADR captures the context, decision, and consequences of a significant architectural choice.

Decision Records

ADR	Title	Status	Summary
ADR-001	Cognitive Triad Taxonomy	Accepted	Adopts the cognitive triad from cognitive psychology (semantic, episodic, procedural) as the universal memory classification system, grounded in Tulving’s established research.
ADR-002	Dual Format Design	Accepted	Supports both Markdown and JSON-LD as first-class formats — Markdown for human authoring and readability, JSON-LD for machine processing and semantic web integration.
ADR-003	Obsidian Compatibility	Accepted	Adopts Obsidian-compatible conventions including YAML frontmatter, wiki-style links, block references, and folder-based organization for seamless knowledge management integration.
ADR-004	Three-Tier Trait Inheritance	Accepted	Implements a three-tier trait inheritance model (mif-base, shared-traits, domain ontologies) for reusable, composable field definitions across ontologies.
ADR-005	Underscore Namespace Prefix	Accepted	Uses underscore prefix (_semantic/, _episodic/, _procedural/) for base type namespaces to visually distinguish system namespaces and ensure predictable sort order.
ADR-006	EntityData vs EntityReference	Accepted	Defines two distinct entity patterns: EntityReference for lightweight mentions of entities in content, and EntityData for full structured ontology-typed data embedded in memories.
ADR-007	GitHub Raw URLs for Schema IDs	Accepted	Uses GitHub raw content URLs for all JSON Schema $id values, providing immediately resolvable, zero-cost hosted schema identifiers with natural git-based versioning.
ADR-008	Decay Model Rationale	Accepted	Implements a configurable memory decay model (none, linear, exponential, step) with type-specific half-life defaults, inspired by Ebbinghaus’s forgetting curve research.

Details

ADR-001: Cognitive Triad Taxonomy

Status: Accepted | Date: 2026-01-27

MIF needed a memory classification system that is universally applicable, grounded in established theory, and simple enough for practical use. The decision adopts the cognitive triad from cognitive psychology — semantic memory (facts and knowledge), episodic memory (events and experiences), and procedural memory (skills and processes). This is based on Tulving’s (1972) foundational research on memory systems. Specific sub-categorization is handled through namespace extensions rather than additional types.

ADR-002: Dual Format Design (Markdown + JSON-LD)

Status: Accepted | Date: 2026-01-27

MIF needs to serve both human authors and machine consumers. Rather than choosing one format, MIF supports both Markdown (with YAML frontmatter) and JSON-LD as first-class, semantically equivalent formats. Markdown provides familiar authoring and readability, while JSON-LD provides structured validation and semantic web compatibility. The two formats are bidirectionally convertible.

ADR-003: Obsidian Compatibility

Status: Accepted | Date: 2026-01-27

Many knowledge workers use Obsidian for personal knowledge management. MIF adopts Obsidian-compatible conventions including YAML frontmatter for metadata, wiki-style [[links]] for cross-references, ^block-id references for granular citations, and folder-based organization mapped to namespaces. This enables zero-friction integration with existing Obsidian workflows while maintaining format independence.

ADR-004: Three-Tier Trait Inheritance

Status: Accepted | Date: 2026-01-27

MIF ontologies need reusable field definitions that can be composed into entity types without repetition. The three-tier model provides: Tier 1 (mif-base) with core traits like timestamped and identified, Tier 2 (shared-traits) with common cross-domain traits like located and lifecycle, and Tier 3 (domain ontologies) with domain-specific traits. This balances reusability with extensibility through a clear inheritance chain.

ADR-005: Underscore Namespace Prefix Convention

Status: Accepted | Date: 2026-01-27

The three base type namespaces (_semantic/, _episodic/, _procedural/) use an underscore prefix to visually distinguish them from domain-specific namespaces. This ensures they sort to the top of directory listings, remain visible in all file browsers (unlike dot-prefixed directories), and signal system-level organization. Domain sub-namespaces within these remain unprefixed.

ADR-006: EntityData vs EntityReference

Status: Accepted | Date: 2026-01-27

MIF represents entities in two distinct contexts: EntityReference for lightweight pointers to entities mentioned in content (using core types like Person, Organization, Technology), and EntityData for full structured data when a memory IS an entity with domain-specific fields defined by an ontology schema. Both patterns can coexist in the same memory document.

ADR-007: GitHub Raw URLs for Schema IDs

Status: Accepted | Date: 2026-01-27

JSON Schema $id values use GitHub raw content URLs (e.g., https://mif-spec.dev/schema/mif.schema.json) instead of custom domains or URNs. This provides immediately resolvable identifiers with zero hosting infrastructure, natural versioning via git refs, and full open-source transparency. Earlier placeholder domains (mif.io, subcog.io) were replaced as they never existed.

ADR-008: Decay Model Rationale

Status: Accepted | Date: 2026-01-27

AI memory systems need mechanisms to prioritize recent/relevant memories and manage storage growth. MIF implements a configurable decay model with four types (none, linear, exponential, step) and type-specific default half-lives: P30D for semantic memories, P7D for episodic, and P14D for procedural. The model is inspired by Ebbinghaus’s forgetting curve and the ACT-R memory decay model, with reinforcement through access and explicit commands.