basicmachines-co-basic-memory/v15-docs/bug-fixes.md

# Bug Fixes and Improvements

**Status**: Bug Fixes
**Version**: v0.15.0
**Impact**: Stability, reliability, platform compatibility

## Overview

v0.15.0 includes 13+ bug fixes addressing entity conflicts, URL handling, file operations, and platform compatibility. These fixes improve stability and eliminate edge cases that could cause errors.

## Key Fixes

### 1. Entity Upsert Conflict Resolution (#328)

**Problem:**
Database-level conflicts when upserting entities with same title/folder caused crashes.

**Fix:**
Simplified entity upsert to use database-level conflict resolution with `ON CONFLICT` clause.

**Before:**
```python
# Manual conflict checking (error-prone)
existing = await get_entity_by_title(title, folder)
if existing:
    await update_entity(existing.id, data)
else:
    await insert_entity(data)
# → Could fail if concurrent insert
```

**After:**
```python
# Database handles conflict
await db.execute("""
    INSERT INTO entities (title, folder, content)
    VALUES (?, ?, ?)
    ON CONFLICT (title, folder) DO UPDATE SET content = excluded.content
""")
# → Always works, even with concurrent access
```

**Benefit:** Eliminates race conditions, more reliable writes

### 2. memory:// URL Underscore Normalization (#329)

**Problem:**
Underscores in memory:// URLs weren't normalized to hyphens, causing lookups to fail.

**Fix:**
Normalize underscores to hyphens when resolving memory:// URLs.

**Before:**
```python
# URL with underscores
url = "memory://my_note"
entity = await resolve_url(url)
# → Not found! (permalink is "my-note")
```

**After:**
```python
# Automatic normalization
url = "memory://my_note"
entity = await resolve_url(url)
# → Found! (my_note → my-note)
```

**Examples:**
- `memory://my_note` → finds entity with permalink `my-note`
- `memory://user_guide` → finds entity with permalink `user-guide`
- `memory://api_docs` → finds entity with permalink `api-docs`

**Benefit:** More forgiving URL matching, fewer lookup failures

### 3. .gitignore File Filtering (#287, #285)

**Problem:**
Sync process didn't respect .gitignore patterns, indexing sensitive files and build artifacts.

**Fix:**
Integrated .gitignore support - files matching patterns are automatically skipped during sync.

**Before:**
```bash
bm sync
# → Indexed .env files
# → Indexed node_modules/
# → Indexed build artifacts
```

**After:**
```bash
# .gitignore
.env
node_modules/
dist/

bm sync
# → Skipped .env (gitignored)
# → Skipped node_modules/ (gitignored)
# → Skipped dist/ (gitignored)
```

**Benefit:** Better security, cleaner knowledge base, faster sync

**See:** `gitignore-integration.md` for full details

### 4. move_note File Extension Handling (#281)

**Problem:**
`move_note` failed when destination path included or omitted `.md` extension inconsistently.

**Fix:**
Automatically handle file extensions - works with or without `.md`.

**Before:**
```python
# Had to match exactly
await move_note("My Note", "new-folder/my-note.md")  # ✓
await move_note("My Note", "new-folder/my-note")     # ✗ Failed
```

**After:**
```python
# Both work
await move_note("My Note", "new-folder/my-note.md")  # ✓ Works
await move_note("My Note", "new-folder/my-note")     # ✓ Works (adds .md)
```

**Automatic handling:**
- Input without `.md` → adds `.md`
- Input with `.md` → uses as-is
- Always creates valid markdown file

**Benefit:** More forgiving API, fewer errors

### 5. .env File Loading Removed (#330)

**Problem:**
Automatic .env file loading created security vulnerability - could load untrusted files.

**Fix:**
Removed automatic .env loading. Environment variables must be set explicitly.

**Impact:** Breaking change for users relying on .env files

**Migration:**
```bash
# Before: Used .env file
# .env
BASIC_MEMORY_LOG_LEVEL=DEBUG

# After: Use explicit export
export BASIC_MEMORY_LOG_LEVEL=DEBUG

# Or use direnv
# .envrc (git-ignored)
export BASIC_MEMORY_LOG_LEVEL=DEBUG
```

**Benefit:** Better security, explicit configuration

**See:** `env-file-removal.md` for migration guide

### 6. Python 3.13 Compatibility

**Problem:**
Code not tested with Python 3.13, potential compatibility issues.

**Fix:**
- Added Python 3.13 to CI test matrix
- Fixed deprecation warnings
- Verified all dependencies compatible
- Updated type hints for 3.13

**Before:**
```yaml
# .github/workflows/test.yml
python-version: ["3.10", "3.11", "3.12"]
```

**After:**
```yaml
# .github/workflows/test.yml
python-version: ["3.10", "3.11", "3.12", "3.13"]
```

