basic-memory 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

basic_memory/schemas/base.py

@@ -181,6 +181,9 @@ class Entity(BaseModel):
     - Optional relations to other entities
     - Optional description for high-level overview
     """
+    
+    # private field to override permalink
+    _permalink: Optional[str] = None
 
     title: str
     content: Optional[str] = None
@@ -199,8 +202,8 @@ class Entity(BaseModel):
     
     @property
     def permalink(self) -> PathId:
-        """Get the path ID in format {snake_case_title}."""
-        return generate_permalink(self.file_path)
+        """Get a url friendly path}."""
+        return self._permalink or generate_permalink(self.file_path)
 
     @model_validator(mode="after")
     @classmethod

basic_memory/schemas/memory.py

@@ -59,6 +59,7 @@ def memory_url_path(url: memory_url) -> str:
 class EntitySummary(BaseModel):
     """Simplified entity representation."""
 
+    type: str = "entity"
     permalink: str
     title: str
     file_path: str
@@ -68,8 +69,9 @@ class EntitySummary(BaseModel):
 class RelationSummary(BaseModel):
     """Simplified relation representation."""
 
+    type: str = "relation"
     permalink: str
-    type: str
+    relation_type: str
     from_id: str
     to_id: Optional[str] = None
 
@@ -77,6 +79,7 @@ class RelationSummary(BaseModel):
 class ObservationSummary(BaseModel):
     """Simplified observation representation."""
 
+    type: str = "observation"
     permalink: str
     category: str
     content: str

basic_memory/services/__init__.py

@@ -1,5 +1,5 @@
 """Services package."""
-
+from .database_service import DatabaseService
 from .service import BaseService
 from .file_service import FileService
 from .entity_service import EntityService
@@ -8,4 +8,5 @@ __all__ = [
     "BaseService",
     "FileService",
     "EntityService",
+    "DatabaseService"
 ]

basic_memory/services/context_service.py

@@ -76,7 +76,7 @@ class ContextService:
                 primary = await self.search_repository.search(permalink=path)
         else:
             logger.debug(f"Build context for '{types}'")
-            primary = await self.search_repository.search(types=types)
+            primary = await self.search_repository.search(types=types, after_date=since)
 
         # Get type_id pairs for traversal
 

basic_memory/services/database_service.py

@@ -0,0 +1,158 @@
+"""Service for managing database lifecycle and schema validation."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Tuple, List
+
+from alembic.runtime.migration import MigrationContext
+from alembic.autogenerate import compare_metadata
+from loguru import logger
+from sqlalchemy import MetaData
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from basic_memory import db
+from basic_memory.config import ProjectConfig
+from basic_memory.models import Base
+
+
+async def check_schema_matches_models(session: AsyncSession) -> Tuple[bool, List[str]]:
+    """Check if database schema matches SQLAlchemy models.
+    
+    Returns:
+        tuple[bool, list[str]]: (matches, list of differences)
+    """
+    # Get current DB schema via migration context
+    conn = await session.connection()
+
+    def _compare_schemas(connection):
+        context = MigrationContext.configure(connection)
+        return compare_metadata(context, Base.metadata)
+
+    # Run comparison in sync context
+    differences = await conn.run_sync(_compare_schemas)
+    
+    if not differences:
+        return True, []
+        
+    # Format differences into readable messages
+    diff_messages = []
+    for diff in differences:
+        if diff[0] == 'add_table':
+            diff_messages.append(f"Missing table: {diff[1].name}")
+        elif diff[0] == 'remove_table':
+            diff_messages.append(f"Extra table: {diff[1].name}")
+        elif diff[0] == 'add_column':
+            diff_messages.append(f"Missing column: {diff[3]} in table {diff[2]}")
+        elif diff[0] == 'remove_column':
+            diff_messages.append(f"Extra column: {diff[3]} in table {diff[2]}")
+        elif diff[0] == 'modify_type':
+            diff_messages.append(f"Column type mismatch: {diff[3]} in table {diff[2]}")
+            
+    return False, diff_messages
+
+
+class DatabaseService:
+    """Manages database lifecycle including schema validation and backups."""
+
+    def __init__(
+        self,
+        config: ProjectConfig,
+        db_type: db.DatabaseType = db.DatabaseType.FILESYSTEM,
+    ):
+        self.config = config
+        self.db_path = Path(config.database_path)
+        self.db_type = db_type
+
+    async def create_backup(self) -> Optional[Path]:
+        """Create backup of existing database file.
+
+        Returns:
+            Optional[Path]: Path to backup file if created, None if no DB exists
+        """
+        if self.db_type == db.DatabaseType.MEMORY:
+            return None  # Skip backups for in-memory DB
+
+        if not self.db_path.exists():
+            return None
+
+        # Create backup with timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_path = self.db_path.with_suffix(f".{timestamp}.backup")
+
+        try:
+            self.db_path.rename(backup_path)
+            logger.info(f"Created database backup: {backup_path}")
+            
+            # make a new empty file
+            self.db_path.touch()
+            return backup_path
+        except Exception as e:
+            logger.error(f"Failed to create database backup: {e}")
+            return None
+
+    async def initialize_db(self):
+        """Initialize database with current schema."""
+        logger.info("Initializing database...")
+
+        if self.db_type == db.DatabaseType.FILESYSTEM:
+            await self.create_backup()
+
+        # Drop existing tables if any
+        await db.drop_db()
+
+        # Create tables with current schema
+        await db.get_or_create_db(
+            db_path=self.db_path,
+            db_type=self.db_type
+        )
+
+        logger.info("Database initialized with current schema")
+
+    async def check_db(self) -> bool:
+        """Check database state and rebuild if schema doesn't match models.
+        
+        Returns:
+            bool: True if DB is ready for use, False if initialization failed
+        """
+        try:
+            _, session_maker = await db.get_or_create_db(
+                db_path=self.db_path,
+                db_type=self.db_type
+            )
+            async with db.scoped_session(session_maker) as db_session:
+                # Check actual schema matches
+                matches, differences = await check_schema_matches_models(db_session)
+                if not matches:
+                    logger.warning("Database schema does not match models:")
+                    for diff in differences:
+                        logger.warning(f"  {diff}")
+                    logger.info("Rebuilding database to match current models...")
+                    await self.initialize_db()
+                    return True
+                    
+                logger.info("Database schema matches models")
+                return True
+
+        except Exception as e:
+            logger.error(f"Database initialization failed: {e}")
+            return False
+
+    async def cleanup_backups(self, keep_count: int = 5):
+        """Clean up old database backups, keeping the N most recent."""
+        if self.db_type == db.DatabaseType.MEMORY:
+            return  # Skip cleanup for in-memory DB
+
+        backup_pattern = "*.backup"  # Use relative pattern
+        backups = sorted(
+            self.db_path.parent.glob(backup_pattern),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+
+        # Remove old backups
+        for backup in backups[keep_count:]:
+            try:
+                backup.unlink()
+                logger.debug(f"Removed old backup: {backup}")
+            except Exception as e:
+                logger.error(f"Failed to remove backup {backup}: {e}")

basic_memory/services/entity_service.py

@@ -19,6 +19,7 @@ from basic_memory.services import FileService
 from basic_memory.services import BaseService
 from basic_memory.services.link_resolver import LinkResolver
 from basic_memory.markdown.entity_parser import EntityParser
+from basic_memory.utils import generate_permalink
 
 
 class EntityService(BaseService[EntityModel]):
@@ -40,6 +41,51 @@ class EntityService(BaseService[EntityModel]):
         self.file_service = file_service
         self.link_resolver = link_resolver
 
+    async def resolve_permalink(
+            self,
+            file_path: Path,
+            markdown: Optional[EntityMarkdown] = None
+    ) -> str:
+        """Get or generate unique permalink for an entity.
+
+        Priority:
+        1. If markdown has permalink and it's not used by another file -> use as is
+        2. If markdown has permalink but it's used by another file -> make unique
+        3. For existing files, keep current permalink from db
+        4. Generate new unique permalink from file path
+        """
+        file_path = str(file_path)
+
+        # If markdown has explicit permalink, try to validate it
+        if markdown and markdown.frontmatter.permalink:
+            desired_permalink = markdown.frontmatter.permalink
+            existing = await self.repository.get_by_permalink(desired_permalink)
+
+            # If no conflict or it's our own file, use as is
+            if not existing or existing.file_path == file_path:
+                return desired_permalink
+
+        # For existing files, try to find current permalink
+        existing = await self.repository.get_by_file_path(file_path)
+        if existing:
+            return existing.permalink
+
+        # New file - generate permalink
+        if markdown and markdown.frontmatter.permalink:
+            desired_permalink = markdown.frontmatter.permalink
+        else:
+            desired_permalink = generate_permalink(file_path)
+
+        # Make unique if needed
+        permalink = desired_permalink
+        suffix = 1
+        while await self.repository.get_by_permalink(permalink):
+            permalink = f"{desired_permalink}-{suffix}"
+            suffix += 1
+            logger.debug(f"creating unique permalink: {permalink}")
+
+        return permalink
+    
     async def create_or_update_entity(self, schema: EntitySchema) -> (EntityModel, bool):
         """Create new entity or update existing one.
         if a new entity is created, the return value is (entity, True)
@@ -66,9 +112,13 @@ class EntityService(BaseService[EntityModel]):
 
         if await self.file_service.exists(file_path):
             raise EntityCreationError(
-                f"file_path {file_path} for entity {schema.permalink} already exists: {file_path}"
+                f"file for entity {schema.folder}/{schema.title} already exists: {file_path}"
             )
 
+        # Get unique permalink
+        permalink = await self.resolve_permalink(schema.permalink or file_path)
+        schema._permalink = permalink
+
         post = await schema_to_markdown(schema)
 
         # write file
@@ -184,7 +234,7 @@ class EntityService(BaseService[EntityModel]):
         Creates the entity with null checksum to indicate sync not complete.
         Relations will be added in second pass.
         """
-        logger.debug(f"Creating entity: {markdown.frontmatter.title}")
+        logger.debug(f"Creating entity: {markdown.frontmatter.title}")        
         model = entity_model_from_markdown(file_path, markdown)
 
         # Mark as incomplete sync

basic_memory/services/file_service.py

@@ -35,7 +35,6 @@ class FileService:
         """Generate absolute filesystem path for entity."""
         return self.base_path / f"{entity.file_path}"
 
-    # TODO move to tests
     async def write_entity_file(
         self,
         entity: EntityModel,

basic_memory/sync/sync_service.py

@@ -5,6 +5,7 @@ from typing import Dict
 
 from loguru import logger
 
+from basic_memory import file_utils
 from basic_memory.markdown import EntityParser, EntityMarkdown
 from basic_memory.repository import EntityRepository, RelationRepository
 from basic_memory.services import EntityService
@@ -92,8 +93,32 @@ class SyncService:
         # First pass: Create/update entities
         # entities will have a null checksum to indicate they are not complete
         for file_path, entity_markdown in parsed_entities.items():
+
+            # Get unique permalink and update markdown if needed
+            permalink = await self.entity_service.resolve_permalink(
+                file_path,
+                markdown=entity_markdown
+            )
+
+            if permalink != entity_markdown.frontmatter.permalink:
+                # Add/update permalink in frontmatter
+                logger.info(f"Adding permalink '{permalink}' to file: {file_path}")
+
+                # update markdown
+                entity_markdown.frontmatter.metadata["permalink"] = permalink
+                
+                # update file frontmatter
+                updated_checksum = await file_utils.update_frontmatter(
+                    directory / file_path,
+                    {"permalink": permalink}
+                )
+
+                # Update checksum in changes report since file was modified
+                changes.checksums[file_path] = updated_checksum
+            
             # if the file is new, create an entity
             if file_path in changes.new:
+                # Create entity with final permalink
                 logger.debug(f"Creating new entity_markdown: {file_path}")
                 await self.entity_service.create_entity_from_markdown(
                     file_path, entity_markdown

basic_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: basic-memory
+Version: 0.1.0
+Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
+Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
+Project-URL: Repository, https://github.com/basicmachines-co/basic-memory
+Project-URL: Documentation, https://github.com/basicmachines-co/basic-memory#readme
+Author-email: Basic Machines <hello@basic-machines.co>
+License: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12.1
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.14.1
+Requires-Dist: dateparser>=1.2.0
+Requires-Dist: fastapi[standard]>=0.115.8
+Requires-Dist: greenlet>=3.1.1
+Requires-Dist: icecream>=2.1.3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic-settings>=2.6.1
+Requires-Dist: pydantic[email,timezone]>=2.10.3
+Requires-Dist: pyright>=1.1.390
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.9.4
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: unidecode>=1.3.8
+Requires-Dist: watchfiles>=1.0.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.1.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Basic Memory
+
+Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
+Claude, while keeping everything in simple markdown files on your computer. It uses the Model Context Protocol (MCP) to
+enable any compatible LLM to read and write to your local knowledge base.
+
+## What is Basic Memory?
+
+Most people use LLMs like calculators - paste in some text, expect to get an answer back, repeat. Each conversation
+starts fresh,
+and any knowledge or context is lost. Some try to work around this by:
+
+- Saving chat histories (but they're hard to reference)
+- Copying and pasting previous conversations (messy and repetitive)
+- Using RAG systems to query documents (complex and often cloud-based)
+
+Basic Memory takes a different approach by letting both humans and LLMs read and write knowledge naturally using
+standard markdown files. This means:
+
+- Your knowledge stays in files you control
+- Both you and the LLM can read and write notes
+- Context persists across conversations
+- Context stays local and user controlled
+
+## How It Works in Practice
+
+Let's say you're working on a new project and want to capture design decisions. Here's how it works:
+
+1. Start by chatting normally:
+
+```markdown
+We need to design a new auth system, some key features:
+
+- local first, don't delegate users to third party system
+- support multiple platforms via jwt
+- want to keep it simple but secure
+```
+
+... continue conversation.
+
+2. Ask Claude to help structure this knowledge:
+
+```
+"Lets write a note about the auth system design."
+```
+
+Claude creates a new markdown file on your system (which you can see instantly in Obsidian or your editor):
+
+```markdown
+---
+title: Auth System Design
+permalink: auth-system-design
+tags
+- design
+- auth
+---
+
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+```
+
+The note embeds semantic content (Observations) and links to other topics (Relations) via simple markdown formatting.
+
+3. You can edit this file directly in your editor in real time:
+
+```markdown
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+- [decision] Will use bcrypt for password hashing # Added by you
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+- blocks [[User Service]]  # Added by you
+```
+
+4. In a new chat with Claude, you can reference this knowledge:
+
+```
+"Claude, look at memory://auth-system-design for context about our auth system"
+```
+
+Claude can now build rich context from the knowledge graph. For example:
+
+```
+Following relation 'implements [[Security Requirements]]':
+- Found authentication best practices
+- OWASP guidelines for JWT
+- Rate limiting requirements
+
+Following relation 'relates_to [[Platform Support]]':
+- Mobile auth requirements 
+- Browser security considerations
+- JWT storage strategies
+```
+
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base. All of
+this context comes from standard markdown files that both humans and LLMs can read and write.
+
+Everything stays in local markdown files that you can:
+
+- Edit in any text editor
+- Version via git
+- Back up normally
+- Share when you want to
+
+## Technical Implementation
+
+Under the hood, Basic Memory:
+
+1. Stores everything in markdown files
+2. Uses a SQLite database just for searching and indexing
+3. Extracts semantic meaning from simple markdown patterns
+4. Maintains a local knowledge graph from file content
+
+The file format is just markdown with some simple markup:
+
+Frontmatter
+
+- title
+- type
+- permalink
+- optional metadata
+
+Observations
+
+- facts about a topic
+
+```markdown
+- [category] content #tag (optional context)
+```
+
+Relations
+
+- links to other topics
+
+```markdown
+- relation_type [[WikiLink]] (optional context)
+```
+
+Example:
+
+```markdown
+---
+title: Note tile
+type: note
+permalink: unique/stable/id  # Added automatically
+tags
+- tag1
+- tag2
+---
+
+# Note Title
+
+Regular markdown content...
+
+## Observations
+
+- [category] Structured knowledge #tag (optional context)
+- [idea] Another observation
+
+## Relations
+
+- links_to [[Other Note]]
+- implements [[Some Spec]]
+```
+
+Basic Memory will parse the markdown and derive the semantic relationships in the content. When you run
+`basic-memory sync`:
+
+1. New and changed files are detected
+2. Markdown patterns become semantic knowledge:
+
+- `[tech]` becomes a categorized observation
+- `[[WikiLink]]` creates a relation in the knowledge graph
+- Tags and metadata are indexed for search
+
+3. A SQLite database maintains these relationships for fast querying
+4. Claude and other MCP-compatible LLMs can access this knowledge via memory:// URLs
+
+This creates a two-way flow where:
+
+- Humans write and edit markdown files
+- LLMs read and write through the MCP protocol
+- Sync keeps everything consistent
+- All knowledge stays in local files.
+
+## Using with Claude
+
+Basic Memory works with the Claude desktop app (https://claude.ai/):
+
+1. Install Basic Memory locally:
+
+```bash
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory"
+      ]
+    }
+}
+```
+
+2. Add to Claude Desktop:
+
+```
+Basic Memory is available with these tools:
+- write_note() for creating/updating notes
+- read_note() for loading notes
+- build_context() to load notes via memory:// URLs
+- recent_activity() to find recently updated information
+- search() to search infomation in the knowledge base
+```
+
+3. Install via uv
+
+```bash
+uv add  basic-memory
+
+# sync local knowledge updates
+basic-memory sync
+
+# run realtime sync process
+basic-memory sync --watch
+```
+
+## Design Philosophy
+
+Basic Memory is built on some key ideas:
+
+- Your knowledge should stay in files you control
+- Both humans and AI should use natural formats
+- Simple text patterns can capture rich meaning
+- Local-first doesn't mean feature-poor
+
+## License
+
+AGPL-3.0