# How the MCP Memory Service Implements Tag Taxonomy with Soft Validation

> Discover how the MCP Memory Service uses a namespace-based tag taxonomy and soft validation to enforce standards and ensure backward compatibility. Learn about prefixes and legacy data handling.

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

---

**The MCP Memory Service employs a namespace-based tag taxonomy with seven predefined prefixes and soft validation to enforce tagging standards while maintaining backward compatibility with legacy data.**

The `doobidoo/mcp-memory-service` repository implements a structured tagging system that organizes metadata through explicit namespaces. This **tag taxonomy system** categorizes tags into machine-readable scopes while **soft validation** ensures data integrity without breaking existing memory entries. Understanding these mechanisms is essential for developers integrating with the memory service or extending its ontology.

## Understanding the Namespace-Based Tag Taxonomy

The taxonomy implementation resides in **[`src/mcp_memory_service/models/tag_taxonomy.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/tag_taxonomy.py)**, where the `TagTaxonomy` class defines seven namespace constants. Each namespace ends with a colon (`:`) to enable clear concatenation with tag values, creating a machine-readable scoping mechanism.

### The Seven Core Namespaces

| Namespace | Purpose | Example Tag |
|-----------|---------|-------------|
| `sys:` | System-generated tags | `sys:auto-generated` |
| `q:` | Quality scores | `q:high` |
| `proj:` | Project or repository context | `proj:mcp-memory` |
| `topic:` | Subject-matter topics | `topic:authentication` |
| `t:` | Temporal tags | `t:2024-01` |
| `user:` | User-defined custom tags | `user:priority` |
| `agent:` | Agent identity tags | `agent:42` |

These constants are defined in lines 22–30 of the taxonomy module, providing the foundation for all tag operations.

### Core Taxonomy Utilities

The `TagTaxonomy` class exposes four primary utilities as both standalone functions and class methods (lines 149–176):

1. **`parse_tag(tag)`** – Splits a tag into `(namespace, value)` tuple. If no colon exists, the tag is treated as a legacy tag with `namespace == None` (lines 32–58).
2. **`validate_tag(tag)`** – Returns `True` for tags using known namespaces from `VALID_NAMESPACES` or for legacy tags. Returns `False` only for unknown namespaces (lines 72–98).
3. **`add_namespace(value, namespace)`** – Strips existing namespaces and prefixes the requested namespace to a tag value (lines 100–122).
4. **`filter_by_namespace(tags, namespace)`** – Returns a filtered list containing only tags belonging to the requested namespace (lines 124–140).

## How Soft Validation Works in MCP Memory Service

Soft validation occurs during `Memory` object instantiation in **[`src/mcp_memory_service/models/memory.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/memory.py)**. The `Memory.__post_init__` method (lines 79–96) invokes the taxonomy to inspect tags without enforcing hard constraints.

### The Validation Implementation

When a `Memory` instance is created, the post-initialization hook executes the following logic:

```python
if self.tags:
    invalid_tags = []
    for tag in self.tags:
        namespace, _ = TagTaxonomy.parse_tag(tag)
        if namespace is not None and namespace not in TagTaxonomy.VALID_NAMESPACES:
            invalid_tags.append(tag)

    if invalid_tags:
        logger.info(
            f"Tags with invalid namespaces: {', '.join(invalid_tags)}. "
            "Valid namespaces: sys:, q:, proj:, topic:, t:, user:. "
            "Legacy tags (no namespace) are still supported."
        )

```

This approach inspects each tag using `TagTaxonomy.parse_tag()`, identifies unknown namespaces by checking against `VALID_NAMESPACES`, and logs informative warnings through the standard logger.

### Characteristics of Soft Validation

- **Non-blocking operation** – The `Memory` object is created and stored even when tags contain invalid namespaces. No exceptions interrupt the data flow.
- **Informational logging only** – Developers and operators receive clear warnings about namespace violations, enabling gradual migration strategies.
- **Legacy compatibility** – Tags without colons automatically pass validation with `namespace == None`, preserving existing data integrity during system upgrades.

