feat: add canonical schema export

Author: Alexxigang

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.21.0 - 2026-03-13
+
+- added a canonical JSON Schema export for third-party tool integration
+- added a `schema` CLI command to print or write the schema
+
 ## 0.20.0 - 2026-03-13
 
 - refreshed README homepage with badges, quick start, and workflow overview

README.md

@@ -25,6 +25,7 @@ This project solves that with a portable canonical memory package plus adapter-b
 
 - detect supported source formats automatically
 - normalize memory into a canonical package
+- publish a JSON Schema for external tool integrations
 - convert across agent-specific formats
 - run diagnostics with `doctor`
 - generate suggestions and safe repairs

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory-migrate-plugin"
-version = "0.20.0"
+version = "0.21.0"
 description = "Open-source toolkit for migrating memories across AI agent systems."
 readme = "README.md"
 requires-python = ">=3.11"

src/memory_migrate_plugin/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.20.0"
+__version__ = "0.21.0"

src/memory_migrate_plugin/cli.py

@@ -15,6 +15,7 @@
 from memory_migrate_plugin.registry import build_registry, detect_format
 from memory_migrate_plugin.release import run_release
 from memory_migrate_plugin.repair import repair_package
+from memory_migrate_plugin.schema import build_canonical_package_schema, write_canonical_package_schema
 from memory_migrate_plugin.report import build_merge_report, build_package_report
 from memory_migrate_plugin.suggest import build_package_suggestions
 from memory_migrate_plugin.utils import write_json
@@ -28,6 +29,9 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("adapters", help="List supported adapters.")
     subparsers.add_parser("profiles", help="List supported export profiles.")
 
+    schema_parser = subparsers.add_parser("schema", help="Print or export the canonical JSON Schema.")
+    schema_parser.add_argument("--output")
+
     detect_parser = subparsers.add_parser("detect", help="Detect the most likely source format for a path.")
     detect_parser.add_argument("--input", required=True)
 
@@ -129,6 +133,15 @@ def command_profiles() -> int:
     return 0
 
 
+def command_schema(output_path: str | None) -> int:
+    schema = build_canonical_package_schema() if not output_path else write_canonical_package_schema(Path(output_path))
+    if output_path:
+        print(f"Wrote schema to {output_path}")
+    else:
+        print(json.dumps(schema, indent=2, ensure_ascii=False))
+    return 0
+
+
 def command_detect(source_path: Path) -> int:
     matches = detect_format(source_path)
     if not matches:
@@ -317,6 +330,8 @@ def main() -> int:
         return command_adapters()
     if args.command == "profiles":
         return command_profiles()
+    if args.command == "schema":
+        return command_schema(args.output)
     if args.command == "detect":
         return command_detect(Path(args.input))
     if args.command == "inspect":

src/memory_migrate_plugin/schema.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from memory_migrate_plugin.utils import write_json
+
+
+CANONICAL_SCHEMA_ID = "https://agent-memory-bridge.dev/schema/canonical-memory-package/v1.0"
+
+
+def build_canonical_package_schema() -> dict[str, Any]:
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": CANONICAL_SCHEMA_ID,
+        "title": "CanonicalMemoryPackage",
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "schema_version",
+            "package_id",
+            "created_at",
+            "source_formats",
+            "metadata",
+            "entries",
+        ],
+        "properties": {
+            "schema_version": {
+                "type": "string",
+                "description": "Canonical package schema version.",
+                "default": "1.0",
+            },
+            "package_id": {
+                "type": "string",
+                "description": "Stable identifier for the package.",
+                "minLength": 1,
+            },
+            "created_at": {
+                "type": "string",
+                "description": "UTC creation timestamp in ISO 8601 format.",
+                "format": "date-time",
+            },
+            "source_formats": {
+                "type": "array",
+                "description": "Distinct source adapters represented in the package.",
+                "items": {"type": "string"},
+                "uniqueItems": True,
+            },
+            "metadata": {
+                "type": "object",
+                "description": "Package-level metadata and provenance fields.",
+                "additionalProperties": True,
+            },
+            "entries": {
+                "type": "array",
+                "description": "Normalized memory entries.",
+                "items": {"$ref": "#/$defs/memoryEntry"},
+            },
+        },
+        "$defs": {
+            "memoryEntry": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": [
+                    "id",
+                    "kind",
+                    "title",
+                    "content",
+                    "tags",
+                    "source_format",
+                    "metadata",
+                ],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "Stable entry identifier.",
+                        "minLength": 1,
+                    },
+                    "kind": {
+                        "type": "string",
+                        "description": "Semantic entry category such as note, project, or preference.",
+                        "minLength": 1,
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "Human-readable entry title.",
+                        "minLength": 1,
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Primary body content for the memory entry.",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "description": "Keyword tags used for retrieval and filtering.",
+                        "items": {"type": "string"},
+                    },
+                    "source_format": {
+                        "type": "string",
+                        "description": "Adapter name that produced the entry.",
+                        "minLength": 1,
+                    },
+                    "created_at": {
+                        "type": ["string", "null"],
+                        "description": "Original creation timestamp when available.",
+                        "format": "date-time",
+                    },
+                    "updated_at": {
+                        "type": ["string", "null"],
+                        "description": "Original update timestamp when available.",
+                        "format": "date-time",
+                    },
+                    "metadata": {
+                        "type": "object",
+                        "description": "Entry-level adapter metadata.",
+                        "additionalProperties": True,
+                    },
+                },
+            }
+        },
+    }
+
+
+def write_canonical_package_schema(output_path: Path) -> dict[str, Any]:
+    schema = build_canonical_package_schema()
+    write_json(output_path, schema)
+    return schema

tests/test_roundtrip.py

@@ -18,6 +18,7 @@
 from memory_migrate_plugin.suggest import build_package_suggestions
 from memory_migrate_plugin.manifest import build_manifest
 from memory_migrate_plugin.verify import verify_manifest
+from memory_migrate_plugin.schema import build_canonical_package_schema, write_canonical_package_schema
 
 
 class MemoryMigrateTests(unittest.TestCase):
@@ -53,6 +54,21 @@ def test_generic_json_roundtrip(self) -> None:
             package = normalize("generic-json", source)
             self.assertEqual(package.entries[0].title, "Editor")
 
+    def test_build_canonical_package_schema_describes_required_fields(self) -> None:
+        schema = build_canonical_package_schema()
+        self.assertEqual(schema["title"], "CanonicalMemoryPackage")
+        self.assertIn("entries", schema["required"])
+        self.assertEqual(schema["properties"]["entries"]["items"]["$ref"], "#/$defs/memoryEntry")
+        self.assertIn("source_format", schema["$defs"]["memoryEntry"]["required"])
+
+    def test_write_canonical_package_schema_outputs_json_file(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output = Path(tmpdir) / "canonical-memory-package.schema.json"
+            schema = write_canonical_package_schema(output)
+            written = json.loads(output.read_text(encoding="utf-8"))
+            self.assertEqual(written["$id"], schema["$id"])
+            self.assertEqual(written["$schema"], "https://json-schema.org/draft/2020-12/schema")
+
     def test_detect_format_prefers_cline_memory_bank(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             source = Path(tmpdir) / "memory-bank"