Namespace Model

Namespace Structure

Namespaces use a flexible scoping model with reserved prefixes for cross-organization sharing:

{root}/{scope}+[/{session}]

Where {root} is either:

• Organization name - private to that organization
• Reserved prefix - special namespace with defined semantics

Reserved Namespace Prefixes

Names beginning with underscore (_) are reserved for special namespaces:

Prefix	Visibility	Description
_public	Global	Publicly accessible by anyone
_shared	Negotiated	Cross-organization sharing with explicit agreements
_local	Local only	Never synchronized or exported
_system	Implementation	Reserved for system/implementation use

Examples:

# Public knowledge (globally accessible)
_public/python/async-patterns
_public/react/hooks-best-practices
_public/security/owasp-top-10

# Shared between organizations (requires agreement)
_shared/cncf/kubernetes/patterns           # CNCF member consortium
_shared/acme+bigcorp/integration-api       # Bilateral agreement
_shared/industry-healthcare/hipaa-compliance

# Organization-private (default)
acme-corp/jane-doe/preferences
acme-corp/project-x/architecture-decisions
acme-corp/team-frontend/patterns

Flexible Scopes Within Organizations

Within an organization, scopes are peer-level - users, projects, teams, and other organizational units are treated equally:

{organization}/{scope}+

Examples:
- acme-corp/jane-doe                    # user scope
- acme-corp/project-x                   # project scope
- acme-corp/team-frontend               # team scope
- acme-corp/jane-doe/project-x          # user + project (order flexible)
- acme-corp/project-x/jane-doe          # same as above
- acme-corp/team-frontend/project-x     # team + project

Key principle: Within an organization, there is no enforced hierarchy between users, projects, or teams. The path segments represent scope intersection, not parent-child relationships.

Shared Namespace Agreements

The _shared prefix requires explicit agreements between organizations:

.mif/shared-agreements/acme+bigcorp.yaml

id: acme+bigcorp
type: bilateral
parties:
  - acme-corp
  - bigcorp-inc
created: 2026-01-15T00:00:00Z
namespaces:
  - _shared/acme+bigcorp/integration-api
  - _shared/acme+bigcorp/data-formats
access:
  read: [acme-corp, bigcorp-inc]
  write: [acme-corp, bigcorp-inc]

For consortiums or communities:

.mif/shared-agreements/cncf.yaml

id: cncf
type: consortium
admin: cncf-foundation
members:
  - google
  - microsoft
  - redhat
  # ... (member list or reference)
namespaces:
  - _shared/cncf/*
access:
  read: members
  write: approved-contributors

Custom Reserved Prefixes

Implementations MAY define additional reserved prefixes following the underscore convention:

.mif/config.yaml

reserved_prefixes:
  _archive:
    description: Archived memories (read-only)
    access: read-only
  _experimental:
    description: Experimental/unstable memories
    ttl: P30D
  _imported:
    description: Memories imported from external systems
    provenance_required: true

Namespace URIs

Full URI form for cross-system references:

mif://{domain}/{namespace}/{memory-id}

Examples:

• mif://github.com/zircote/acme-corp/project-x/550e8400...
• mif://registry/_public/python/async-patterns/abc123...
• mif://local/_local/scratch/memory-123

Namespace Inheritance

Child namespaces MAY inherit properties from parents:

.mif/namespaces/acme-corp.yaml

id: acme-corp
type: organization
default_ttl: P365D
default_visibility: private

# .mif/namespaces/acme-corp/project-x.yaml
id: project-x
parent: acme-corp
default_tags: [project-x]
# Inherits default_ttl and default_visibility from parent

Ontology Definition

Ontologies define namespace hierarchies, entity types, and discovery patterns. They enable domain-specific customization while maintaining MIF compatibility.

Ontology Files

Ontologies are defined in YAML files with optional JSON-LD export:

.mif/ontologies/
├── mif-base.ontology.yaml       # Base ontology (semantic/episodic/procedural)
├── mif-base.ontology.jsonld     # JSON-LD export for semantic web
└── domain/
    └── software-engineering.ontology.yaml

Base Type Hierarchy

The base ontology uses a three-tier hierarchy based on cognitive memory types:

namespaces:
  semantic:                    # Facts, concepts, relationships
    type_hint: semantic
    children:
      decisions: {}
      knowledge: {}
      entities: {}
  episodic:                    # Events, experiences, timelines
    type_hint: episodic
    children:
      incidents: {}
      sessions: {}
      blockers: {}
  procedural:                  # Step-by-step processes
    type_hint: procedural
    children:
      runbooks: {}
      patterns: {}
      migrations: {}

Entity Type Definition

Entity types define structured data with traits and JSON Schema:

entity_types:
  - name: component
    base: semantic
    traits: [versioned, documented]
    schema:
      required: [name, responsibility]
      properties:
        name: { type: string }
        responsibility: { type: string }
        dependencies: { type: array, items: { type: string } }

Discovery Patterns

Ontologies can define patterns for suggesting entity types:

discovery:
  enabled: true
  confidence_threshold: 0.8
  patterns:
    - content_pattern: "\\b(PostgreSQL|MySQL|MongoDB)\\b"
      suggest_entity: technology
      suggest_namespace: _semantic/entities
    - file_pattern: "**/services/**/*.py"
      suggest_entity: component
      suggest_namespace: _semantic/components

Ontology Resolution

Ontologies are loaded from multiple sources with precedence:

1. MIF base ontology (built-in)
2. User ontology (~/.claude/mnemonic/ontology.yaml)
3. Project ontology (./.claude/mnemonic/ontology.yaml)

Later sources can extend or override earlier definitions.

Trait Inheritance and Conflict Resolution

Traits support inheritance via the extends field, enabling composition:

traits:
  timestamped:
    fields:
      created: { type: string, format: date-time }
      modified: { type: string, format: date-time }

  auditable:
    extends: [timestamped]
    fields:
      audit_log: { type: array }
      last_audited: { type: string, format: date-time }

  lifecycle:
    extends: [timestamped]
    fields:
      status: { type: string, enum: [draft, active, archived] }

Conflict Resolution Strategy:

When multiple traits define the same field (e.g., both auditable and lifecycle inherit created from timestamped), implementations MUST apply the following resolution rules:

Scenario	Resolution	Rationale
Same field inherited via different paths	Use shared ancestor definition	Diamond inheritance resolved to common base
Same field defined in multiple independent traits	Error at composition time	Ambiguous definition requires explicit resolution
Field in trait overrides inherited field	Child definition wins	Explicit override is intentional
Field in entity overrides trait field	Entity definition wins	Most specific wins

Example - Diamond Inheritance:

# Both auditable and lifecycle inherit timestamped
entity_types:
  - name: document
    traits: [auditable, lifecycle]  # No conflict: `created` from shared `timestamped`

Example - Conflict Requiring Resolution:

traits:
  trait_a:
    fields:
      status: { type: string, enum: [open, closed] }

  trait_b:
    fields:
      status: { type: string, enum: [draft, published] }

entity_types:
  - name: conflicting_entity
    traits: [trait_a, trait_b]
    # ERROR: `status` defined differently in both traits
    # Resolution: Override explicitly in entity schema
    schema:
      properties:
        status: { type: string, enum: [draft, open, published, closed] }

Implementation Guidance:

1. Validation: Implementations SHOULD detect conflicts at ontology load time
2. Error Messages: Include both conflicting definitions and their sources
3. Explicit Override: When conflicts exist, entity-level schema takes precedence
4. Documentation: Ontology authors SHOULD document intentional overrides