How the MCP Memory Service Implements Tag Taxonomy with Soft Validation

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, 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. 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:

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:

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:

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():

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:

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.
• Soft validation occurs in Memory.__post_init__ within 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: 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, containing namespace constants, parsing logic, validation functions, and helper utilities. The soft validation integration occurs in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}