feat: Add disable_permalinks config flag (#313)

phernandez · github-actions[bot] · claude · web-flow · commit 903591384dff · 2025-10-03T22:11:47.000-05:00
Signed-off-by: phernandez &lt;paul@basicmachines.co&gt;
Co-authored-by: claude[bot] &lt;41898282+claude[bot]@users.noreply.github.com&gt;
Co-authored-by: Paul Hernandez &lt;phernandez@users.noreply.github.com&gt;
Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/src/basic_memory/cli/commands/cloud/api_client.py b/src/basic_memory/cli/commands/cloud/api_client.py
@@ -90,7 +90,10 @@ async def make_api_request(
                     # Handle both FastAPI HTTPException format (nested under "detail")
                     # and direct format
                     detail_obj = error_detail.get("detail", error_detail)
-                    if isinstance(detail_obj, dict) and detail_obj.get("error") == "subscription_required":
+                    if (
+                        isinstance(detail_obj, dict)
+                        and detail_obj.get("error") == "subscription_required"
+                    ):
                         message = detail_obj.get("message", "Active subscription required")
                         subscribe_url = detail_obj.get(
                             "subscribe_url", "https://basicmemory.com/subscribe"
diff --git a/src/basic_memory/config.py b/src/basic_memory/config.py
@@ -93,11 +93,22 @@ class BasicMemoryConfig(BaseSettings):
         description="Format for generated filenames. False preserves spaces and special chars, True converts them to hyphens for consistency with permalinks",
     )
 
+    disable_permalinks: bool = Field(
+        default=False,
+        description="Disable automatic permalink generation in frontmatter. When enabled, new notes won't have permalinks added and sync won't update permalinks. Existing permalinks will still work for reading.",
+    )
+
     skip_initialization_sync: bool = Field(
         default=False,
         description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",
     )
 
+    # API connection configuration
+    api_url: Optional[str] = Field(
+        default=None,
+        description="URL of remote Basic Memory API. If set, MCP will connect to this API instead of using local ASGI transport.",
+    )
+
     # Cloud configuration
     cloud_client_id: str = Field(
         default="client_01K6KWQPW6J1M8VV7R3TZP5A6M",
diff --git a/src/basic_memory/deps.py b/src/basic_memory/deps.py
@@ -260,6 +260,7 @@ async def get_entity_service(
     entity_parser: EntityParserDep,
     file_service: FileServiceDep,
     link_resolver: "LinkResolverDep",
+    app_config: AppConfigDep,
 ) -> EntityService:
     """Create EntityService with repository."""
     return EntityService(
@@ -269,6 +270,7 @@ async def get_entity_service(
         entity_parser=entity_parser,
         file_service=file_service,
         link_resolver=link_resolver,
+        app_config=app_config,
     )
 
 
diff --git a/src/basic_memory/schemas/base.py b/src/basic_memory/schemas/base.py
@@ -197,6 +197,7 @@ class Entity(BaseModel):
     """
 
     # private field to override permalink
+    # Use empty string "" as sentinel to indicate permalinks are explicitly disabled
     _permalink: Optional[str] = None
 
     title: str
@@ -247,8 +248,11 @@ def file_path(self):
             return os.path.join(self.folder, safe_title) if self.folder else safe_title
 
     @property
-    def permalink(self) -> Permalink:
+    def permalink(self) -> Optional[Permalink]:
         """Get a url friendly path}."""
+        # Empty string is a sentinel value indicating permalinks are disabled
+        if self._permalink == "":
+            return None
         return self._permalink or generate_permalink(self.file_path)
 
     @model_validator(mode="after")
diff --git a/src/basic_memory/services/entity_service.py b/src/basic_memory/services/entity_service.py
@@ -42,13 +42,15 @@ def __init__(
         relation_repository: RelationRepository,
         file_service: FileService,
         link_resolver: LinkResolver,
+        app_config: Optional[BasicMemoryConfig] = None,
     ):
         super().__init__(entity_repository)
         self.observation_repository = observation_repository
         self.relation_repository = relation_repository
         self.entity_parser = entity_parser
         self.file_service = file_service
         self.link_resolver = link_resolver
+        self.app_config = app_config
 
     async def detect_file_path_conflicts(self, file_path: str) -> List[Entity]:
         """Detect potential file path conflicts for a given file path.
@@ -145,9 +147,9 @@ async def create_or_update_entity(self, schema: EntitySchema) -> Tuple[EntityMod
         )
 
         # Try to find existing entity using smart resolution
-        existing = await self.link_resolver.resolve_link(
-            schema.file_path
-        ) or await self.link_resolver.resolve_link(schema.permalink)
+        existing = await self.link_resolver.resolve_link(schema.file_path)
+        if not existing and schema.permalink:
+            existing = await self.link_resolver.resolve_link(schema.permalink)
 
         if existing:
             logger.debug(f"Found existing entity: {existing.file_path}")
@@ -194,9 +196,15 @@ async def create_entity(self, schema: EntitySchema) -> EntityModel:
                     relations=[],
                 )
 
-        # Get unique permalink (prioritizing content frontmatter)
-        permalink = await self.resolve_permalink(file_path, content_markdown)
-        schema._permalink = permalink
+        # Get unique permalink (prioritizing content frontmatter) unless disabled
+        if self.app_config and self.app_config.disable_permalinks:
+            # Use empty string as sentinel to indicate permalinks are disabled
+            # The permalink property will return None when it sees empty string
+            schema._permalink = ""
+        else:
+            # Generate and set permalink
+            permalink = await self.resolve_permalink(file_path, content_markdown)
+            schema._permalink = permalink
 
         post = await schema_to_markdown(schema)
 
@@ -254,15 +262,16 @@ async def update_entity(self, entity: EntityModel, schema: EntitySchema) -> Enti
                     relations=[],
                 )
 
-        # Check if we need to update the permalink based on content frontmatter
+        # Check if we need to update the permalink based on content frontmatter (unless disabled)
         new_permalink = entity.permalink  # Default to existing
-        if content_markdown and content_markdown.frontmatter.permalink:
-            # Resolve permalink with the new content frontmatter
-            resolved_permalink = await self.resolve_permalink(file_path, content_markdown)
-            if resolved_permalink != entity.permalink:
-                new_permalink = resolved_permalink
-                # Update the schema to use the new permalink
-                schema._permalink = new_permalink
+        if self.app_config and not self.app_config.disable_permalinks:
+            if content_markdown and content_markdown.frontmatter.permalink:
+                # Resolve permalink with the new content frontmatter
+                resolved_permalink = await self.resolve_permalink(file_path, content_markdown)
+                if resolved_permalink != entity.permalink:
+                    new_permalink = resolved_permalink
+                    # Update the schema to use the new permalink
+                    schema._permalink = new_permalink
 
         # Create post with new content from schema
         post = await schema_to_markdown(schema)
@@ -746,8 +755,10 @@ async def move_entity(
             # 6. Prepare database updates
             updates = {"file_path": destination_path}
 
-            # 7. Update permalink if configured or if entity has null permalink
-            if app_config.update_permalinks_on_move or old_permalink is None:
+            # 7. Update permalink if configured or if entity has null permalink (unless disabled)
+            if not app_config.disable_permalinks and (
+                app_config.update_permalinks_on_move or old_permalink is None
+            ):
                 # Generate new permalink from destination path
                 new_permalink = await self.resolve_permalink(destination_path)
 
diff --git a/src/basic_memory/sync/sync_service.py b/src/basic_memory/sync/sync_service.py
@@ -338,8 +338,8 @@ async def sync_markdown_file(self, path: str, new: bool = True) -> Tuple[Optiona
         # entity markdown will always contain front matter, so it can be used up create/update the entity
         entity_markdown = await self.entity_parser.parse_file(path)
 
-        # if the file contains frontmatter, resolve a permalink
-        if file_contains_frontmatter:
+        # if the file contains frontmatter, resolve a permalink (unless disabled)
+        if file_contains_frontmatter and not self.app_config.disable_permalinks:
             # Resolve permalink - this handles all the cases including conflicts
             permalink = await self.entity_service.resolve_permalink(path, markdown=entity_markdown)
 
@@ -530,8 +530,10 @@ async def handle_move(self, old_path, new_path):
             updates = {"file_path": new_path}
 
             # If configured, also update permalink to match new path
-            if self.app_config.update_permalinks_on_move and self.file_service.is_markdown(
-                new_path
+            if (
+                self.app_config.update_permalinks_on_move
+                and not self.app_config.disable_permalinks
+                and self.file_service.is_markdown(new_path)
             ):
                 # generate new permalink value
                 new_permalink = await self.entity_service.resolve_permalink(new_path)
diff --git a/src/basic_memory/sync/watch_service.py b/src/basic_memory/sync/watch_service.py
@@ -121,7 +121,9 @@ async def _watch_projects_cycle(self, projects: Sequence[Project], stop_event: a
                         ignore_patterns = self._get_ignore_patterns(project_path)
 
                         if should_ignore_path(file_path, project_path, ignore_patterns):
-                            logger.trace(f"Ignoring watched file change: {file_path.relative_to(project_path)}")
+                            logger.trace(
+                                f"Ignoring watched file change: {file_path.relative_to(project_path)}"
+                            )
                             continue
 
                         project_changes[project].append((change, path))
diff --git a/test-int/test_disable_permalinks_integration.py b/test-int/test_disable_permalinks_integration.py
@@ -0,0 +1,141 @@
+"""Integration tests for the disable_permalinks configuration."""
+
+import pytest
+from pathlib import Path
+from textwrap import dedent
+
+from basic_memory.config import BasicMemoryConfig
+from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.models import Project
+from basic_memory.repository import (
+    EntityRepository,
+    ObservationRepository,
+    RelationRepository,
+)
+from basic_memory.repository.search_repository import SearchRepository
+from basic_memory.schemas import Entity as EntitySchema
+from basic_memory.services import FileService
+from basic_memory.services.entity_service import EntityService
+from basic_memory.services.link_resolver import LinkResolver
+from basic_memory.services.search_service import SearchService
+from basic_memory.sync.sync_service import SyncService
+
+
+@pytest.mark.asyncio
+async def test_disable_permalinks_create_entity(tmp_path, engine_factory):
+    """Test that entities created with disable_permalinks=True don't have permalinks."""
+    engine, session_maker = engine_factory
+
+    # Create app config with disable_permalinks=True
+    app_config = BasicMemoryConfig(disable_permalinks=True)
+
+    # Setup repositories
+    entity_repository = EntityRepository(session_maker, project_id=1)
+    observation_repository = ObservationRepository(session_maker, project_id=1)
+    relation_repository = RelationRepository(session_maker, project_id=1)
+    search_repository = SearchRepository(session_maker, project_id=1)
+
+    # Setup services
+    entity_parser = EntityParser(tmp_path)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(tmp_path, markdown_processor)
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    await search_service.init_search_index()
+    link_resolver = LinkResolver(entity_repository, search_service)
+
+    entity_service = EntityService(
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        app_config=app_config,
+    )
+
+    # Create entity via API
+    entity_data = EntitySchema(
+        title="Test Note",
+        folder="test",
+        entity_type="note",
+        content="Test content",
+    )
+
+    created = await entity_service.create_entity(entity_data)
+
+    # Verify entity has no permalink
+    assert created.permalink is None
+
+    # Verify file has no permalink in frontmatter
+    file_path = tmp_path / "test" / "Test Note.md"
+    assert file_path.exists()
+    content = file_path.read_text()
+    assert "permalink:" not in content
+    assert "Test content" in content
+
+
+@pytest.mark.asyncio
+async def test_disable_permalinks_sync_workflow(tmp_path, engine_factory):
+    """Test full sync workflow with disable_permalinks enabled."""
+    engine, session_maker = engine_factory
+
+    # Create app config with disable_permalinks=True
+    app_config = BasicMemoryConfig(disable_permalinks=True)
+
+    # Create a test markdown file without frontmatter
+    test_file = tmp_path / "test_note.md"
+    test_file.write_text("# Test Note\nThis is test content.")
+
+    # Setup repositories
+    entity_repository = EntityRepository(session_maker, project_id=1)
+    observation_repository = ObservationRepository(session_maker, project_id=1)
+    relation_repository = RelationRepository(session_maker, project_id=1)
+    search_repository = SearchRepository(session_maker, project_id=1)
+
+    # Setup services
+    entity_parser = EntityParser(tmp_path)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(tmp_path, markdown_processor)
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    await search_service.init_search_index()
+    link_resolver = LinkResolver(entity_repository, search_service)
+
+    entity_service = EntityService(
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        app_config=app_config,
+    )
+
+    sync_service = SyncService(
+        app_config=app_config,
+        entity_service=entity_service,
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        relation_repository=relation_repository,
+        search_service=search_service,
+        file_service=file_service,
+    )
+
+    # Run sync
+    report = await sync_service.scan(tmp_path)
+    # Note: scan may pick up database files too, so just check our file is there
+    assert "test_note.md" in report.new
+
+    # Sync the file
+    await sync_service.sync_file("test_note.md", new=True)
+
+    # Verify file has no permalink added
+    content = test_file.read_text()
+    assert "permalink:" not in content
+    assert "# Test Note" in content
+
+    # Verify entity in database has no permalink
+    entities = await entity_repository.find_all()
+    assert len(entities) == 1
+    assert entities[0].permalink is None
+    # Title is extracted from filename when no frontmatter, or from frontmatter when present
+    assert entities[0].title in ("test_note", "Test Note")
diff --git a/tests/cli/test_cloud_authentication.py b/tests/cli/test_cloud_authentication.py
@@ -70,9 +70,7 @@ async def test_parse_subscription_required_error_flat_format(self):
         mock_response.headers = {}
 
         # Create HTTPStatusError with the mock response
-        http_error = httpx.HTTPStatusError(
-            "403 Forbidden", request=Mock(), response=mock_response
-        )
+        http_error = httpx.HTTPStatusError("403 Forbidden", request=Mock(), response=mock_response)
 
         # Mock httpx client to raise the error
         with patch("basic_memory.cli.commands.cloud.api_client.httpx.AsyncClient") as mock_client:
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -200,6 +200,7 @@ async def entity_service(
     entity_parser: EntityParser,
     file_service: FileService,
     link_resolver: LinkResolver,
+    app_config: BasicMemoryConfig,
 ) -> EntityService:
     """Create EntityService."""
     return EntityService(
@@ -209,6 +210,7 @@ async def entity_service(
         relation_repository=relation_repository,
         file_service=file_service,
         link_resolver=link_resolver,
+        app_config=app_config,
     )
 
 
diff --git a/tests/services/test_entity_service_disable_permalinks.py b/tests/services/test_entity_service_disable_permalinks.py
diff --git a/tests/test_config.py b/tests/test_config.py
