fix: schema_validate identifier resolution and text rendering

Fixes issues #29 and #33 from openclaw-basic-memory.

🔧 Identifier resolution (#33):
- Router used get_by_permalink() which only matched exact permalinks.
  Replaced with link_resolver.resolve_link() so titles, paths, and
  fuzzy matches work consistently with other tools like read_note.
- Set total_entities=1 and total_notes=len(results) on single-note
  path for consistency with batch path.
- Guards for "no notes" and "no schema" now fire for identifier-based
  validation too, not just note_type-based.

🎨 Text rendering (#29):
- Tool returned raw Pydantic model which LLMs rendered as
  "undefined — invalid". Now returns pre-formatted markdown.
- Router uses entity.title (with permalink fallback) as note_identifier
  for human-readable output in both text and JSON modes.
- JSON output (output_format="json") unchanged for CLI compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/api/v2/routers/schema_router.py

@@ -12,7 +12,7 @@
 
 from fastapi import APIRouter, Path, Query
 
-from basic_memory.deps import EntityRepositoryV2ExternalDep
+from basic_memory.deps import EntityRepositoryV2ExternalDep, LinkResolverV2ExternalDep
 from basic_memory.models.knowledge import Entity
 from basic_memory.schemas.schema import (
     ValidationReport,
@@ -80,6 +80,7 @@ def _entity_frontmatter(entity: Entity) -> dict:
 @router.post("/schema/validate", response_model=ValidationReport)
 async def validate_schema(
     entity_repository: EntityRepositoryV2ExternalDep,
+    link_resolver: LinkResolverV2ExternalDep,
     project_id: str = Path(..., description="Project external UUID"),
     note_type: str | None = Query(None, description="Note type to validate"),
     identifier: str | None = Query(None, description="Specific note identifier"),
@@ -93,9 +94,11 @@ async def validate_schema(
 
     # --- Single note validation ---
     if identifier:
-        entity = await entity_repository.get_by_permalink(identifier)
+        # Resolve identifier flexibly (permalink, title, path, fuzzy)
+        # to match how read_note and other tools resolve identifiers
+        entity = await link_resolver.resolve_link(identifier)
         if not entity:
-            return ValidationReport(note_type=note_type, total_notes=0, results=[])
+            return ValidationReport(note_type=note_type, total_notes=0, total_entities=0)
 
         frontmatter = _entity_frontmatter(entity)
         schema_ref = frontmatter.get("schema")
@@ -111,7 +114,7 @@ async def search_fn(query: str) -> list[dict]:
         schema_def = await resolve_schema(frontmatter, search_fn)
         if schema_def:
             result = validate_note(
-                entity.permalink or identifier,
+                entity.title or entity.permalink or identifier,
                 schema_def,
                 _entity_observations(entity),
                 _entity_relations(entity),
@@ -121,7 +124,8 @@ async def search_fn(query: str) -> list[dict]:
 
         return ValidationReport(
             note_type=note_type or entity.note_type,
-            total_notes=1,
+            total_notes=len(results),
+            total_entities=1,
             valid_count=1 if (results and results[0].passed) else 0,
             warning_count=sum(len(r.warnings) for r in results),
             error_count=sum(len(r.errors) for r in results),
@@ -146,7 +150,7 @@ async def search_fn(query: str) -> list[dict]:
         schema_def = await resolve_schema(frontmatter, search_fn)
         if schema_def:
             result = validate_note(
-                entity.permalink or entity.file_path,
+                entity.title or entity.permalink or entity.file_path,
                 schema_def,
                 _entity_observations(entity),
                 _entity_relations(entity),

src/basic_memory/mcp/tools/schema.py

@@ -14,6 +14,36 @@
 from basic_memory.schemas.schema import ValidationReport, InferenceReport, DriftReport
 
 
+def _format_validation_report(report: ValidationReport) -> str:
+    """Render a ValidationReport as readable markdown.
+
+    Produces output the LLM can display directly instead of trying to
+    interpret raw JSON, which leads to "undefined — invalid" rendering.
+    """
+    lines: list[str] = []
+
+    # --- Header ---
+    type_label = report.note_type or "all"
+    lines.append(f"# Schema Validation: {type_label}")
+    lines.append("")
+    lines.append(
+        f"Notes: {report.total_notes} | Valid: {report.valid_count} "
+        f"| Warnings: {report.warning_count} | Errors: {report.error_count}"
+    )
+    lines.append("")
+
+    # --- Per-note results ---
+    for r in report.results:
+        status = "valid" if r.passed else "INVALID"
+        lines.append(f"- **{r.note_identifier}** — {status}")
+        for w in r.warnings:
+            lines.append(f"  - warning: {w}")
+        for e in r.errors:
+            lines.append(f"  - error: {e}")
+
+    return "\n".join(lines)
+
+
 def _no_notes_guidance(note_type: str, tool_name: str) -> str:
     """Build guidance string when no notes of a given type exist.
 
@@ -142,24 +172,25 @@ async def schema_validate(
             # Trigger: no entities of this type exist in the project
             # Why: can't validate notes that don't exist yet
             # Outcome: return guidance on creating notes of this type
-            if note_type and result.total_entities == 0:
+            effective_type = note_type or result.note_type or "unknown"
+            if result.total_entities == 0:
                 if output_format == "json":
-                    return {"error": f"No notes found of type '{note_type}'"}
-                return _no_notes_guidance(note_type, "schema_validate")
+                    return {"error": f"No notes found of type '{effective_type}'"}
+                return _no_notes_guidance(effective_type, "schema_validate")
 
             # --- No schema guard ---
             # Trigger: entities exist but none were validated (no schema found)
             # Why: notes of this type exist but no schema was found, so none were validated
             # Outcome: return guidance on how to create a schema
-            if note_type and result.total_notes == 0:
+            if result.total_notes == 0:
                 if output_format == "json":
-                    return {"error": f"No schema found for type '{note_type}'"}
-                return _no_schema_guidance(note_type, "schema_validate")
+                    return {"error": f"No schema found for type '{effective_type}'"}
+                return _no_schema_guidance(effective_type, "schema_validate")
 
             if output_format == "json":
                 return result.model_dump(mode="json", exclude_none=True)
 
-            return result
+            return _format_validation_report(result)
 
         except Exception as e:
             logger.error(f"Schema validation failed: {e}, project: {active_project.name}")

tests/mcp/test_tool_schema.py

@@ -12,7 +12,7 @@
 
 from basic_memory.mcp.tools.schema import schema_validate, schema_infer, schema_diff
 from basic_memory.mcp.tools.write_note import write_note
-from basic_memory.schemas.schema import ValidationReport, InferenceReport, DriftReport
+from basic_memory.schemas.schema import InferenceReport, DriftReport
 
 
 # --- Helpers ---
@@ -82,8 +82,39 @@ async def test_schema_validate_by_type(app, test_project, sync_service):
         project=test_project.name,
     )
 
-    assert isinstance(result, ValidationReport)
-    assert result.total_notes >= 1
+    assert isinstance(result, str)
+    assert "Schema Validation: person" in result
+    assert "Notes: 1" in result
+    assert "**Alice**" in result
+    assert "valid" in result
+
+
+@pytest.mark.asyncio
+async def test_schema_validate_json_output(app, test_project, sync_service):
+    """JSON output returns a dict with full structured data."""
+    project_path = Path(test_project.path)
+
+    _write_schema_file(project_path, "schemas/Person.md", PERSON_SCHEMA)
+    _write_schema_file(
+        project_path,
+        "people/Alice.md",
+        PERSON_NOTE.format(name="Alice", permalink="alice"),
+    )
+
+    await sync_service.sync(project_path)
+
+    result = await schema_validate(
+        note_type="person",
+        project=test_project.name,
+        output_format="json",
+    )
+
+    assert isinstance(result, dict)
+    assert result["total_notes"] == 1
+    assert result["valid_count"] == 1
+    assert len(result["results"]) == 1
+    assert result["results"][0]["note_identifier"] == "Alice"
+    assert result["results"][0]["passed"] is True
 
 
 @pytest.mark.asyncio
@@ -105,8 +136,70 @@ async def test_schema_validate_by_identifier(app, test_project, sync_service):
         project=test_project.name,
     )
 
-    assert isinstance(result, ValidationReport)
-    assert result.total_notes >= 1
+    assert isinstance(result, str)
+    assert "**Alice**" in result
+    assert "valid" in result
+
+
+@pytest.mark.asyncio
+async def test_schema_validate_by_title(app, test_project, sync_service):
+    """Validate a specific note by title (not permalink).
+
+    Regression test for issue #33: schema_validate(identifier="Note Title")
+    returned 0 notes because the router only searched by permalink.
+    """
+    project_path = Path(test_project.path)
+
+    _write_schema_file(project_path, "schemas/Person.md", PERSON_SCHEMA)
+    _write_schema_file(
+        project_path,
+        "people/Alice.md",
+        PERSON_NOTE.format(name="Alice", permalink="alice"),
+    )
+
+    await sync_service.sync(project_path)
+
+    # Use the title "Alice" instead of the permalink "people/alice"
+    result = await schema_validate(
+        identifier="Alice",
+        project=test_project.name,
+    )
+
+    assert isinstance(result, str)
+    assert "**Alice**" in result
+    assert "Notes: 1" in result
+    assert "valid" in result
+
+
+@pytest.mark.asyncio
+async def test_schema_validate_identifier_no_schema_returns_guidance(
+    app, test_project, sync_service
+):
+    """When a note exists but no schema is defined, return guidance.
+
+    Regression test for issue #33: when validating a single note by identifier
+    and no schema exists, the tool should return guidance instead of an empty report.
+    """
+    project_path = Path(test_project.path)
+
+    # Create a person note but no schema note
+    _write_schema_file(
+        project_path,
+        "people/Alice.md",
+        PERSON_NOTE.format(name="Alice", permalink="alice"),
+    )
+
+    await sync_service.sync(project_path)
+
+    result = await schema_validate(
+        identifier="Alice",
+        project=test_project.name,
+    )
+
+    # Should return guidance string about missing schema
+    assert isinstance(result, str)
+    assert "No Schema Found" in result
+    assert "person" in result
 
 
 @pytest.mark.asyncio
@@ -214,8 +307,9 @@ async def test_write_note_metadata_creates_schema_note(app, test_project, sync_s
         project=test_project.name,
     )
 
-    assert isinstance(result, ValidationReport)
-    assert result.total_notes >= 2
+    assert isinstance(result, str)
+    assert "Schema Validation: person" in result
+    assert "valid" in result
 
 
 @pytest.mark.asyncio
@@ -279,10 +373,13 @@ async def test_schema_title_mismatch_finds_by_metadata(app, test_project, sync_s
         project=test_project.name,
     )
 
-    assert isinstance(result, ValidationReport)
-    assert result.total_notes == 2
+    assert isinstance(result, str)
+    assert "Schema Validation: employee" in result
+    assert "Notes: 2" in result
+    assert "Valid: 2" in result
     # Both notes have name + department, schema requires name and optionally department
-    assert result.valid_count == 2
+    assert "**Alice**" in result
+    assert "**Bob**" in result
 
 
 # --- Empty schema guard ---