## Practical Implementation Examples

### Creating and Parsing Namespaced Tags

Use `add_namespace()` to apply taxonomy prefixes and `parse_tag()` to deconstruct them:

```python
from mcp_memory_service.models.tag_taxonomy import TagTaxonomy

# Apply quality namespace

tag = TagTaxonomy.add_namespace("high", "q:")
print(tag)  # Output: q:high

# Deconstruct the tag

namespace, value = TagTaxonomy.parse_tag(tag)
print(f"Namespace: {namespace}, Value: {value}")

# Output: Namespace: q:, Value: high

```

### Soft Validation in Action

The `Memory` constructor demonstrates soft validation by accepting mixed tag quality:

```python
from mcp_memory_service.models.memory import Memory

# Create memory with valid, invalid, and legacy tags

memory = Memory(
    content="Example content",
    content_hash="abc123",
    tags=["q:high", "proj:mcp", "bad:tag", "legacy-tag"]
)

# Log output indicates:

# Tags with invalid namespaces: bad:tag. Valid namespaces: sys:, q:, proj:, ...

# Object creation succeeds despite the invalid namespace

```

### Filtering by Namespace

Extract specific categories using `filter_by_namespace()`:

```python
tags = ["q:high", "proj:auth", "q:medium", "legacy", "sys:auto"]
quality_tags = TagTaxonomy.filter_by_namespace(tags, "q:")
print(quality_tags)  # Output: ['q:high', 'q:medium']

```

### Direct Validation Checks

Validate individual tags before application:

```python
if TagTaxonomy.validate_tag("t:2024-01"):
    print("Temporal tag is valid")
else:
    print("Invalid namespace detected")

```

## Summary

- The **tag taxonomy system** in `doobidoo/mcp-memory-service` uses seven predefined namespaces (`sys:`, `q:`, `proj:`, `topic:`, `t:`, `user:`, `agent:`) to scope metadata in [`src/mcp_memory_service/models/tag_taxonomy.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/tag_taxonomy.py).
- **Soft validation** occurs in `Memory.__post_init__` within [`src/mcp_memory_service/models/memory.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/memory.py), logging warnings for invalid namespaces without raising exceptions.
- The `TagTaxonomy` class provides `parse_tag()`, `validate_tag()`, `add_namespace()`, and `filter_by_namespace()` utilities as both functions and class methods.
- Legacy tags without namespaces automatically pass validation, ensuring backward compatibility during ontology evolution.

## Frequently Asked Questions

### What namespaces are supported in MCP Memory Service?

The service supports seven predefined namespaces defined in [`src/mcp_memory_service/models/tag_taxonomy.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/tag_taxonomy.py): `sys:` for system tags, `q:` for quality scores, `proj:` for project context, `topic:` for subject matter, `t:` for temporal data, `user:` for custom tags, and `agent:` for identity markers. Tags using these prefixes pass `validate_tag()` checks.

### How does soft validation differ from strict validation?

**Soft validation** logs informative warnings about invalid namespaces through `logger.info()` but allows the `Memory` object to be created and stored. **Strict validation** would raise exceptions or reject the data entirely. The MCP Memory Service uses soft validation specifically to prevent breaking existing integrations while encouraging migration to the new taxonomy.

### Can I use legacy tags without namespaces?

Yes. The `parse_tag()` function returns `namespace == None` for tags without colons, and the soft validation logic in `Memory.__post_init__` explicitly accepts these legacy tags. This design ensures existing memory entries remain valid even as the taxonomy system evolves.

### Where is the tag taxonomy implemented in the codebase?

The core implementation resides in [`src/mcp_memory_service/models/tag_taxonomy.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/tag_taxonomy.py), containing namespace constants, parsing logic, validation functions, and helper utilities. The soft validation integration occurs in [`src/mcp_memory_service/models/memory.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/memory.py) within the `Memory` class's post-initialization hook. Unit tests describing intended behavior are available in [`tests/test_tag_taxonomy.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/tests/test_tag_taxonomy.py).