feat: Add project-prefixed permalinks and memory URL routing (#544)

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

Author: phernandez

.github/workflows/test.yml

@@ -37,18 +37,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just (Linux)
-        if: runner.os != 'Windows'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
-
-      - name: Install just (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          # Install just using Chocolatey (pre-installed on GitHub Actions Windows runners)
-          choco install just --yes
-        shell: pwsh
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |
@@ -96,10 +85,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |
@@ -133,10 +119,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |

src/basic_memory/cli/commands/import_chatgpt.py

@@ -60,7 +60,9 @@ def import_chatgpt(
         console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
 
         # Create importer and run import
-        importer = ChatGPTImporter(config.home, markdown_processor, file_service)
+        importer = ChatGPTImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
             result = run_with_cleanup(importer.import_data(json_data, folder))

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -57,7 +57,9 @@ def import_claude(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeConversationsImporter(config.home, markdown_processor, file_service)
+        importer = ClaudeConversationsImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home / folder

src/basic_memory/cli/commands/import_claude_projects.py

@@ -56,7 +56,9 @@ def import_projects(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeProjectsImporter(config.home, markdown_processor, file_service)
+        importer = ClaudeProjectsImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home / base_folder if base_folder else config.home

src/basic_memory/cli/commands/import_memory_json.py

@@ -55,7 +55,9 @@ def memory_json(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = MemoryJsonImporter(config.home, markdown_processor, file_service)
+        importer = MemoryJsonImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home if not destination_folder else config.home / destination_folder

src/basic_memory/config.py

@@ -196,6 +196,11 @@ class BasicMemoryConfig(BaseSettings):
         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.",
     )
 
+    permalinks_include_project: bool = Field(
+        default=True,
+        description="When True, generated permalinks are prefixed with the project slug (e.g., 'specs/search'). Existing permalinks remain unchanged unless explicitly updated.",
+    )
+
     skip_initialization_sync: bool = Field(
         default=False,
         description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",

src/basic_memory/deps/importers.py

@@ -41,7 +41,12 @@ async def get_chatgpt_importer(
     file_service: FileServiceDep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer)]
@@ -53,7 +58,12 @@ async def get_chatgpt_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with v2 dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterV2Dep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2)]
@@ -65,7 +75,12 @@ async def get_chatgpt_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with v2 external_id dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterV2ExternalDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2_external)]
@@ -80,7 +95,12 @@ async def get_claude_conversations_importer(
     file_service: FileServiceDep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterDep = Annotated[
@@ -94,7 +114,12 @@ async def get_claude_conversations_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with v2 dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterV2Dep = Annotated[
@@ -108,7 +133,12 @@ async def get_claude_conversations_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with v2 external_id dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterV2ExternalDep = Annotated[
@@ -125,7 +155,12 @@ async def get_claude_projects_importer(
     file_service: FileServiceDep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterDep = Annotated[ClaudeProjectsImporter, Depends(get_claude_projects_importer)]
@@ -137,7 +172,12 @@ async def get_claude_projects_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with v2 dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterV2Dep = Annotated[
@@ -151,7 +191,12 @@ async def get_claude_projects_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with v2 external_id dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterV2ExternalDep = Annotated[
@@ -168,7 +213,12 @@ async def get_memory_json_importer(
     file_service: FileServiceDep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterDep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer)]
@@ -180,7 +230,12 @@ async def get_memory_json_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with v2 dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterV2Dep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer_v2)]
@@ -192,7 +247,12 @@ async def get_memory_json_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with v2 external_id dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterV2ExternalDep = Annotated[

src/basic_memory/importers/base.py

@@ -8,6 +8,7 @@
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.markdown.schemas import EntityMarkdown
 from basic_memory.schemas.importer import ImportResult
+from basic_memory.utils import build_canonical_permalink, generate_permalink
 
 if TYPE_CHECKING:  # pragma: no cover
     from basic_memory.services.file_service import FileService
@@ -29,6 +30,7 @@ def __init__(
         base_path: Path,
         markdown_processor: MarkdownProcessor,
         file_service: "FileService",
+        project_name: Optional[str] = None,
     ):
         """Initialize the import service.
 
@@ -40,6 +42,8 @@ def __init__(
         self.base_path = base_path.resolve()  # Get absolute path
         self.markdown_processor = markdown_processor
         self.file_service = file_service
+        self.project_name = project_name
+        self.project_permalink = generate_permalink(project_name) if project_name else None
 
     @abstractmethod
     async def import_data(self, source_data, destination_folder: str, **kwargs: Any) -> T:
@@ -73,6 +77,26 @@ async def write_entity(self, entity: EntityMarkdown, file_path: str | Path) -> s
         # FileService.write_file handles directory creation and returns checksum
         return await self.file_service.write_file(file_path, content)
 
+    def canonical_permalink(self, path: str) -> str:
+        """Build a canonical permalink for imported content."""
+        include_project = True
+        # Trigger: importer has app config with permalink prefixing flag
+        # Why: imported notes should align with canonical permalink format
+        # Outcome: include project prefix when enabled
+        if self.file_service.app_config is not None:
+            include_project = self.file_service.app_config.permalinks_include_project
+
+        return build_canonical_permalink(
+            self.project_permalink,
+            path,
+            include_project=include_project,
+        )
+
+    def build_import_paths(self, path: str) -> tuple[str, str]:
+        """Return (permalink, file_path) for an imported entity."""
+        permalink = self.canonical_permalink(path)
+        return permalink, f"{path}.md"
+
     async def ensure_folder_exists(self, folder: str) -> None:
         """Ensure folder exists using FileService.
 

src/basic_memory/importers/chatgpt_importer.py

@@ -51,11 +51,20 @@ async def import_data(
             chats_imported = 0
 
             for chat in conversations:
+                created_at = chat["create_time"]
+                date_prefix = datetime.fromtimestamp(created_at).astimezone().strftime("%Y%m%d")
+                clean_title = clean_filename(chat["title"])
+                relative_path = (
+                    f"{destination_folder}/{date_prefix}-{clean_title}"
+                    if destination_folder
+                    else f"{date_prefix}-{clean_title}"
+                )
+                permalink, file_path = self.build_import_paths(relative_path)
+
                 # Convert to entity
-                entity = self._format_chat_content(destination_folder, chat)
+                entity = self._format_chat_content(chat, permalink)
 
                 # Write file using relative path - FileService handles base_path
-                file_path = f"{entity.frontmatter.metadata['permalink']}.md"
                 await self.write_entity(entity, file_path)
 
                 # Count messages
@@ -83,7 +92,7 @@ async def import_data(
             return self.handle_error("Failed to import ChatGPT conversations", e)
 
     def _format_chat_content(
-        self, folder: str, conversation: Dict[str, Any]
+        self, conversation: Dict[str, Any], permalink: str
     ) -> EntityMarkdown:  # pragma: no cover
         """Convert chat conversation to Basic Memory entity.
 
@@ -105,10 +114,6 @@ def _format_chat_content(
                 root_id = node_id
                 break
 
-        # Generate permalink
-        date_prefix = datetime.fromtimestamp(created_at).astimezone().strftime("%Y%m%d")
-        clean_title = clean_filename(conversation["title"])
-
         # Format content
         content = self._format_chat_markdown(
             title=conversation["title"],
@@ -126,7 +131,7 @@ def _format_chat_content(
                     "title": conversation["title"],
                     "created": format_timestamp(created_at),
                     "modified": format_timestamp(modified_at),
-                    "permalink": f"{folder}/{date_prefix}-{clean_title}",
+                    "permalink": permalink,
                 }
             ),
             content=content,