# MemoryTypeOntology in MCP Memory Service: Complete Guide to 12 Base Types and 75 Sub-Types

> Explore the MemoryTypeOntology in MCP Memory Service. Understand 12 base types and 75 sub-types for precise semantic retrieval and analytics. Learn when to use each memory type.

- Repository: [Henry/mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
- Tags: deep-dive
- Published: 2026-02-28

---

**The MemoryTypeOntology defines 12 base memory types and 75 specific sub-types that categorize why you store a memory (base) and what specific content it contains (sub-type), enabling precise semantic retrieval and project analytics.**

The **MemoryTypeOntology** is the formal classification system at the heart of the `doobidoo/mcp-memory-service` repository, structuring how AI assistants categorize and retrieve contextual memories. Defined in [`src/mcp_memory_service/models/ontology.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/ontology.py), this taxonomy ensures every memory has a clear purpose and specific content category for optimal searchability and analytics.

## The 12 Base Memory Types (The "Why")

The `BaseMemoryType` enum (lines 37‑64 of [`ontology.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/ontology.py)) defines the root categories that describe the *intent* behind storing a memory. Select the base type that matches the fundamental purpose of the information.

### observation

Use **observation** when capturing factual events, raw data, or actions that occurred. This is the default category for logging what happened during a session.

**Common sub-types:** `code_edit`, `file_access`, `search`, `command`, `conversation`, `document`, `note`, `reference`

### decision

Use **decision** to record choices, recommendations, or configuration selections you made during development.

**Common sub-types:** `architecture`, `tool_choice`, `approach`, `configuration`

### learning

Use **learning** for lessons derived from experience, including insights, best practices, and pitfalls to avoid.

**Common sub-types:** `insight`, `best_practice`, `anti_pattern`, `gotcha`

### error

Use **error** to document problems, failures, exceptions, or timeouts that occurred or were discovered.

**Common sub-types:** `bug`, `failure`, `exception`, `timeout`

### pattern

Use **pattern** for recurring constructs you want to reference later, such as code smells, design patterns, or workflow templates.

**Common sub-types:** `recurring_issue`, `code_smell`, `design_pattern`, `workflow`

### planning

Use **planning** (Agile context) for sprint-related elements including goals, backlog items, estimates, and velocity metrics.

**Common sub-types:** `sprint_goal`, `backlog_item`, `story_point_estimate`, `velocity`, `retrospective`, `standup_note`, `acceptance_criteria`

### ceremony

Use **ceremony** (Agile context) for structured recurring meetings such as reviews, planning sessions, and stand-ups.

**Common sub-types:** `sprint_review`, `sprint_planning`, `daily_standup`, `retrospective_action`, `demo_feedback`

### milestone

Use **milestone** (Traditional PM) for high-level project checkpoints including deliverables, dependencies, risks, and deadlines.

**Common sub-types:** `deliverable`, `dependency`, `risk`, `constraint`, `assumption`, `deadline`

### stakeholder

Use **stakeholder** (Traditional PM) for interactions with people or groups that affect the project.

**Common sub-types:** `requirement`, `feedback`, `escalation`, `approval`, `change_request`, `status_update`

### meeting

Use **meeting** (Knowledge Work) for general meeting artifacts including agendas, minutes, and action items.

**Common sub-types:** `action_item`, `attendee_note`, `agenda_item`, `follow_up`, `minutes`

### research

Use **research** (Knowledge Work) for structured investigation work including findings, comparisons, and hypotheses.

**Common sub-types:** `finding`, `comparison`, `recommendation`, `source`, `hypothesis`

### communication

Use **communication** (Knowledge Work) for summaries of asynchronous communication such as emails, chats, and announcements.

**Common sub-types:** `email_summary`, `chat_summary`, `announcement`, `request`, `response`

## The 75 Built-In Sub-Types (The "What")