**Benefit:** Full Python 3.13 support, future-proof

## Additional Fixes

### Minimum Timeframe Enforcement (#318)

**Problem:**
`recent_activity` with very short timeframes caused timezone issues.

**Fix:**
Enforce minimum 1-day timeframe to handle timezone edge cases.

```python
# Before: Could use any timeframe
await recent_activity(timeframe="1h")  # Timezone issues

# After: Minimum 1 day
await recent_activity(timeframe="1h")  # → Auto-adjusted to "1d"
```

### Permalink Collision Prevention

**Problem:**
Strict link resolution could create duplicate permalinks.

**Fix:**
Enhanced permalink uniqueness checking to prevent collisions.

### DateTime JSON Schema (#312)

**Problem:**
MCP validation failed on DateTime fields - missing proper JSON schema format.

**Fix:**
Added proper `format: "date-time"` annotations for MCP compatibility.

```python
# Before: No format
created_at: datetime

# After: With format
created_at: datetime = Field(json_schema_extra={"format": "date-time"})
```

## Testing Coverage

### Automated Tests

All fixes include comprehensive tests:

```bash
# Entity upsert conflict
tests/services/test_entity_upsert.py

# URL normalization
tests/mcp/test_build_context_validation.py

# File extension handling
tests/mcp/test_tool_move_note.py

# gitignore integration
tests/sync/test_gitignore.py
```

### Manual Testing Checklist

- [x] Entity upsert with concurrent access
- [x] memory:// URLs with underscores
- [x] .gitignore file filtering
- [x] move_note with/without .md extension
- [x] .env file not auto-loaded
- [x] Python 3.13 compatibility

## Migration Guide

### If You're Affected by These Bugs

**Entity Conflicts:**
- No action needed - automatically fixed

**memory:// URLs:**
- No action needed - URLs now more forgiving
- Previously broken URLs should work now

**.gitignore Integration:**
- Create `.gitignore` if you don't have one
- Add patterns for files to skip

**move_note:**
- No action needed - both formats now work
- Can simplify code that manually added `.md`

**.env Files:**
- See `env-file-removal.md` for full migration
- Use explicit environment variables or direnv

**Python 3.13:**
- Upgrade if desired: `pip install --upgrade basic-memory`
- Or stay on 3.10-3.12 (still supported)

## Verification

### Check Entity Upserts Work

```python
# Should not conflict
await write_note("Test", "Content", "folder")
await write_note("Test", "Updated", "folder")  # Updates, not errors
```

### Check URL Normalization

```python
# Both should work
context1 = await build_context("memory://my_note")
context2 = await build_context("memory://my-note")
# Both resolve to same entity
```

### Check .gitignore Respected

```bash
echo ".env" >> .gitignore
echo "SECRET=test" > .env
bm sync
# .env should be skipped
```

### Check move_note Extension

```python
# Both work
await move_note("Note", "folder/note.md")   # ✓
await move_note("Note", "folder/note")      # ✓
```

### Check .env Not Loaded

```bash
echo "BASIC_MEMORY_LOG_LEVEL=DEBUG" > .env
bm sync
# LOG_LEVEL not set (not auto-loaded)

export BASIC_MEMORY_LOG_LEVEL=DEBUG
bm sync
# LOG_LEVEL now set (explicit)
```

### Check Python 3.13

```bash
python3.13 --version
python3.13 -m pip install basic-memory
python3.13 -m basic_memory --version
```

## Known Issues (Fixed)

### Previously Reported, Now Fixed

1. ✅ Entity upsert conflicts (#328)
2. ✅ memory:// URL underscore handling (#329)
3. ✅ .gitignore not respected (#287, #285)
4. ✅ move_note extension issues (#281)
5. ✅ .env security vulnerability (#330)
6. ✅ Minimum timeframe issues (#318)
7. ✅ DateTime JSON schema (#312)
8. ✅ Permalink collisions
9. ✅ Python 3.13 compatibility

## Upgrade Notes

### From v0.14.x

All bug fixes apply automatically:

```bash
# Upgrade
pip install --upgrade basic-memory

# Restart MCP server
# Bug fixes active immediately
```

### Breaking Changes

Only one breaking change:

- ✅ .env file auto-loading removed (#330)
  - See `env-file-removal.md` for migration

All other fixes are backward compatible.

## Reporting New Issues

If you encounter issues:

1. Check this list to see if already fixed
2. Verify you're on v0.15.0+: `bm --version`
3. Report at: https://github.com/basicmachines-co/basic-memory/issues

## See Also

- `gitignore-integration.md` - .gitignore support details
- `env-file-removal.md` - .env migration guide
- GitHub issues for each fix
- v0.15.0 changelog