Each base type contains a closed list of sub-types defined in the `TAXONOMY` mapping (lines 66‑161 of [`ontology.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/ontology.py)). These provide granular classification for the specific content being stored.

### Observation Sub-Types

- `code_edit` – A code change (add/remove/modify)
- `file_access` – Opening, reading, or writing a file
- `search` – A query against code, docs, or logs
- `command` – A CLI or tool command executed
- `conversation` – A chat transcript or dialogue
- `document` – A full-length document (e.g., design doc)
- `note` – A short free-form note
- `reference` – A link or citation to external knowledge

### Decision Sub-Types

- `architecture` – A high-level design choice
- `tool_choice` – Selecting a library, framework, or service
- `approach` – A methodological decision
- `configuration` – A setting or parameter chosen

### Learning Sub-Types

- `insight` – A novel understanding
- `best_practice` – A proven technique
- `anti_pattern` – A known bad practice to avoid
- `gotcha` – A surprising pitfall discovered

### Error Sub-Types

- `bug` – A defect in code
- `failure` – A broader failure (e.g., build break)
- `exception` – A raised exception trace
- `timeout` – An operation that exceeded its deadline

### Pattern Sub-Types

- `recurring_issue` – A problem that shows up repeatedly
- `code_smell` – A sign of deeper code quality issues
- `design_pattern` – A reusable solution (e.g., Singleton)
- `workflow` – A repeatable process template

### Planning Sub-Types (Agile)

- `sprint_goal`, `backlog_item`, `story_point_estimate`, `velocity`, `retrospective`, `standup_note`, `acceptance_criteria`

### Ceremony Sub-Types (Agile)

- `sprint_review`, `sprint_planning`, `daily_standup`, `retrospective_action`, `demo_feedback`

### Milestone Sub-Types (Traditional)

- `deliverable`, `dependency`, `risk`, `constraint`, `assumption`, `deadline`

### Stakeholder Sub-Types (Traditional)

- `requirement`, `feedback`, `escalation`, `approval`, `change_request`, `status_update`

### Meeting Sub-Types (Knowledge Work)

- `action_item`, `attendee_note`, `agenda_item`, `follow_up`, `minutes`

### Research Sub-Types (Knowledge Work)

- `finding`, `comparison`, `recommendation`, `source`, `hypothesis`

### Communication Sub-Types (Knowledge Work)

- `email_summary`, `chat_summary`, `announcement`, `request`, `response`

## How to Programmatically Validate and Use Memory Types

The `MemoryTypeOntology` class provides static methods to validate types and retrieve hierarchy information (lines 22‑34 and 45‑61).

### Validating a Memory Type

```python
from mcp_memory_service.models.ontology import MemoryTypeOntology

# Check if a type is valid

is_valid = MemoryTypeOntology.validate_memory_type("bug")
print(is_valid)  # True

# Check invalid type

is_valid = MemoryTypeOntology.validate_memory_type("invalid_type")
print(is_valid)  # False

```

### Retrieving Parent Base Types

```python

# Get the parent base type for any sub-type

parent = MemoryTypeOntology.get_parent_type("code_edit")
print(parent)  # 'observation'

parent = MemoryTypeOntology.get_parent_type("architecture")
print(parent)  # 'decision'

```

### Getting All Supported Types

```python

# Retrieve all supported types including custom extensions

all_types = MemoryTypeOntology.get_all_types()
print(f"Total available types: {len(all_types)}")

```

### Accessing the Full Taxonomy

```python

# Get the merged taxonomy dictionary

tax = MemoryTypeOntology._get_merged_taxonomy()
print(tax["observation"])  # ['code_edit', 'file_access', ...]

```

## Extending MemoryTypeOntology with Custom Types

The service supports runtime extension of the ontology via the `MCP_CUSTOM_MEMORY_TYPES` environment variable. The `_load_custom_types_from_config()` method (lines 96‑124) merges custom definitions with the built-in taxonomy.

Set the environment variable to a JSON object mapping base types to lists of new sub-types:

```bash
export MCP_CUSTOM_MEMORY_TYPES='{"planning": ["tech_spike", "ux_research"], "meeting": ["brainstorm"]}'

```

When loaded, these custom types are validated and merged into the taxonomy, making them available for `validate_memory_type()` and `get_all_types()` calls immediately.

## Choosing the Right Memory Type: Decision Workflow

Follow this sequence when classifying a new memory:

1. **Identify the intent** – Determine if you are recording something that happened (observation), a choice made (decision), a lesson learned (learning), a problem encountered (error), or a reusable construct (pattern)
2. **Select the base type** – Match the intent to one of the 12 base types in `BaseMemoryType`
3. **Pinpoint the content** – Choose the most specific sub-type from the 75 available options that captures the concrete content
4. **Validate** – Use `MemoryTypeOntology.validate_memory_type()` to ensure the combination is supported

### Example Classification Logic

```python
def classify_memory(purpose: str, content: str) -> str:
    if purpose == "code_change":
        return "observation:code_edit"
    elif purpose == "design_decision":
        return "decision:architecture"
    elif purpose == "discovered_bug":
        return "error:bug"
    elif purpose == "lesson_learned":
        return "learning:insight"
    else:
        return "observation:note"

```

## Summary

- The **MemoryTypeOntology** in [`src/mcp_memory_service/models/ontology.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/ontology.py) provides **12 base types** (observation, decision, learning, error, pattern, planning, ceremony, milestone, stakeholder, meeting, research, communication) that define *why* you store a memory
- **75 built-in sub-types** define *what* specific content you are storing, organized under each base type in the `TAXONOMY` mapping (lines 66‑161)
- Use **`validate_memory_type()`** to check type validity and **`get_parent_type()`** to navigate the hierarchy
- Extend the ontology at runtime using the **`MCP_CUSTOM_MEMORY_TYPES`** environment variable and `_load_custom_types_from_config()`
- Select base types based on intent and sub-types based on specific content for optimal retrieval and analytics

## Frequently Asked Questions

### How do I add a custom memory type not covered by the 75 built-in sub-types?

Set the `MCP_CUSTOM_MEMORY_TYPES` environment variable to a JSON object mapping existing base types to your new sub-types. The `_load_custom_types_from_config()` method merges these with the built-in `TAXONOMY` at runtime, making them available for validation and storage immediately.

### What happens if I use an invalid memory type string?

The `MemoryTypeOntology.validate_memory_type()` method returns `False` for any type not present in the built-in taxonomy or custom extensions. The memory service typically rejects invalid types to maintain data quality and ensure analytics aggregation works correctly.

### Can I retrieve all sub-types for a specific base type programmatically?

Yes. Use `MemoryTypeOntology._get_merged_taxonomy()` to access the full dictionary, then index into the base type name (e.g., `taxonomy["observation"]`) to get the list of valid sub-types. Alternatively, use `get_parent_type()` on any sub-type string to verify its base category.

### When should I use "observation" versus "learning" for documenting code discoveries?

Use **observation** when neutrally logging what happened (e.g., "discovered deprecated function usage"). Use **learning** when capturing a derived insight or best practice (e.g., "always check for deprecation warnings before refactoring"). The distinction helps separate raw event logs from synthesized knowledge.