chore(release): 0.12.3 [skip ci]

Signed-off-by: phernandez <paul@basicmachines.co>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve Basic Memory
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+A clear and concise description of what the bug is.
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+1. Install version '...'
+2. Run command '...'
+3. Use tool/feature '...'
+4. See error
+
+## Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+What actually happened, including error messages and output.
+
+## Environment
+- OS: [e.g. macOS 14.2, Ubuntu 22.04]
+- Python version: [e.g. 3.12.1]
+- Basic Memory version: [e.g. 0.1.0]
+- Installation method: [e.g. pip, uv, source]
+- Claude Desktop version (if applicable):
+
+## Additional Context
+- Configuration files (if relevant)
+- Logs or screenshots
+- Any special configuration or environment variables
+
+## Possible Solution
+If you have any ideas on what might be causing the issue or how to fix it, please share them here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Basic Memory Discussions
+    url: https://github.com/basicmachines-co/basic-memory/discussions
+    about: For questions, ideas, or more open-ended discussions
+  - name: Documentation
+    url: https://github.com/basicmachines-co/basic-memory#readme
+    about: Please check the documentation first before reporting an issue

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,19 @@
+---
+name: Documentation improvement
+about: Suggest improvements or report issues with documentation
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Issue
+Describe what's missing, unclear, or incorrect in the current documentation.
+
+## Location
+Where is the problematic documentation? (URL, file path, or section)
+
+## Suggested Improvement
+How would you improve this documentation? Please be as specific as possible.
+
+## Additional Context
+Any additional information or screenshots that might help explain the issue or improvement.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest an idea for Basic Memory
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+A clear and concise description of the feature you'd like to see implemented.
+
+## Problem This Feature Solves
+Describe the problem or limitation you're experiencing that this feature would address.
+
+## Proposed Solution
+Describe how you envision this feature working. Include:
+- User workflow
+- Interface design (if applicable)
+- Technical approach (if you have ideas)
+
+## Alternative Solutions
+Have you considered any alternative solutions or workarounds?
+
+## Additional Context
+Add any other context, screenshots, or examples about the feature request here.
+
+## Impact
+How would this feature benefit you and other users of Basic Memory?

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+      

.github/workflows/claude-code-actions.yml

@@ -0,0 +1,16 @@
+name: Claude Code Integration
+
+on:
+  issue_comment:
+    types: [ created ]
+  pull_request_review_comment:
+    types: [ created ]
+
+jobs:
+  claude-integration:
+    uses: basicmachines-co/claude-code-github-action/.github/workflows/claude-full.yml@v0.11.0
+    with:
+      issue-label: 'claude-fix'  # Optional: customize the trigger label
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      PERSONAL_ACCESS_TOKEN: ${{ secrets.CLAUDE_TOKEN }}

.github/workflows/release.yml

@@ -57,10 +57,14 @@ jobs:
         with:
           ref: ${{ needs.release.outputs.tag }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Set up Python "3.12"
+        uses: actions/setup-python@v4
         with:
-          python-version: '3.12'
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install librsvg
+        run: brew install librsvg
 
       - name: Install uv
         run: |
@@ -70,27 +74,19 @@ jobs:
         run: |
           uv venv
 
-      - name: Install librsvg
-        run: brew install librsvg
-
-      - name: Create icon
+      - name: Install dependencies
         run: |
-          cd installer
-          chmod +x make_icons.sh
-          ./make_icons.sh
+          uv sync
 
       - name: Build macOS installer
         run: |
-          uv pip install -e ".[dev]"
           make installer-mac
-          # Remove quarantine attribute
-          cd installer/build
-          xattr -dr com.apple.quarantine "Basic Memory Installer.app"
+          xattr -dr com.apple.quarantine "installer/build/Basic Memory Installer.app"
 
       - name: Zip macOS installer
         run: |
           cd installer/build
-          zip -r "Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip" "Basic Memory Installer.app"
+          zip -ry "Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip" "Basic Memory Installer.app"
 
       - name: Upload macOS installer
         uses: softprops/action-gh-release@v1

.github/workflows/test.yml

@@ -5,6 +5,12 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  # pull_request_target runs on the BASE of the PR, not the merge result.
+  # It has write permissions and access to secrets.
+  # It's useful for PRs from forks or automated PRs but requires careful use for security reasons.
+  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
+  pull_request_target:
+    branches: [ "main" ]
 
 jobs:
   test:

.gitignore

@@ -42,3 +42,13 @@ ENV/
 
 # macOS
 .DS_Store
+/.coverage.*
+
+# obsidian docs:
+/docs/.obsidian/
+/examples/.obsidian/
+/examples/.basic-memory/
+
+
+# claude action
+claude-output

CHANGELOG.md

@@ -1,8 +1,648 @@
 # CHANGELOG
 
 
+## v0.12.3 (2025-04-17)
+
+### Bug Fixes
+
+- Add extra logic for permalink generation with mixed Latin unicode and Chinese characters
+  ([`73ea91f`](https://github.com/basicmachines-co/basic-memory/commit/73ea91fe0d1f7ab89b99a1b691d59fe608b7fcbb))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Modify recent_activity args to be strings instead of enums
+  ([`3c1cc34`](https://github.com/basicmachines-co/basic-memory/commit/3c1cc346df519e703fae6412d43a92c7232c6226))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+
+## v0.12.2 (2025-04-08)
+
+### Bug Fixes
+
+- Utf8 for all file reads/write/open instead of default platform encoding
+  ([#91](https://github.com/basicmachines-co/basic-memory/pull/91),
+  [`2934176`](https://github.com/basicmachines-co/basic-memory/commit/29341763318408ea8f1e954a41046c4185f836c6))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+
+## v0.12.1 (2025-04-07)
+
+### Bug Fixes
+
+- Run migrations and sync when starting mcp
+  ([#88](https://github.com/basicmachines-co/basic-memory/pull/88),
+  [`78a3412`](https://github.com/basicmachines-co/basic-memory/commit/78a3412bcff83b46e78e26f8b9fce42ed9e05991))
+
+
+## v0.12.0 (2025-04-06)
+
+### Bug Fixes
+
+- [bug] `#` character accumulation in markdown frontmatter tags prop
+  ([#79](https://github.com/basicmachines-co/basic-memory/pull/79),
+  [`6c19c9e`](https://github.com/basicmachines-co/basic-memory/commit/6c19c9edf5131054ba201a109b37f15c83ef150c))
+
+- [bug] Cursor has errors calling search tool
+  ([#78](https://github.com/basicmachines-co/basic-memory/pull/78),
+  [`9d581ce`](https://github.com/basicmachines-co/basic-memory/commit/9d581cee133f9dde4a0a85118868227390c84161))
+
+- [bug] Some notes never exit "modified" status
+  ([#77](https://github.com/basicmachines-co/basic-memory/pull/77),
+  [`7930ddb`](https://github.com/basicmachines-co/basic-memory/commit/7930ddb2919057be30ceac8c4c19da6aaa1d3e92))
+
+- [bug] write_note Tool Fails to Update Existing Files in Some Situations.
+  ([#80](https://github.com/basicmachines-co/basic-memory/pull/80),
+  [`9bff1f7`](https://github.com/basicmachines-co/basic-memory/commit/9bff1f732e71bc60f88b5c2ce3db5a2aa60b8e28))
+
+- Set default mcp log level to ERROR
+  ([#81](https://github.com/basicmachines-co/basic-memory/pull/81),
+  [`248214c`](https://github.com/basicmachines-co/basic-memory/commit/248214cb114a269ca60ff6398e382f9e2495ad8e))
+
+- Write_note preserves frontmatter fields in content
+  ([#84](https://github.com/basicmachines-co/basic-memory/pull/84),
+  [`3f4d9e4`](https://github.com/basicmachines-co/basic-memory/commit/3f4d9e4d872ebc0ed719c61b24d803c14a9db5e6))
+
+### Documentation
+
+- Add VS Code instructions to README
+  ([#76](https://github.com/basicmachines-co/basic-memory/pull/76),
+  [`43cbb7b`](https://github.com/basicmachines-co/basic-memory/commit/43cbb7b38cc0482ac0a41b6759320e3588186e43))
+
+- Updated basicmachines.co links to be https
+  ([#69](https://github.com/basicmachines-co/basic-memory/pull/69),
+  [`40ea28b`](https://github.com/basicmachines-co/basic-memory/commit/40ea28b0bfc60012924a69ecb76511daa4c7d133))
+
+### Features
+
+- Add watch to mcp process ([#83](https://github.com/basicmachines-co/basic-memory/pull/83),
+  [`00c8633`](https://github.com/basicmachines-co/basic-memory/commit/00c8633cfcee75ff640ff8fe81dafeb956281a94))
+
+- Permalink enhancements ([#82](https://github.com/basicmachines-co/basic-memory/pull/82),
+  [`617e60b`](https://github.com/basicmachines-co/basic-memory/commit/617e60bda4a590678a5f551f10a73e7b47e3b13e))
+
+- Avoiding "useless permalink values" for files without metadata - Enable permalinks to be updated
+  on move via config setting
+
+
+## v0.11.0 (2025-03-29)
+
+### Bug Fixes
+
+- Just delete db for reset db instead of using migrations.
+  ([#65](https://github.com/basicmachines-co/basic-memory/pull/65),
+  [`0743ade`](https://github.com/basicmachines-co/basic-memory/commit/0743ade5fc07440f95ecfd816ba7e4cfd74bca12))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Make logs for each process - mcp, sync, cli
+  ([#64](https://github.com/basicmachines-co/basic-memory/pull/64),
+  [`f1c9570`](https://github.com/basicmachines-co/basic-memory/commit/f1c95709cbffb1b88292547b0b8f29fcca22d186))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Documentation
+
+- Update broken "Multiple Projects" link in README.md
+  ([#55](https://github.com/basicmachines-co/basic-memory/pull/55),
+  [`3c68b7d`](https://github.com/basicmachines-co/basic-memory/commit/3c68b7d5dd689322205c67637dca7d188111ee6b))
+
+### Features
+
+- Add bm command alias for basic-memory
+  ([#67](https://github.com/basicmachines-co/basic-memory/pull/67),
+  [`069c0a2`](https://github.com/basicmachines-co/basic-memory/commit/069c0a21c630784e1bf47d2b7de5d6d1f6fadd7a))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Rename search tool to search_notes
+  ([#66](https://github.com/basicmachines-co/basic-memory/pull/66),
+  [`b278276`](https://github.com/basicmachines-co/basic-memory/commit/b27827671dc010be3e261b8b221aca6b7f836661))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+
+## v0.10.1 (2025-03-25)
+
+### Bug Fixes
+
+- Make set_default_project also activate project for current session to fix #37
+  ([`cbe72be`](https://github.com/basicmachines-co/basic-memory/commit/cbe72be10a646c0b03931bb39aff9285feae47f9))
+
+This change makes the 'basic-memory project default <name>' command both: 1. Set the default project
+  for future invocations (persistent change) 2. Activate the project for the current session
+  (immediate change)
+
+Added tests to verify this behavior, which resolves issue #37 where the project name and path
+  weren't changing properly when the default project was changed.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+- Make set_default_project also activate project for current session to fix #37
+  ([`46c4fd2`](https://github.com/basicmachines-co/basic-memory/commit/46c4fd21645b109af59eb2a0201c7bd849b34a49))
+
+This change makes the 'basic-memory project default <name>' command both: 1. Set the default project
+  for future invocations (persistent change) 2. Activate the project for the current session
+  (immediate change)
+
+Added tests to verify this behavior, which resolves issue #37 where the project name and path
+  weren't changing properly when the default project was changed.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Move ai_assistant_guide.md into package resources to fix #39
+  ([`390ff9d`](https://github.com/basicmachines-co/basic-memory/commit/390ff9d31ccee85bef732e8140b5eeecd7ee176f))
+
+This change relocates the AI assistant guide from the static directory into the package resources
+  directory, ensuring it gets properly included in the distribution package and is accessible when
+  installed via pip/uv.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+- Move ai_assistant_guide.md into package resources to fix #39
+  ([`cc2cae7`](https://github.com/basicmachines-co/basic-memory/commit/cc2cae72c14b380f78ffeb67c2261e4dbee45faf))
+
+This change relocates the AI assistant guide from the static directory into the package resources
+  directory, ensuring it gets properly included in the distribution package and is accessible when
+  installed via pip/uv.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Preserve custom frontmatter fields when updating notes
+  ([`78f234b`](https://github.com/basicmachines-co/basic-memory/commit/78f234b1806b578a0a833e8ee4184015b7369a97))
+
+Fixes #36 by modifying entity_service.update_entity() to read existing frontmatter from files before
+  updating them. Custom metadata fields such as Status, Priority, and Version are now preserved when
+  notes are updated through the write_note MCP tool.
+
+Added test case that verifies this behavior by creating a note with custom frontmatter and then
+  updating it.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+- Preserve custom frontmatter fields when updating notes
+  ([`e716946`](https://github.com/basicmachines-co/basic-memory/commit/e716946b4408d017eca4be720956d5a210b4e6b1))
+
+Fixes #36 by modifying entity_service.update_entity() to read existing frontmatter from files before
+  updating them. Custom metadata fields such as Status, Priority, and Version are now preserved when
+  notes are updated through the write_note MCP tool.
+
+Added test case that verifies this behavior by creating a note with custom frontmatter and then
+  updating it.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Chores
+
+- Remove duplicate code in entity_service.py from bad merge
+  ([`681af5d`](https://github.com/basicmachines-co/basic-memory/commit/681af5d4505dadc40b4086630f739d76bac9201d))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Documentation
+
+- Add help docs to mcp cli tools
+  ([`731b502`](https://github.com/basicmachines-co/basic-memory/commit/731b502d36cec253d114403d73b48fab3c47786e))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Add mcp badge, update cli reference, llms-install.md
+  ([`b26afa9`](https://github.com/basicmachines-co/basic-memory/commit/b26afa927f98021246cd8b64858e57333595ea90))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Update CLAUDE.md ([#33](https://github.com/basicmachines-co/basic-memory/pull/33),
+  [`dfaf0fe`](https://github.com/basicmachines-co/basic-memory/commit/dfaf0fea9cf5b97d169d51a6276ec70162c21a7e))
+
+fix spelling in CLAUDE.md: enviroment -> environment Signed-off-by: Ikko Eltociear Ashimine
+  <eltociear@gmail.com>
+
+### Refactoring
+
+- Move project stats into projct subcommand
+  ([`2a881b1`](https://github.com/basicmachines-co/basic-memory/commit/2a881b1425c73947f037fbe7ac5539c015b62526))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+
+## v0.10.0 (2025-03-15)
+
+### Bug Fixes
+
+- Ai_resource_guide.md path
+  ([`da97353`](https://github.com/basicmachines-co/basic-memory/commit/da97353cfc3acc1ceb0eca22ac6af326f77dc199))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Ai_resource_guide.md path
+  ([`c4732a4`](https://github.com/basicmachines-co/basic-memory/commit/c4732a47b37dd2e404139fb283b65556c81ce7c9))
+
+- Ai_resource_guide.md path
+  ([`2e9d673`](https://github.com/basicmachines-co/basic-memory/commit/2e9d673e54ad6a63a971db64f01fc2f4e59c2e69))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Don't sync *.tmp files on watch ([#31](https://github.com/basicmachines-co/basic-memory/pull/31),
+  [`6b110b2`](https://github.com/basicmachines-co/basic-memory/commit/6b110b28dd8ba705ebfc0bcb41faf2cb993da2c3))
+
+Fixes #30
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Drop search_index table on db reindex
+  ([`31cca6f`](https://github.com/basicmachines-co/basic-memory/commit/31cca6f913849a0ab8fc944803533e3072e9ef88))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Improve utf-8 support for file reading/writing
+  ([#32](https://github.com/basicmachines-co/basic-memory/pull/32),
+  [`eb5e4ec`](https://github.com/basicmachines-co/basic-memory/commit/eb5e4ec6bd4d2fe757087be030d867f4ca1d38ba))
+
+fixes #29
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Chores
+
+- Remove logfire
+  ([`9bb8a02`](https://github.com/basicmachines-co/basic-memory/commit/9bb8a020c3425a02cb3a88f6f02adcd281bccee2))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Documentation
+
+- Add glama badge. Fix typos in README.md
+  ([#28](https://github.com/basicmachines-co/basic-memory/pull/28),
+  [`9af913d`](https://github.com/basicmachines-co/basic-memory/commit/9af913da4fba7bb4908caa3f15f2db2aa03777ec))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Update CLAUDE.md with GitHub integration capabilities
+  ([#25](https://github.com/basicmachines-co/basic-memory/pull/25),
+  [`fea2f40`](https://github.com/basicmachines-co/basic-memory/commit/fea2f40d1b54d0c533e6d7ee7ce1aa7b83ad9a47))
+
+This PR updates the CLAUDE.md file to document the GitHub integration capabilities that enable
+  Claude to participate directly in the development workflow.
+
+### Features
+
+- Add Smithery integration for easier installation
+  ([#24](https://github.com/basicmachines-co/basic-memory/pull/24),
+  [`eb1e7b6`](https://github.com/basicmachines-co/basic-memory/commit/eb1e7b6088b0b3dead9c104ee44174b2baebf417))
+
+This PR adds support for deploying Basic Memory on the Smithery platform.
+
+Signed-off-by: bm-claudeai <claude@basicmachines.co>
+
+
+## v0.9.0 (2025-03-07)
+
+### Chores
+
+- Pre beta prep ([#20](https://github.com/basicmachines-co/basic-memory/pull/20),
+  [`6a4bd54`](https://github.com/basicmachines-co/basic-memory/commit/6a4bd546466a45107007b5000276b6c9bb62ef27))
+
+fix: drop search_index table on db reindex
+
+fix: ai_resource_guide.md path
+
+chore: remove logfire
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+### Documentation
+
+- Update README.md and CLAUDE.md
+  ([`182ec78`](https://github.com/basicmachines-co/basic-memory/commit/182ec7835567fc246798d9b4ad121b2f85bc6ade))
+
+### Features
+
+- Add project_info tool ([#19](https://github.com/basicmachines-co/basic-memory/pull/19),
+  [`d2bd75a`](https://github.com/basicmachines-co/basic-memory/commit/d2bd75a949cc4323cb376ac2f6cb39f47c78c428))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+- Beta work ([#17](https://github.com/basicmachines-co/basic-memory/pull/17),
+  [`e6496df`](https://github.com/basicmachines-co/basic-memory/commit/e6496df595f3cafde6cc836384ee8c60886057a5))
+
+feat: Add multiple projects support
+
+feat: enhanced read_note for when initial result is not found
+
+fix: merge frontmatter when updating note
+
+fix: handle directory removed on sync watch
+
+- Implement boolean search ([#18](https://github.com/basicmachines-co/basic-memory/pull/18),
+  [`90d5754`](https://github.com/basicmachines-co/basic-memory/commit/90d5754180beaf4acd4be38f2438712555640b49))
+
+
+## v0.8.0 (2025-02-28)
+
+### Chores
+
+- Formatting
+  ([`93cc637`](https://github.com/basicmachines-co/basic-memory/commit/93cc6379ebb9ecc6a1652feeeecbf47fc992d478))
+
+- Refactor logging setup
+  ([`f4b703e`](https://github.com/basicmachines-co/basic-memory/commit/f4b703e57f0ddf686de6840ff346b8be2be499ad))
+
+### Features
+
+- Add enhanced prompts and resources
+  ([#15](https://github.com/basicmachines-co/basic-memory/pull/15),
+  [`093dab5`](https://github.com/basicmachines-co/basic-memory/commit/093dab5f03cf7b090a9f4003c55507859bf355b0))
+
+## Summary - Add comprehensive documentation to all MCP prompt modules - Enhance search prompt with
+  detailed contextual output formatting - Implement consistent logging and docstring patterns across
+  prompt utilities - Fix type checking in prompt modules
+
+## Prompts Added/Enhanced - `search.py`: New formatted output with relevance scores, excerpts, and
+  next steps - `recent_activity.py`: Enhanced with better metadata handling and documentation -
+  `continue_conversation.py`: Improved context management
+
+## Resources Added/Enhanced - `ai_assistant_guide`: Resource with description to give to LLM to
+  understand how to use the tools
+
+## Technical improvements - Added detailed docstrings to all prompt modules explaining their purpose
+  and usage - Enhanced the search prompt with rich contextual output that helps LLMs understand
+  results - Created a consistent pattern for formatting output across prompts - Improved error
+  handling in metadata extraction - Standardized import organization and naming conventions - Fixed
+  various type checking issues across the codebase
+
+This PR is part of our ongoing effort to improve the MCP's interaction quality with LLMs, making the
+  system more helpful and intuitive for AI assistants to navigate knowledge bases.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+---------
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+- Add new `canvas` tool to create json canvas files in obsidian.
+  ([#14](https://github.com/basicmachines-co/basic-memory/pull/14),
+  [`0d7b0b3`](https://github.com/basicmachines-co/basic-memory/commit/0d7b0b3d7ede7555450ddc9728951d4b1edbbb80))
+
+Add new `canvas` tool to create json canvas files in obsidian.
+
+---------
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+- Incremental sync on watch ([#13](https://github.com/basicmachines-co/basic-memory/pull/13),
+  [`37a01b8`](https://github.com/basicmachines-co/basic-memory/commit/37a01b806d0758029d34a862e76d44c7e5d538a5))
+
+- incremental sync on watch - sync non-markdown files in knowledge base - experimental
+  `read_resource` tool for reading non-markdown files in raw form (pdf, image)
+
+
+## v0.7.0 (2025-02-19)
+
+### Bug Fixes
+
+- Add logfire instrumentation to tools
+  ([`3e8e3e8`](https://github.com/basicmachines-co/basic-memory/commit/3e8e3e8961eae2e82839746e28963191b0aef0a0))
+
+- Add logfire spans to cli
+  ([`00d23a5`](https://github.com/basicmachines-co/basic-memory/commit/00d23a5ee15ddac4ea45e702dcd02ab9f0509276))
+
+- Add logfire spans to cli
+  ([`812136c`](https://github.com/basicmachines-co/basic-memory/commit/812136c8c22ad191d14ff32dcad91aae076d4120))
+
+- Search query pagination params
+  ([`bc9ca07`](https://github.com/basicmachines-co/basic-memory/commit/bc9ca0744ffe4296d7d597b4dd9b7c73c2d63f3f))
+
+### Chores
+
+- Fix tests
+  ([`57984aa`](https://github.com/basicmachines-co/basic-memory/commit/57984aa912625dcde7877afb96d874c164af2896))
+
+- Remove unused tests
+  ([`2c8ed17`](https://github.com/basicmachines-co/basic-memory/commit/2c8ed1737d6769fe1ef5c96f8a2bd75b9899316a))
+
+### Features
+
+- Add cli commands for mcp tools
+  ([`f5a7541`](https://github.com/basicmachines-co/basic-memory/commit/f5a7541da17e97403b7a702720a05710f68b223a))
+
+- Add pagination to build_context and recent_activity
+  ([`0123544`](https://github.com/basicmachines-co/basic-memory/commit/0123544556513af943d399d70b849b142b834b15))
+
+- Add pagination to read_notes
+  ([`02f8e86`](https://github.com/basicmachines-co/basic-memory/commit/02f8e866923d5793d2620076c709c920d99f2c4f))
+
+
+## v0.6.0 (2025-02-18)
+
+### Chores
+
+- Re-add sync status console on watch
+  ([`66b57e6`](https://github.com/basicmachines-co/basic-memory/commit/66b57e682f2e9c432bffd4af293b0d1db1d3469b))
+
+### Features
+
+- Configure logfire telemetry ([#12](https://github.com/basicmachines-co/basic-memory/pull/12),
+  [`6da1438`](https://github.com/basicmachines-co/basic-memory/commit/6da143898bd45cdab8db95b5f2b75810fbb741ba))
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+
+## v0.5.0 (2025-02-18)
+
+### Features
+
+- Return semantic info in markdown after write_note
+  ([#11](https://github.com/basicmachines-co/basic-memory/pull/11),
+  [`0689e7a`](https://github.com/basicmachines-co/basic-memory/commit/0689e7a730497827bf4e16156ae402ddc5949077))
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+
+## v0.4.3 (2025-02-18)
+
+### Bug Fixes
+
+- Re do enhanced read note format ([#10](https://github.com/basicmachines-co/basic-memory/pull/10),
+  [`39bd5ca`](https://github.com/basicmachines-co/basic-memory/commit/39bd5ca08fd057220b95a8b5d82c5e73a1f5722b))
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+
+## v0.4.2 (2025-02-17)
+
+
+## v0.4.1 (2025-02-17)
+
+### Bug Fixes
+
+- Fix alemic config
+  ([`71de8ac`](https://github.com/basicmachines-co/basic-memory/commit/71de8acfd0902fc60f27deb3638236a3875787ab))
+
+- More alembic fixes
+  ([`30cd74e`](https://github.com/basicmachines-co/basic-memory/commit/30cd74ec95c04eaa92b41b9815431f5fbdb46ef8))
+
+
+## v0.4.0 (2025-02-16)
+
+### Features
+
+- Import chatgpt conversation data ([#9](https://github.com/basicmachines-co/basic-memory/pull/9),
+  [`56f47d6`](https://github.com/basicmachines-co/basic-memory/commit/56f47d6812982437f207629e6ac9a82e0e56514e))
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+- Import claude.ai data ([#8](https://github.com/basicmachines-co/basic-memory/pull/8),
+  [`a15c346`](https://github.com/basicmachines-co/basic-memory/commit/a15c346d5ebd44344b76bad877bb4d1073fcbc3b))
+
+Import Claude.ai conversation and project data to basic-memory Markdown format.
+
+---------
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+
+## v0.3.0 (2025-02-15)
+
+### Bug Fixes
+
+- Refactor db schema migrate handling
+  ([`ca632be`](https://github.com/basicmachines-co/basic-memory/commit/ca632beb6fed5881f4d8ba5ce698bb5bc681e6aa))
+
+
+## v0.2.21 (2025-02-15)
+
+### Bug Fixes
+
+- Fix osx installer github action
+  ([`65ebe5d`](https://github.com/basicmachines-co/basic-memory/commit/65ebe5d19491e5ff047c459d799498ad5dd9cd1a))
+
+- Handle memory:// url format in read_note tool
+  ([`e080373`](https://github.com/basicmachines-co/basic-memory/commit/e0803734e69eeb6c6d7432eea323c7a264cb8347))
+
+- Remove create schema from init_db
+  ([`674dd1f`](https://github.com/basicmachines-co/basic-memory/commit/674dd1fd47be9e60ac17508476c62254991df288))
+
+### Features
+
+- Set version in var, output version at startup
+  ([`a91da13`](https://github.com/basicmachines-co/basic-memory/commit/a91da1396710e62587df1284da00137d156fc05e))
+
+
+## v0.2.20 (2025-02-14)
+
+### Bug Fixes
+
+- Fix installer artifact
+  ([`8de84c0`](https://github.com/basicmachines-co/basic-memory/commit/8de84c0221a1ee32780aa84dac4d3ea60895e05c))
+
+
+## v0.2.19 (2025-02-14)
+
+### Bug Fixes
+
+- Get app artifact for installer
+  ([`fe8c3d8`](https://github.com/basicmachines-co/basic-memory/commit/fe8c3d87b003166252290a87cbe958301cccf797))
+
+
+## v0.2.18 (2025-02-14)
+
+### Bug Fixes
+
+- Don't zip app on release
+  ([`8664c57`](https://github.com/basicmachines-co/basic-memory/commit/8664c57bb331d7f3f7e0239acb5386c7a3c6144e))
+
+
+## v0.2.17 (2025-02-14)
+
+### Bug Fixes
+
+- Fix app zip in installer release
+  ([`8fa197e`](https://github.com/basicmachines-co/basic-memory/commit/8fa197e2ec8a1b6caaf6dbb39c3c6626bba23e2e))
+
+
+## v0.2.16 (2025-02-14)
+
+### Bug Fixes
+
+- Debug inspect build on ci
+  ([`1d6054d`](https://github.com/basicmachines-co/basic-memory/commit/1d6054d30a477a4e6a5d6ac885632e50c01945d3))
+
+
+## v0.2.15 (2025-02-14)
+
+### Bug Fixes
+
+- Debug installer ci
+  ([`dab9573`](https://github.com/basicmachines-co/basic-memory/commit/dab957314aec9ed0e12abca2265552494ae733a2))
+
+
+## v0.2.14 (2025-02-14)
+
+
+## v0.2.13 (2025-02-14)
+
+### Bug Fixes
+
+- Refactor release.yml installer
+  ([`a152657`](https://github.com/basicmachines-co/basic-memory/commit/a15265783e47c22d8c7931396281d023b3694e27))
+
+- Try using symlinks in installer build
+  ([`8dd923d`](https://github.com/basicmachines-co/basic-memory/commit/8dd923d5bc0587276f92b5f1db022ad9c8687e45))
+
+
+## v0.2.12 (2025-02-14)
+
+### Bug Fixes
+
+- Fix cx_freeze options for installer
+  ([`854cf83`](https://github.com/basicmachines-co/basic-memory/commit/854cf8302e2f83578030db05e29b8bdc4348795a))
+
+
+## v0.2.11 (2025-02-14)
+
+### Bug Fixes
+
+- Ci installer app fix #37
+  ([`2e215fe`](https://github.com/basicmachines-co/basic-memory/commit/2e215fe83ca421b921186c7f1989dc2cb5cca278))
+
+
+## v0.2.10 (2025-02-14)
+
+### Bug Fixes
+
+- Fix build on github ci for app installer
+  ([`29a2594`](https://github.com/basicmachines-co/basic-memory/commit/29a259421a0ccb10cfa68e3707eaa506ad5e55c0))
+
+
+## v0.2.9 (2025-02-14)
+
+
 ## v0.2.8 (2025-02-14)
 
+### Bug Fixes
+
+- Fix installer on ci, maybe
+  ([`edbc04b`](https://github.com/basicmachines-co/basic-memory/commit/edbc04be601d234bb1f5eb3ba24d6ad55244b031))
+
 
 ## v0.2.7 (2025-02-14)
 

CLA.md

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+https://developercertificate.org/
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+have the right to submit it under the open source license
+indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+of my knowledge, is covered under an appropriate open source
+license and I have the right under that license to submit that
+work with modifications, whether created in whole or in part
+by me, under the same open source license (unless I am
+permitted to submit under a different license), as indicated
+in the file; or
+
+(c) The contribution was provided directly to me by some other
+person who certified (a), (b) or (c) and I have not modified
+it.
+
+(d) I understand and agree that this project and the contribution
+are public and that a record of the contribution (including all
+personal information I submit with it, including my sign-off) is
+maintained indefinitely and may be redistributed consistent with
+this project or the open source license(s) involved.

CLAUDE.md

@@ -0,0 +1,189 @@
+# CLAUDE.md - Basic Memory Project Guide
+
+## Project Overview
+
+Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
+bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
+be traversed using links between documents.
+
+## CODEBASE DEVELOPMENT
+
+### Project information
+
+See the [README.md](README.md) file for a project overview.
+
+### Build and Test Commands
+
+- Install: `make install` or `pip install -e ".[dev]"`
+- Run tests: `uv run pytest -p pytest_mock -v` or `make test`
+- Single test: `pytest tests/path/to/test_file.py::test_function_name`
+- Lint: `make lint` or `ruff check . --fix`
+- Type check: `make type-check` or `uv run pyright`
+- Format: `make format` or `uv run ruff format .`
+- Run all code checks: `make check` (runs lint, format, type-check, test)
+- Create db migration: `make migration m="Your migration message"`
+- Run development MCP Inspector: `make run-inspector`
+
+### Code Style Guidelines
+
+- Line length: 100 characters max
+- Python 3.12+ with full type annotations
+- Format with ruff (consistent styling)
+- Import order: standard lib, third-party, local imports
+- Naming: snake_case for functions/variables, PascalCase for classes
+- Prefer async patterns with SQLAlchemy 2.0
+- Use Pydantic v2 for data validation and schemas
+- CLI uses Typer for command structure
+- API uses FastAPI for endpoints
+- Follow the repository pattern for data access
+- Tools communicate to api routers via the httpx ASGI client (in process)
+- avoid using "private" functions in modules or classes (prepended with _)
+
+### Codebase Architecture
+
+- `/alembic` - Alembic db migrations
+- `/api` - FastAPI implementation of REST endpoints
+- `/cli` - Typer command-line interface
+- `/markdown` - Markdown parsing and processing
+- `/mcp` - Model Context Protocol server implementation
+- `/models` - SQLAlchemy ORM models
+- `/repository` - Data access layer
+- `/schemas` - Pydantic models for validation
+- `/services` - Business logic layer
+- `/sync` - File synchronization services
+
+### Development Notes
+
+- MCP tools are defined in src/basic_memory/mcp/tools/
+- MCP prompts are defined in src/basic_memory/mcp/prompts/
+- MCP tools should be atomic, composable operations
+- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools
+- MCP Prompts are used to invoke tools and format content with instructions for an LLM
+- Schema changes require Alembic migrations
+- SQLite is used for indexing and full text search, files are source of truth
+- Testing uses pytest with asyncio support (strict mode)
+- Test database uses in-memory SQLite
+- Avoid creating mocks in tests in most circumstances.
+- Each test runs in a standalone environment with in memory SQLite and tmp_file directory
+
+## BASIC MEMORY PRODUCT USAGE
+
+### Knowledge Structure
+
+- Entity: Any concept, document, or idea represented as a markdown file
+- Observation: A categorized fact about an entity (`- [category] content`)
+- Relation: A directional link between entities (`- relation_type [[Target]]`)
+- Frontmatter: YAML metadata at the top of markdown files
+- Knowledge representation follows precise markdown format:
+    - Observations with [category] prefixes
+    - Relations with WikiLinks [[Entity]]
+    - Frontmatter with metadata
+
+### Basic Memory Commands
+
+- Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
+- Import from Claude: `basic-memory import claude conversations`
+- Import from ChatGPT: `basic-memory import chatgpt`
+- Import from Memory JSON: `basic-memory import memory-json`
+- Check sync status: `basic-memory status`
+- Tool access: `basic-memory tools` (provides CLI access to MCP tools)
+    - Guide: `basic-memory tools basic-memory-guide`
+    - Continue: `basic-memory tools continue-conversation --topic="search"`
+
+### MCP Capabilities
+
+- Basic Memory exposes these MCP tools to LLMs:
+
+  **Content Management:**
+    - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph
+      awareness
+    - `read_file(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+
+  **Knowledge Graph Navigation:**
+    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation
+      continuity
+    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "
+      1d", "1 week")
+
+  **Search & Discovery:**
+    - `search_notes(query, page, page_size)` - Full-text search across all content with filtering options
+
+  **Visualization:**
+    - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
+
+- MCP Prompts for better AI interaction:
+    - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
+    - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
+    - `search_notes(query, after_date)` - Search with detailed, formatted results for better context understanding
+    - `recent_activity(timeframe)` - View recently changed items with formatted output
+    - `json_canvas_spec()` - Full JSON Canvas specification for Obsidian visualization
+
+## AI-Human Collaborative Development
+
+Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
+of using AI just for code generation, we've developed a true collaborative workflow:
+
+1. AI (LLM) writes initial implementation based on specifications and context
+2. Human reviews, runs tests, and commits code with any necessary adjustments
+3. Knowledge persists across conversations using Basic Memory's knowledge graph
+4. Development continues seamlessly across different AI sessions with consistent context
+5. Results improve through iterative collaboration and shared understanding
+
+This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
+could achieve independently.
+
+## GitHub Integration
+
+Basic Memory uses Claude directly into the development workflow through GitHub:
+
+### GitHub MCP Tools
+
+Using the GitHub Model Context Protocol server, Claude can:
+
+- **Repository Management**:
+    - View repository files and structure
+    - Read file contents
+    - Create new branches
+    - Create and update files
+
+- **Issue Management**:
+    - Create new issues
+    - Comment on existing issues
+    - Close and update issues
+    - Search across issues
+
+- **Pull Request Workflow**:
+    - Create pull requests
+    - Review code changes
+    - Add comments to PRs
+
+This integration enables Claude to participate as a full team member in the development process, not just as a code
+generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic
+Machines organization with direct contributor access to the codebase.
+
+### Collaborative Development Process
+
+With GitHub integration, the development workflow includes:
+
+1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
+2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
+3. **Branch management** - Claude can create feature branches for implementations
+4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
+
+With this integration, the AI assistant is a full-fledged team member rather than just a tool for generating code
+snippets.
+
+
+### Basic Memory Pro
+
+Basic Memory Pro is a desktop GUI application that wraps the basic-memory CLI/MCP tools:
+
+- Built with Tauri (Rust), React (TypeScript), and a Python FastAPI sidecar
+- Provides visual knowledge graph exploration and project management
+- Uses the same core codebase but adds a desktop-friendly interface
+- Project configuration is shared between CLI and Pro versions
+- Multiple project support with visual switching interface
+
+local repo: /Users/phernandez/dev/basicmachines/basic-memory-pro
+github: https://github.com/basicmachines-co/basic-memory-pro

CONTRIBUTING.md

@@ -1,17 +1,163 @@
 # Contributing to Basic Memory
 
-Thank you for considering contributing to Basic Memory! Your help is greatly appreciated to improve this project.
+Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the
+project and how to get started as a developer.
 
-## How to Contribute
+## Getting Started
 
-1. **Fork the Repo**: Fork the repository and clone your copy.
-1. **Create a Branch**: Create a new branch for your feature or fix.
-1. **Test Your Changes**: Ensure tests pass locally and include new tests when necessary to ensure 100& test coverage.
-1. **Format Your Code**: Run `make format` to ensure code is formatted appropriately.
-4. **Submit a PR**: Submit a pull request with a detailed description of your changes.
+### Development Environment
 
-Thank You!
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/basicmachines-co/basic-memory.git
+   cd basic-memory
+   ```
+
+2. **Install Dependencies**:
+   ```bash
+   # Using make (recommended)
+   make install
+   
+   # Or using uv
+   uv install -e ".[dev]"
+   
+   # Or using pip
+   pip install -e ".[dev]"
+   ```
+
+3. **Run the Tests**:
+   ```bash
+   # Run all tests
+   make test
+   # or
+   uv run pytest -p pytest_mock -v
+   
+   # Run a specific test
+   pytest tests/path/to/test_file.py::test_function_name
+   ```
+
+### Development Workflow
+
+1. **Fork the Repo**: Fork the repository on GitHub and clone your copy.
+2. **Create a Branch**: Create a new branch for your feature or fix.
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-you-are-fixing
+   ```
+3. **Make Your Changes**: Implement your changes with appropriate test coverage.
+4. **Check Code Quality**:
+   ```bash
+   # Run all checks at once
+   make check
+   
+   # Or run individual checks
+   make lint      # Run linting
+   make format    # Format code
+   make type-check  # Type checking
+   ```
+5. **Test Your Changes**: Ensure all tests pass locally and maintain 100% test coverage.
+   ```bash
+   make test
+   ```
+6. **Submit a PR**: Submit a pull request with a detailed description of your changes.
+
+## LLM-Assisted Development
+
+This project is designed for collaborative development between humans and LLMs (Large Language Models):
+
+1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs.
+   This file contains:
+    - Key project information and architectural overview
+    - Development commands and workflows
+    - Code style guidelines
+    - Documentation standards
+
+2. **AI-Human Collaborative Workflow**:
+    - We encourage using LLMs like Claude for code generation, reviews, and documentation
+    - When possible, save context in markdown files that can be referenced later
+    - This enables seamless knowledge transfer between different development sessions
+    - Claude can help with implementation details while you focus on architecture and design
+
+3. **Adding to CLAUDE.md**:
+    - If you discover useful project information or common commands, consider adding them to CLAUDE.md
+    - This helps all contributors (human and AI) maintain consistent knowledge of the project
+
+## Pull Request Process
+
+1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description.
+2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that
+   you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you
+   create a PR.
+3. **PR Description**: Include:
+    - What the PR changes
+    - Why the change is needed
+    - How you tested the changes
+    - Any related issues (use "Fixes #123" to automatically close issues)
+4. **Code Review**: Wait for code review and address any feedback.
+5. **CI Checks**: Ensure all CI checks pass.
+6. **Merge**: Once approved, a maintainer will merge your PR.
+
+## Developer Certificate of Origin
+
+By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you
+certify that:
+
+- You have the right to submit your contributions
+- You're not knowingly submitting code with patent or copyright issues
+- Your contributions are provided under the project's license (AGPL-3.0)
+
+This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be
+properly incorporated into the project and potentially used in commercial applications.
+
+### Signing Your Commits
+
+Sign your commit:
+
+**Using the `-s` or `--signoff` flag**:
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO.
+
+The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your
+agreement to the DCO.
+
+## Code Style Guidelines
+
+- **Python Version**: Python 3.12+ with full type annotations
+- **Line Length**: 100 characters maximum
+- **Formatting**: Use ruff for consistent styling
+- **Import Order**: Standard lib, third-party, local imports
+- **Naming**: Use snake_case for functions/variables, PascalCase for classes
+- **Documentation**: Add docstrings to public functions, classes, and methods
+- **Type Annotations**: Use type hints for all functions and methods
+
+## Testing Guidelines
+
+- **Coverage Target**: We aim for 100% test coverage for all code
+- **Test Framework**: Use pytest for unit and integration tests
+- **Mocking**: Use pytest-mock for mocking dependencies only when necessary
+- **Edge Cases**: Test both normal operation and edge cases
+- **Database Testing**: Use in-memory SQLite for testing database operations
+- **Fixtures**: Use async pytest fixtures for setup and teardown
+
+## Creating Issues
+
+If you're planning to work on something, please create an issue first to discuss the approach. Include:
+
+- A clear title and description
+- Steps to reproduce if reporting a bug
+- Expected behavior vs. actual behavior
+- Any relevant logs or screenshots
+- Your proposed solution, if you have one
 
 ## Code of Conduct
 
 All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Thank You!
+
+Your contributions help make Basic Memory better. We appreciate your time and effort!

Dockerfile

@@ -0,0 +1,16 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy the project files
+COPY . .
+
+# Install pip and build dependencies
+RUN pip install --upgrade pip \
+&& pip install . --no-cache-dir --ignore-installed
+
+# Expose port if necessary (e.g., uv might use a port, but MCP over stdio so not needed here)
+
+# Use the basic-memory entrypoint to run the MCP server
+CMD ["basic-memory", "mcp"]

Makefile

@@ -1,10 +1,23 @@
-.PHONY: install test lint clean format type-check installer-mac installer-win
+.PHONY: install test test-module lint clean format type-check installer-mac installer-win check
 
 install:
 	pip install -e ".[dev]"
 
 test:
-	pytest -p pytest_mock -v
+	uv run pytest -p pytest_mock -v
+
+# Run tests for a specific module
+# Usage: make test-module m=path/to/module.py [cov=module_path]
+test-module:
+	@if [ -z "$(m)" ]; then \
+		echo "Usage: make test-module m=path/to/module.py [cov=module_path]"; \
+		exit 1; \
+	fi; \
+	if [ -z "$(cov)" ]; then \
+		uv run pytest $(m) -v; \
+	else \
+		uv run pytest $(m) -v --cov=$(cov); \
+	fi
 
 lint:
 	ruff check . --fix
@@ -27,11 +40,12 @@ format:
 	uv run ruff format .
 
 # run inspector tool
-run-dev:
+run-inspector:
 	uv run mcp dev src/basic_memory/mcp/main.py
 
 # Build app installer
 installer-mac:
+	cd installer && chmod +x make_icons.sh && ./make_icons.sh
 	cd installer && uv run python setup.py bdist_mac
 
 installer-win:
@@ -39,4 +53,15 @@ installer-win:
 
 
 update-deps:
-	uv lock f--upgrade
+	uv lock --upgrade
+
+check: lint  format type-check test
+
+
+# Target for generating Alembic migrations with a message from command line
+migration:
+	@if [ -z "$(m)" ]; then \
+		echo "Usage: make migration m=\"Your migration message\""; \
+		exit 1; \
+	fi; \
+	cd src/basic_memory/alembic && alembic revision --autogenerate -m "$(m)"

README.md

@@ -1,258 +1,396 @@
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![](https://badge.mcpx.dev?type=server 'MCP Server')
+![](https://badge.mcpx.dev?type=dev 'MCP Dev')
+[![smithery badge](https://smithery.ai/badge/@basicmachines-co/basic-memory)](https://smithery.ai/server/@basicmachines-co/basic-memory)
+
 # 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
+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?
+- Website: https://basicmachines.co
+- Documentation: https://memory.basicmachines.co
 
-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:
+## Pick up your conversation right where you left off
 
-- 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)
+- AI assistants can load context from local files in a new conversation
+- Notes are saved locally as Markdown files in real time
+- No project knowledge or special prompting required
 
-Basic Memory takes a different approach by letting both humans and LLMs read and write knowledge naturally using
-standard markdown files. This means:
+https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 
-- 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:
+## Quick Start
 
 ```bash
+# Install with uv (recommended)
+uv tool install basic-memory
+
+# Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
+# Add this to your config:
 {
   "mcpServers": {
     "basic-memory": {
       "command": "uvx",
       "args": [
-        "basic-memory"
+        "basic-memory",
+        "mcp"
       ]
     }
+  }
+}
+# Now in Claude Desktop, you can:
+# - Write notes with "Create a note about coffee brewing methods"
+# - Read notes with "What do I know about pour over coffee?"
+# - Search with "Find information about Ethiopian beans"
+
+```
+
+You can view shared context via files in `~/basic-memory` (default directory location).
+
+### Alternative Installation via Smithery
+
+You can use [Smithery](https://smithery.ai/server/@basicmachines-co/basic-memory) to automatically configure Basic
+Memory for Claude Desktop:
+
+```bash
+npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
+```
+
+This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. The
+Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
+
+### Glama.ai
+
+<a href="https://glama.ai/mcp/servers/o90kttu9ym">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/o90kttu9ym/badge" alt="basic-memory MCP server" />
+</a>
+
+## Why Basic Memory?
+
+Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation
+starts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:
+
+- Chat histories capture conversations but aren't structured knowledge
+- RAG systems can query documents but don't let LLMs write back
+- Vector databases require complex setups and often live in the cloud
+- Knowledge graphs typically need specialized tools to maintain
+
+Basic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can
+read
+and write to. The key advantages:
+
+- **Local-first:** All knowledge stays in files you control
+- **Bi-directional:** Both you and the LLM read and write to the same files
+- **Structured yet simple:** Uses familiar Markdown with semantic patterns
+- **Traversable knowledge graph:** LLMs can follow links between topics
+- **Standard formats:** Works with existing editors like Obsidian
+- **Lightweight infrastructure:** Just local files indexed in a local SQLite database
+
+With Basic Memory, you can:
+
+- Have conversations that build on previous knowledge
+- Create structured notes during natural conversations
+- Have conversations with LLMs that remember what you've discussed before
+- Navigate your knowledge graph semantically
+- Keep everything local and under your control
+- Use familiar tools like Obsidian to view and edit notes
+- Build a personal knowledge base that grows over time
+
+## How It Works in Practice
+
+Let's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:
+
+1. Start by chatting normally:
+
+```
+I've been experimenting with different coffee brewing methods. Key things I've learned:
+
+- Pour over gives more clarity in flavor than French press
+- Water temperature is critical - around 205°F seems best
+- Freshly ground beans make a huge difference
+```
+
+... continue conversation.
+
+2. Ask the LLM to help structure this knowledge:
+
+```
+"Let's write a note about coffee brewing methods."
+```
+
+LLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):
+
+```markdown
+---
+title: Coffee Brewing Methods
+permalink: coffee-brewing-methods
+tags:
+- coffee
+- brewing
+---
+
+# Coffee Brewing Methods
+
+## Observations
+
+- [method] Pour over provides more clarity and highlights subtle flavors
+- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
+- [principle] Freshly ground beans preserve aromatics and flavor
+
+## Relations
+
+- relates_to [[Coffee Bean Origins]]
+- requires [[Proper Grinding Technique]]
+- affects [[Flavor Extraction]]
+```
+
+The note embeds semantic content and links to other topics via simple Markdown formatting.
+
+3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
+
+- Realtime sync is enabled by default with the v0.12.0 version
+
+4. In a chat with the LLM, you can reference a topic:
+
+```
+Look at `coffee-brewing-methods` for context about pour over coffee
+```
+
+The LLM can now build rich context from the knowledge graph. For example:
+
+```
+Following relation 'relates_to [[Coffee Bean Origins]]':
+- Found information about Ethiopian Yirgacheffe
+- Notes on Colombian beans' nutty profile
+- Altitude effects on bean characteristics
+
+Following relation 'requires [[Proper Grinding Technique]]':
+- Burr vs. blade grinder comparisons
+- Grind size recommendations for different methods
+- Impact of consistent particle size on extraction
+```
+
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base.
+
+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.
+
+## Technical Implementation
+
+Under the hood, Basic Memory:
+
+1. Stores everything in Markdown files
+2. Uses a SQLite database for searching and indexing
+3. Extracts semantic meaning from simple Markdown patterns
+    - Files become `Entity` objects
+    - Each `Entity` can have `Observations`, or facts associated with it
+    - `Relations` connect entities together to form the knowledge graph
+4. Maintains the local knowledge graph derived from the files
+5. Provides bidirectional synchronization between files and the knowledge graph
+6. Implements the Model Context Protocol (MCP) for AI integration
+7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph
+8. Uses memory:// URLs to reference entities across tools and conversations
+
+The file format is just Markdown with some simple markup:
+
+Each Markdown file has:
+
+### Frontmatter
+
+```markdown
+title: <Entity title>
+type: <The type of Entity> (e.g. note)
+permalink: <a uri slug>
+
+- <optional metadata> (such as tags) 
+```
+
+### Observations
+
+Observations are facts about a topic.
+They can be added by creating a Markdown list with a special format that can reference a `category`, `tags` using a
+"#" character, and an optional `context`.
+
+Observation Markdown format:
+
+```markdown
+- [category] content #tag (optional context)
+```
+
+Examples of observations:
+
+```markdown
+- [method] Pour over extracts more floral notes than French press
+- [tip] Grind size should be medium-fine for pour over #brewing
+- [preference] Ethiopian beans have bright, fruity flavors (especially from Yirgacheffe)
+- [fact] Lighter roasts generally contain more caffeine than dark roasts
+- [experiment] Tried 1:15 coffee-to-water ratio with good results
+- [resource] James Hoffman's V60 technique on YouTube is excellent
+- [question] Does water temperature affect extraction of different compounds differently?
+- [note] My favorite local shop uses a 30-second bloom time
+```
+
+### Relations
+
+Relations are links to other topics. They define how entities connect in the knowledge graph.
+
+Markdown format:
+
+```markdown
+- relation_type [[WikiLink]] (optional context)
+```
+
+Examples of relations:
+
+```markdown
+- pairs_well_with [[Chocolate Desserts]]
+- grown_in [[Ethiopia]]
+- contrasts_with [[Tea Brewing Methods]]
+- requires [[Burr Grinder]]
+- improves_with [[Fresh Beans]]
+- relates_to [[Morning Routine]]
+- inspired_by [[Japanese Coffee Culture]]
+- documented_in [[Coffee Journal]]
+```
+
+## Using with VS Code
+For one-click installation, click one of the install buttons below...
+
+[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D&quality=insiders)
+
+You can use Basic Memory with VS Code to easily retrieve and store information while coding. Click the installation buttons above for one-click setup, or follow the manual installation instructions below.
+
+### Manual Installation
+
+Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "basic-memory": {
+        "command": "uvx",
+        "args": ["basic-memory", "mcp"]
+      }
+    }
+  }
 }
 ```
 
-2. Add to Claude Desktop:
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
 
-```
-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
+```json
+{
+  "servers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"]
+    }
+  }
+}
 ```
 
-3. Install via uv
+## Using with Claude Desktop
 
-```bash
-uv add  basic-memory
+Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):
 
-# sync local knowledge updates
-basic-memory sync
+1. Configure Claude Desktop to use Basic Memory:
 
-# run realtime sync process
-basic-memory sync --watch
+Edit your MCP configuration file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json`
+for OS X):
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "mcp"
+      ]
+    }
+  }
+}
 ```
 
-## Design Philosophy
+If you want to use a specific project (see [Multiple Projects](docs/User%20Guide.md#multiple-projects)), update your
+Claude Desktop
+config:
 
-Basic Memory is built on some key ideas:
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "--project",
+        "your-project-name",
+        "mcp"
+      ]
+    }
+  }
+}
+```
 
-- 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
+2. Sync your knowledge:
+
+Basic Memory will sync the files in your project in real time if you make manual edits.
+
+3. In Claude Desktop, the LLM can now use these tools:
+
+```
+write_note(title, content, folder, tags) - Create or update notes
+read_note(identifier, page, page_size) - Read notes by title or permalink
+build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
+search_notes(query, page, page_size) - Search across your knowledge base
+recent_activity(type, depth, timeframe) - Find recently updated information
+canvas(nodes, edges, title, folder) - Generate knowledge visualizations
+```
+
+5. Example prompts to try:
+
+```
+"Create a note about our project architecture decisions"
+"Find information about JWT authentication in my notes"
+"Create a canvas visualization of my project components"
+"Read my notes on the authentication system"
+"What have I been working on in the past week?"
+```
+
+## Futher info
+
+See the [Documentation](https://memory.basicmachines.co/) for more info, including:
+
+- [Complete User Guide](https://memory.basicmachines.co/docs/user-guide)
+- [CLI tools](https://memory.basicmachines.co/docs/cli-reference)
+- [Managing multiple Projects](https://memory.basicmachines.co/docs/cli-reference#project)
+- [Importing data from OpenAI/Claude Projects](https://memory.basicmachines.co/docs/cli-reference#import)
 
 ## License
 
-AGPL-3.0
+AGPL-3.0
+
+Contributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally
+and submitting PRs.
+
+## Star History
+
+<a href="https://www.star-history.com/#basicmachines-co/basic-memory&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+ </picture>
+</a>
+
+Built with ♥️ by Basic Machines

SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+If you find a vulnerability, please contact hello@basicmachines.co

claude-output/claude_issue_fix_log_75.txt

@@ -0,0 +1,13 @@
+Starting issue-fix mode at Sat Apr  5 18:02:54 UTC 2025
+Fetching issue #75 details
+Using repository: basicmachines-co/basic-memory
+Checking if phernandez is a member of organization basicmachines-co
+User phernandez is a member of organization basicmachines-co. Proceeding with Claude fix.
+Creating a new branch: fix-issue-75-20250405180254
+From https://github.com/basicmachines-co/basic-memory
+ * branch            main       -> FETCH_HEAD
+Switched to a new branch 'fix-issue-75-20250405180254'
+branch 'fix-issue-75-20250405180254' set up to track 'origin/main'.
+Prompt saved to ./claude-output/claude_prompt_75.txt for debugging
+Running Claude to fix the issue...
+Committing changes...

claude-output/claude_output_75.txt

@@ -0,0 +1,35 @@
+Let's summarize the changes we've made to fix issue #75:
+
+1. We updated the `search_notes` tool in `/src/basic_memory/mcp/tools/search.py` to accept primitive types as parameters instead of a complex Pydantic `SearchQuery` object. This makes it easier for LLMs like Cursor to make proper tool calls.
+
+2. We converted the internal implementation to create a SearchQuery object from the primitive parameters, maintaining backward compatibility with the existing API.
+
+3. We updated tests in `/tests/mcp/test_tool_search.py` to use the new function signature with primitive parameters.
+
+4. We updated code in `/src/basic_memory/mcp/tools/read_note.py` to use the new function signature when making calls to `search_notes`.
+
+5. We updated code in `/src/basic_memory/mcp/prompts/search.py` to use the new function signature when making calls to `search_notes`.
+
+These changes should make it easier for Cursor and other LLMs to use the search_notes tool by eliminating the complex Pydantic object parameter in favor of simple primitive parameters.
+
+---SUMMARY---
+Fixed issue #75 where Cursor was having errors calling the search_notes tool. The problem was that the search_notes tool was expecting a complex Pydantic object (SearchQuery) as input, which was confusing Cursor. 
+
+Changes:
+1. Modified the search_notes tool to accept primitive types (strings, lists, etc.) as parameters instead of a complex Pydantic object
+2. Updated the implementation to create a SearchQuery object internally from these primitive parameters
+3. Updated all call sites in the codebase that were using the old function signature
+4. Updated tests to use the new function signature
+
+The fix makes it easier for LLMs like Cursor to make proper calls to the search_notes tool, which will resolve the reported error messages:
+- "Parameter 'query' must be of type undefined, got object"
+- "Parameter 'query' must be of type undefined, got string"
+- "Invalid type for parameter 'query' in tool search_notes"
+
+Files modified:
+- src/basic_memory/mcp/tools/search.py
+- src/basic_memory/mcp/tools/read_note.py
+- src/basic_memory/mcp/prompts/search.py
+- tests/mcp/test_tool_search.py
+- tests/mcp/test_tool_read_note.py
+---END SUMMARY---

claude-output/claude_prompt_75.txt

@@ -0,0 +1,49 @@
+You are Claude, an AI assistant tasked with fixing issues in a GitHub repository.
+
+Issue #75: [BUG] Cursor has errors calling search tool
+
+Issue Description:
+## Bug Description
+
+
+
+> Cursor cannot figure out how to structure the parameters for that tool call.  No matter what Cursor seems to try it gets the errors.
+> 
+> ```Looking at the error messages more carefully:
+> - When I pass an object: "Parameter 'query' must be of type undefined, got object"
+> - When I pass a string: "Parameter 'query' must be of type undefined, got string"
+> 
+> 
+> 
+>  and then it reports:  "Invalid type for parameter 'query' in tool search_notes"
+> Any chance you can give me some guidance with this?
+> 
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+
+try using search tool in Cursor. 
+
+## Possible Solution
+
+The tool args should probably be plain text and not json to make it easier to call. 
+Additional Instructions from User Comment:
+ let make a PR to implement option #1.  
+Your task is to:
+1. Analyze the issue carefully to understand the problem
+2. Look through the repository to identify the relevant files that need to be modified
+3. Make precise changes to fix the issue
+4. Use the Edit tool to modify files directly when needed
+5. Be minimal in your changes - only modify what's necessary to fix the issue
+
+After making changes, provide a summary of what you did in this format:
+
+---SUMMARY---
+[Your detailed summary of changes, including which files were modified and how]
+---END SUMMARY---
+
+Remember:
+- Be specific in your changes
+- Only modify files that are necessary to fix the issue
+- Follow existing code style and conventions
+- Make the minimal changes needed to resolve the issue

docs/AI Assistant Guide.md

@@ -0,0 +1,398 @@
+---
+title: AI Assistant Guide
+type: note
+permalink: docs/ai-assistant-guide
+---
+> Note: This is an optional document that can be copy/pasted into the project knowledge for an LLM to provide a full description of how it can work with Basic Memory. It is provided as a helpful resource. The tools contain extensive usage description prompts with enable the LLM to understand them. 
+
+You can [download](https://github.com/basicmachines-co/basic-memory/blob/main/docs/AI%20Assistant%20Guide.md) the contents of this file from GitHub
+# AI Assistant Guide for Basic Memory
+
+This guide helps you, the AI assistant, use Basic Memory tools effectively when working with users. It covers reading, writing, and navigating knowledge through the Model Context Protocol (MCP).
+
+## Overview
+
+Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
+
+- **Local-First**: All data is stored in plain text files on the user's computer
+- **Real-Time**: Users see content updates immediately
+- **Bi-Directional**: Both you and users can read and edit notes
+- **Semantic**: Simple patterns create a structured knowledge graph
+- **Persistent**: Knowledge persists across sessions and conversations
+
+## The Importance of the Knowledge Graph
+
+Basic Memory's value comes from connections between notes, not just the notes themselves. When writing notes, your primary goal should be creating a rich, interconnected knowledge graph.
+
+When creating content, focus on:
+
+1. **Increasing Semantic Density**: Add multiple observations and relations to each note
+2. **Using Accurate References**: Aim to reference existing entities by their exact titles
+3. **Creating Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these when they're created later
+4. **Creating Bidirectional Links**: When appropriate, connect entities from both directions
+5. **Using Meaningful Categories**: Add semantic context with appropriate observation categories
+6. **Choosing Precise Relations**: Use specific relation types that convey meaning
+
+Remember that a knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help build these connections.
+
+## Core Tools Reference
+
+```python
+# Writing knowledge - THE MOST IMPORTANT TOOL!
+response = await write_note(
+    title="Search Design",              # Required: Note title
+    content="# Search Design\n...",     # Required: Note content
+    folder="specs",                     # Optional: Folder to save in
+    tags=["search", "design"],          # Optional: Tags for categorization
+    verbose=True                        # Optional: Get parsing details
+)
+
+# Reading knowledge
+content = await read_note("Search Design")             # By title
+content = await read_note("specs/search-design")       # By path
+content = await read_note("memory://specs/search")     # By memory URL
+
+# Searching for knowledge
+results = await search_notes(
+    query="authentication system",      # Text to search for
+    page=1,                             # Optional: Pagination
+    page_size=10                        # Optional: Results per page
+)
+
+# Building context from the knowledge graph
+context = await build_context(
+    url="memory://specs/search",        # Starting point
+    depth=2,                            # Optional: How many hops to follow
+    timeframe="1 month"                 # Optional: Recent timeframe
+)
+
+# Checking recent changes
+activity = await recent_activity(
+    type="all",                         # Optional: Entity types to include
+    depth=1,                            # Optional: Related items to include
+    timeframe="1 week"                  # Optional: Time window
+)
+
+# Creating a knowledge visualization
+canvas_result = await canvas(
+    nodes=[{"id": "note1", "label": "Search Design"}],  # Nodes to display
+    edges=[{"from": "note1", "to": "note2"}],           # Connections
+    title="Project Overview",                           # Canvas title
+    folder="diagrams"                                   # Storage location
+)
+```
+
+## memory:// URLs Explained
+
+Basic Memory uses a special URL format to reference entities in the knowledge graph:
+
+- `memory://title` - Reference by title
+- `memory://folder/title` - Reference by folder and title 
+- `memory://permalink` - Reference by permalink
+- `memory://path/relation_type/*` - Follow all relations of a specific type
+- `memory://path/*/target` - Find all entities with relations to target
+
+## Semantic Markdown Format
+
+Knowledge is encoded in standard markdown using simple patterns:
+
+**Observations** - Facts about an entity:
+```markdown
+- [category] This is an observation #tag1 #tag2 (optional context)
+```
+
+**Relations** - Links between entities:
+```markdown
+- relation_type [[Target Entity]] (optional context)
+```
+
+**Common Categories & Relation Types:**
+- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
+- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`, `originated_from`
+
+## When to Record Context
+
+**Always consider recording context when**:
+
+1. Users make decisions or reach conclusions
+2. Important information emerges during conversation
+3. Multiple related topics are discussed
+4. The conversation contains information that might be useful later
+5. Plans, tasks, or action items are mentioned
+
+**Protocol for recording context**:
+
+1. Identify valuable information in the conversation
+2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
+3. If they agree, use `write_note` to capture the information
+4. If they decline, continue without recording
+5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
+
+## Understanding User Interactions
+
+Users will interact with Basic Memory in patterns like:
+
+1. **Creating knowledge**:
+   ```
+   Human: "Let's write up what we discussed about search."
+   
+   You: I'll create a note capturing our discussion about the search functionality.
+   [Use write_note() to record the conversation details]
+   ```
+
+2. **Referencing existing knowledge**:
+   ```
+   Human: "Take a look at memory://specs/search"
+   
+   You: I'll examine that information.
+   [Use build_context() to gather related information]
+   [Then read_note() to access specific content]
+   ```
+
+3. **Finding information**:
+   ```
+   Human: "What were our decisions about auth?"
+   
+   You: Let me find that information for you.
+   [Use search_notes() to find relevant notes]
+   [Then build_context() to understand connections]
+   ```
+
+## Key Things to Remember
+
+1. **Files are Truth**
+   - All knowledge lives in local files on the user's computer
+   - Users can edit files outside your interaction
+   - Changes need to be synced by the user (usually automatic)
+   - Always verify information is current with `recent_activity()`
+
+2. **Building Context Effectively**
+   - Start with specific entities
+   - Follow meaningful relations
+   - Check recent changes
+   - Build context incrementally
+   - Combine related information
+
+3. **Writing Knowledge Wisely**
+   - Using the same title+folder will overwrite existing notes
+   - Structure content with clear headings and sections
+   - Use semantic markup for observations and relations
+   - Keep files organized in logical folders
+
+## Common Knowledge Patterns
+
+### Capturing Decisions
+
+```markdown
+# Coffee Brewing Methods
+
+## Context
+I've experimented with various brewing methods including French press, pour over, and espresso.
+
+## Decision
+Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control over the extraction.
+
+## Observations
+- [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
+- [preference] Water temperature between 195-205°F works best #temperature
+- [equipment] Gooseneck kettle provides better control of water flow #tools
+
+## Relations
+- pairs_with [[Light Roast Beans]]
+- contrasts_with [[French Press Method]]
+- requires [[Proper Grinding Technique]]
+```
+
+### Recording Project Structure
+
+```markdown
+# Garden Planning
+
+## Overview
+This document outlines the garden layout and planting strategy for this season.
+
+## Observations
+- [structure] Raised beds in south corner for sun exposure #layout
+- [structure] Drip irrigation system installed for efficiency #watering
+- [pattern] Companion planting used to deter pests naturally #technique
+
+## Relations
+- contains [[Vegetable Section]]
+- contains [[Herb Garden]]
+- implements [[Organic Gardening Principles]]
+```
+
+### Technical Discussions
+
+```markdown
+# Recipe Improvement Discussion
+
+## Key Points
+Discussed strategies for improving the chocolate chip cookie recipe.
+
+## Observations
+- [issue] Cookies spread too thin when baked at 350°F #texture
+- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
+- [decision] Will use brown butter instead of regular butter #flavor
+
+## Relations
+- improves [[Basic Cookie Recipe]]
+- inspired_by [[Bakery-Style Cookies]]
+- pairs_with [[Homemade Ice Cream]]
+```
+
+### Creating Effective Relations
+
+When creating relations, you can:
+1. Reference existing entities by their exact title
+2. Create forward references to entities that don't exist yet
+
+```python
+# Example workflow for creating notes with effective relations
+async def create_note_with_effective_relations():
+    # Search for existing entities to reference
+    search_results = await search_notes("travel")
+    existing_entities = [result.title for result in search_results.primary_results]
+    
+    # Check if specific entities exist
+    packing_tips_exists = "Packing Tips" in existing_entities
+    japan_travel_exists = "Japan Travel Guide" in existing_entities
+    
+    # Prepare relations section - include both existing and forward references
+    relations_section = "## Relations\n"
+    
+    # Existing reference - exact match to known entity
+    if packing_tips_exists:
+        relations_section += "- references [[Packing Tips]]\n"
+    else:
+        # Forward reference - will be linked when that entity is created later
+        relations_section += "- references [[Packing Tips]]\n"
+    
+    # Another possible reference
+    if japan_travel_exists:
+        relations_section += "- part_of [[Japan Travel Guide]]\n"
+    
+    # You can also check recently modified notes to reference them
+    recent = await recent_activity(timeframe="1 week")
+    recent_titles = [item.title for item in recent.primary_results]
+    
+    if "Transportation Options" in recent_titles:
+        relations_section += "- relates_to [[Transportation Options]]\n"
+    
+    # Always include meaningful forward references, even if they don't exist yet
+    relations_section += "- located_in [[Tokyo]]\n"
+    relations_section += "- visited_during [[Spring 2023 Trip]]\n"
+    
+    # Now create the note with both verified and forward relations
+    content = f"""# Tokyo Neighborhood Guide
+    
+## Overview
+Details about different Tokyo neighborhoods and their unique characteristics.
+
+## Observations
+- [area] Shibuya is a busy shopping district #shopping
+- [transportation] Yamanote Line connects major neighborhoods #transit
+- [recommendation] Visit Shimokitazawa for vintage shopping #unique
+- [tip] Get a Suica card for easy train travel #convenience
+
+{relations_section}
+    """
+    
+    result = await write_note(
+        title="Tokyo Neighborhood Guide",
+        content=content,
+        verbose=True
+    )
+    
+    # You can check which relations were resolved and which are forward references
+    if result and 'relations' in result:
+        resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
+        forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
+        
+        print(f"Resolved relations: {resolved}")
+        print(f"Forward references that will be resolved later: {forward_refs}")
+```
+
+## Error Handling
+
+Common issues to watch for:
+
+1. **Missing Content**
+   ```python
+   try:
+       content = await read_note("Document")
+   except:
+       # Try search instead
+       results = await search_notes("Document")
+       if results and results.primary_results:
+           # Found something similar
+           content = await read_note(results.primary_results[0].permalink)
+   ```
+
+2. **Forward References (Unresolved Relations)**
+   ```python
+   response = await write_note(..., verbose=True)
+   # Check for forward references (unresolved relations)
+   forward_refs = []
+   for relation in response.get('relations', []):
+       if not relation.get('target_id'):
+           forward_refs.append(relation.get('to_name'))
+   
+   if forward_refs:
+       # This is a feature, not an error! Inform the user about forward references
+       print(f"Note created with forward references to: {forward_refs}")
+       print("These will be automatically linked when those notes are created.")
+       
+       # Optionally suggest creating those entities now
+       print("Would you like me to create any of these notes now to complete the connections?")
+   ```
+
+3. **Sync Issues**
+   ```python
+   # If information seems outdated
+   activity = await recent_activity(timeframe="1 hour")
+   if not activity or not activity.primary_results:
+       print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
+   ```
+
+## Best Practices
+
+1. **Proactively Record Context**
+   - Offer to capture important discussions
+   - Record decisions, rationales, and conclusions
+   - Link to related topics
+   - Ask for permission first: "Would you like me to save our discussion about [topic]?"
+   - Confirm when complete: "I've saved our discussion to Basic Memory"
+
+2. **Create a Rich Semantic Graph**
+   - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
+   - **Create deliberate relations**: Connect each note to at least 2-3 related entities
+   - **Use existing entities**: Before creating a new relation, search for existing entities
+   - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
+   - **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
+   - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead of "relates_to")
+   - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
+
+3. **Structure Content Thoughtfully**
+   - Use clear, descriptive titles
+   - Organize with logical sections (Context, Decision, Implementation, etc.)
+   - Include relevant context and background
+   - Add semantic observations with appropriate categories
+   - Use a consistent format for similar types of notes
+   - Balance detail with conciseness
+
+4. **Navigate Knowledge Effectively**
+   - Start with specific searches
+   - Follow relation paths
+   - Combine information from multiple sources
+   - Verify information is current
+   - Build a complete picture before responding
+
+5. **Help Users Maintain Their Knowledge**
+   - Suggest organizing related topics
+   - Identify potential duplicates
+   - Recommend adding relations between topics
+   - Offer to create summaries of scattered information
+   - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
+
+Built with ♥️ by Basic Machines

docs/CLI Reference.md

@@ -0,0 +1,332 @@
+---
+title: CLI Reference
+type: note
+permalink: docs/cli-reference
+---
+
+# CLI Reference
+
+Basic Memory provides command line tools for managing your knowledge base. This reference covers the available commands and their options.
+
+## Core Commands
+
+### sync
+
+Keeps files and the knowledge graph in sync:
+
+```bash
+# Basic sync
+basic-memory sync
+
+# Watch for changes
+basic-memory sync --watch
+
+# Show detailed sync information
+basic-memory sync --verbose
+```
+
+Options:
+- `--watch`: Continuously monitor for changes
+- `--verbose`: Show detailed output
+
+**Note**:
+
+As of the v0.12.0 release syncing will occur in real time when the mcp process starts.
+- The real time sync means that it is no longer necessary to run the `basic-memory sync --watch` process in a a terminal to sync changes to the db (so the AI can see them). This will be done automatically.
+
+This behavior can be changed via the config. The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
+
+To change the properties, set the following values:
+```
+ ~/.basic-memory/config.json 
+{
+  "sync_changes": false,
+}
+```
+
+Thanks for using Basic Memory!
+### import
+
+Imports external knowledge sources:
+
+```bash
+# Claude conversations
+basic-memory import claude conversations
+
+# Claude projects
+basic-memory import claude projects
+
+# ChatGPT history
+basic-memory import chatgpt
+
+# ChatGPT history
+basic-memory import memory-json /path/to/memory.json
+
+```
+
+> **Note**: After importing, run `basic-memory sync` to index the new files.
+### status
+
+Shows system status information:
+
+```bash
+# Basic status check
+basic-memory status
+
+# Detailed status
+basic-memory status --verbose
+
+# JSON output
+basic-memory status --json
+```
+
+
+### project
+
+Create multiple projects to manage your knowledge. 
+  
+```bash  
+# List all configured projects  
+basic-memory project list  
+  
+# Add a new project  
+basic-memory project add work ~/work-basic-memory  
+  
+# Set the default project  
+basic-memory project default work  
+  
+# Remove a project (doesn't delete files)  
+basic-memory project remove personal  
+  
+# Show current project  
+basic-memory project current  
+```  
+
+> Be sure to restart Claude Desktop after changing projects. 
+
+#### Using Projects in Commands  
+  
+All commands support the `--project` flag to specify which project to use:  
+  
+```bash  
+# Sync a specific project  
+basic-memory --project=work sync  
+  
+# Run MCP server for a specific project  
+basic-memory --project=personal mcp  
+```  
+  
+You can also set the `BASIC_MEMORY_PROJECT` environment variable:  
+  
+```bash  
+BASIC_MEMORY_PROJECT=work basic-memory sync  
+```  
+
+### help
+
+The full list of commands and help for each can be viewed with the `--help` argument.
+
+```
+ ✗ basic-memory --help
+
+ Usage: basic-memory [OPTIONS] COMMAND [ARGS]...
+
+ Basic Memory - Local-first personal knowledge management system.
+
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮
+│ --project             -p      TEXT  Specify which project to use                          │
+│                                     [env var: BASIC_MEMORY_PROJECT]                       │
+│                                     [default: None]                                       │
+│ --version             -V            Show version information and exit.                    │
+│ --install-completion                Install completion for the current shell.             │
+│ --show-completion                   Show completion for the current shell, to copy it or  │
+│                                     customize the installation.                           │
+│ --help                              Show this message and exit.                           │
+╰───────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ────────────────────────────────────────────────────────────────────────────────╮
+│ sync      Sync knowledge files with the database.                                         │
+│ status    Show sync status between files and database.                                    │
+│ reset     Reset database (drop all tables and recreate).                                  │
+│ mcp       Run the MCP server for Claude Desktop integration.                              │
+│ import    Import data from various sources                                                │
+│ tool      Direct access to MCP tools via CLI                                              │
+│ project   Manage multiple Basic Memory projects                                           │
+╰───────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Initial Setup
+
+```bash
+# Install Basic Memory
+uv install basic-memory
+
+# First sync
+basic-memory sync
+
+# Start watching mode
+basic-memory sync --watch
+```
+
+> **Important**: You need to install Basic Memory via `uv` or `pip` to use the command line tools, see [[Getting Started with Basic Memory#Installation]].
+
+## Regular Usage
+
+```bash
+# Check status
+basic-memory status
+
+# Import new content
+basic-memory import claude conversations
+
+# Sync changes
+basic-memory sync
+
+# Sync changes continuously
+basic-memory sync --watch
+```
+
+## Maintenance Tasks
+
+```bash
+# Check system status in detail
+basic-memory status --verbose
+
+# Full resync of all files
+basic-memory sync
+
+# Import updates to specific folder
+basic-memory import claude conversations --folder new
+```
+
+
+## Using stdin with Basic Memory's `write_note` Tool
+
+The `write-note` tool supports reading content from standard input (stdin), allowing for more flexible workflows when creating or updating notes in your Basic Memory knowledge base.
+
+### Use Cases
+
+This feature is particularly useful for:
+
+1. **Piping output from other commands** directly into Basic Memory notes
+2. **Creating notes with multi-line content** without having to escape quotes or special characters
+3. **Integrating with AI assistants** like Claude Code that can generate content and pipe it to Basic Memory
+4. **Processing text data** from files or other sources
+
+### Basic Usage
+
+#### Method 1: Using a Pipe
+
+You can pipe content from another command into `write_note`:
+
+```bash
+# Pipe output of a command into a new note
+echo "# My Note\n\nThis is a test note" | basic-memory tool write-note --title "Test Note" --folder "notes"
+
+# Pipe output of a file into a new note
+cat README.md | basic-memory tool write-note --title "Project README" --folder "documentation"
+
+# Process text through other tools before saving as a note
+cat data.txt | grep "important" | basic-memory tool write-note --title "Important Data" --folder "data"
+```
+
+#### Method 2: Using Heredoc Syntax
+
+For multi-line content, you can use heredoc syntax:
+
+```bash
+# Create a note with heredoc
+cat << EOF | basic-memory tool write_note --title "Project Ideas" --folder "projects"
+# Project Ideas for Q2
+
+## AI Integration
+- Improve recommendation engine
+- Add semantic search to product catalog
+
+## Infrastructure
+- Migrate to Kubernetes
+- Implement CI/CD pipeline
+EOF
+```
+
+#### Method 3: Input Redirection
+
+You can redirect input from a file:
+
+```bash
+# Create a note from file content
+basic-memory tool write-note --title "Meeting Notes" --folder "meetings" < meeting_notes.md
+```
+
+## Integration with Claude Code
+
+This feature works well with Claude Code in the terminal:
+
+### cli
+
+In a Claude Code session, let Claude know he can use the basic-memory tools, then he can execute them via the cli:
+
+```
+⏺ Bash(echo "# Test Note from Claude\n\nThis is a test note created by Claude to test the stdin functionality." | basic-memory tool write-note --title "Claude Test Note" --folder "test" --tags "test" --tags "claude")…
+  ⎿  # Created test/Claude Test Note.md (23e00eec)
+     permalink: test/claude-test-note
+
+     ## Tags
+     - test, claude
+
+```
+
+### MCP
+
+Claude code can also now use mcp tools, so it can use any of the basic-memory tool natively. To install basic-memory in Claude Code:
+
+Run
+```
+claude mcp add basic-memory basic-memory mcp
+```
+
+For example: 
+
+```
+➜  ~ claude mcp add basic-memory basic-memory mcp
+Added stdio MCP server basic-memory with command: basic-memory mcp to project config
+➜  ~ claude mcp list
+basic-memory: basic-memory mcp
+```
+
+You can then use the `/mcp` command in the REPL:
+
+```
+/mcp
+  ⎿  MCP Server Status
+
+     • basic-memory: connected
+```
+
+## Troubleshooting Common Issues
+
+### Sync Conflicts
+
+If you encounter a file changed during sync error:
+1. Check the file referenced in the error message
+2. Resolve any conflicts manually
+3. Run sync again
+
+### Import Errors
+
+If import fails:
+1. Check that the source file is in the correct format
+2. Verify permissions on the target directory
+3. Use --verbose flag for detailed error information
+
+### Status Issues
+
+If status shows problems:
+1. Note any unresolved relations or warnings
+2. Run a full sync to attempt automatic resolution
+3. Check file permissions if database access errors occur
+
+
+## Relations
+- used_by [[Getting Started with Basic Memory]] (Installation instructions)
+- complements [[User Guide]] (How to use Basic Memory)
+- relates_to [[Introduction to Basic Memory]] (System overview)

docs/Canvas.md

@@ -0,0 +1,107 @@
+---
+title: Canvas Visualizations
+type: note
+permalink: docs/canvas
+tags:
+- visualization
+- mapping
+- obsidian
+---
+
+# Canvas Visualizations
+
+Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure.
+
+## Creating Canvas Visualizations
+
+Ask Claude to create a visualization by describing what you want to map:
+
+```
+You: "Create a canvas visualization of my project components and their relationships."
+
+You: "Make a concept map showing the main themes from our discussion about climate change."
+
+You: "Can you make a canvas diagram of the perfect pour over method?"
+```
+
+![[Canvas.png]]
+
+## Types of Visualizations
+
+Basic Memory can create several types of visual maps:
+
+### Document Maps
+Visualize connections between your notes and documents
+
+### Concept Maps
+Create visual representations of ideas and their relationships
+
+### Process Diagrams
+Map workflows, sequences, and procedures
+
+### Thematic Analysis
+Organize ideas around central themes
+
+### Relationship Networks
+Show how different entities relate to each other
+
+## Visualization Sources
+
+Claude can create visualizations based on:
+
+### Documents in Your Knowledge Base
+```
+You: "Create a canvas showing the connections between my project planning documents"
+```
+
+### Conversation Content
+```
+You: "Make a canvas visualization of the main points we just discussed"
+```
+
+### Search Results
+```
+You: "Find all my notes about psychology and create a visual map of the concepts"
+```
+
+### Themes and Relationships
+```
+You: "Create a visual map showing how different philosophical schools relate to each other"
+```
+
+## Visualization Workflow
+
+1. **Request a visualization** by describing what you want to see
+2. **Claude creates the canvas file** in your Basic Memory directory
+3. **Open the file in Obsidian** to view the visualization
+4. **Refine the visualization** by asking Claude for adjustments:
+   ```
+   You: "Could you reorganize the canvas to group related components together?"
+   
+   You: "Please add more detail about the connection between these two concepts."
+   ```
+
+## Technical Details
+
+Behind the scenes, Claude:
+
+1. Creates a `.canvas` file in JSON format
+2. Adds nodes for each concept or document
+3. Creates edges to represent relationships
+4. Sets positions for visual clarity
+5. Includes any relevant metadata
+
+The resulting file is fully compatible with Obsidian's Canvas feature and can be edited directly in Obsidian.
+
+## Tips for Effective Visualizations
+
+- **Be specific** about what you want to visualize
+- **Specify the level of detail** you need
+- **Mention the visualization type** you want (concept map, process flow, etc.)
+- **Start simple** and ask for refinements
+- **Provide context** about what documents or concepts to include
+
+## Relations
+- enhances [[Obsidian Integration]] (Using Basic Memory with Obsidian)
+- visualizes [[Knowledge Format]] (The structure of your knowledge)
+- complements [[User Guide]] (Ways to use Basic Memory)

docs/Getting Started with Basic Memory.md

@@ -0,0 +1,293 @@
+---
+title: Getting Started with Basic Memory
+type: note
+permalink: docs/getting-started
+---
+
+# Getting Started with Basic Memory
+
+This guide will help you install Basic Memory, configure it with Claude Desktop, and create your first knowledge notes
+through conversations.
+
+Basic Memory uses the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) to connect with LLMs.
+It can be used with any service that supports the MCP, but Claude Desktop works especially well.
+
+## Installation
+
+### Prerequisites
+
+The easiest way to install basic memory is via `uv`. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+### 1. Install Basic Memory
+
+```bash
+# Install with uv (recommended).  
+uv tool install basic-memory
+
+# Or with pip
+pip install basic-memory
+```
+
+> **Important**: You need to install Basic Memory using one of the commands above to use the command line tools.
+
+Using `uv tool install` will install the basic-memory package in a standalone virtual environment. See the [UV docs](https://docs.astral.sh/uv/concepts/tools/) for more info.
+
+### 2. Configure Claude Desktop
+
+Edit your Claude Desktop config, located at `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+**Restart Claude Desktop**. You should see Basic Memory tools available in the "tools" menu in Claude Desktop (the little hammer icon in the bottom-right corner of the chat interface). Click it to view available tools.
+#### Fix Path to uv
+
+If you get an error that says `ENOENT` , this most likely means Claude Desktop could not find your `uv` installation. Make sure that you have `uv` installed per the instructions above, then:
+
+**Step 1: Find the absolute path to uvx**
+
+Open Terminal and run:
+
+```bash
+which uvx
+```
+
+This will show you the full path (e.g., `/Users/yourusername/.cargo/bin/uvx`).
+
+**Step 2: Edit Claude Desktop Configuration**
+
+Edit the Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "/absolute/path/to/uvx",
+      "args": [
+        "basic-memory",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/uvx` with the actual path you found in Step 1.
+
+**Step 3: Restart Claude Desktop**
+
+Close and reopen Claude Desktop for the changes to take effect.
+
+### 3. Sync changes in real time
+
+> **Note**: The service will sync changes from your project directory in real time so they available for the AI assistant. 
+
+To disable realtime sync, you can update the config. See [[CLI Reference#sync]].
+### 4. Staying Updated
+
+To update Basic Memory when new versions are released:
+
+```bash
+# Update with uv (recommended)
+uv tool upgrade basic-memory 
+
+# Or with pip 
+pip install --upgrade basic-memory
+```
+
+> **Note**: After updating, you'll need to restart Claude Desktop and your sync process for changes to take effect.
+
+### 5. Change the default project directory
+
+By default, Basic Memory will create a project in the  `basic-memory` folder in your home directory. You can change this via the `project` [[CLI Reference#project|cli command]]. 
+
+```  
+# Add a new project  
+basic-memory project add work ~/work-basic-memory  
+  
+# Set the default project  
+basic-memory project default work  
+
+# List all configured projects  
+basic-memory project list  
+```
+
+## Troubleshooting Installation
+
+### Common Issues
+
+#### Claude Says "No Basic Memory Tools Available"
+
+If Claude cannot find Basic Memory tools:
+
+1. **Check absolute paths**: Ensure you're using complete absolute paths to uvx in the Claude Desktop configuration
+2. **Verify installation**: Run `basic-memory --version` in Terminal to confirm Basic Memory is installed
+3. **Restart applications**: Restart both Terminal and Claude Desktop after making configuration changes
+4. **Check sync status**: You can view the sync status by running `basic-memory status
+.
+#### Permission Issues
+
+If you encounter permission errors:
+
+1. Check that Basic Memory has access to create files in your home directory
+2. Ensure Claude Desktop has permission to execute the uvx command
+
+## Creating Your First Knowledge Note
+
+1. **Open Claude Desktop** and start a new conversation.
+
+2. **Have a natural conversation** about any topic:
+   ```
+   You: "Let's talk about coffee brewing methods I've been experimenting with."
+   Claude: "I'd be happy to discuss coffee brewing methods..."
+   You: "I've found that pour over gives more flavor clarity than French press..."
+   ```
+
+3. **Ask Claude to create a note**:
+   ```
+   You: "Could you create a note summarizing what we've discussed about coffee brewing?"
+   ```
+
+4. **Confirm note creation**:
+   Claude will confirm when the note has been created and where it's stored.
+
+5. **View the created file** in your `~/basic-memory` directory using any text editor or Obsidian.
+   The file structure will look similar to:
+   ```markdown
+   ---
+   title: Coffee Brewing Methods
+   permalink: coffee-brewing-methods
+   ---
+   
+   # Coffee Brewing Methods
+   
+   ## Observations
+   - [method] Pour over provides more clarity...
+   - [technique] Water temperature at 205°F...
+   
+   ## Relations
+   - relates_to [[Other Coffee Topics]]
+   ```
+
+5. **Start the sync process** in a Terminal window (optional):
+   ```bash
+   basic-memory sync --watch
+   ```
+   Keep this running in the background.
+
+## Using Special Prompts
+
+Basic Memory includes special prompts that help you start conversations with context from your knowledge base:
+
+### Continue Conversation
+
+To resume a previous topic:
+
+```
+You: "Let's continue our conversation about coffee brewing."
+```
+
+This prompt triggers Claude to:
+
+1. Search your knowledge base for relevant content about coffee brewing
+2. Build context from these documents
+3. Resume the conversation with full awareness of previous discussions
+
+### Recent Activity
+
+To see what you've been working on:
+
+```
+You: "What have we been discussing recently?"
+```
+
+This prompt causes Claude to:
+
+1. Retrieve documents modified in the recent past
+2. Summarize the topics and main points
+3. Offer to continue any of those discussions
+
+### Search
+
+To find specific information:
+
+```
+You: "Find information about pour over coffee methods."
+```
+
+Claude will:
+
+1. Search your knowledge base for relevant documents
+2. Summarize the key findings
+3. Offer to explore specific documents in more detail
+
+See [[User Guide#Using Special Prompts]] for further information.
+
+## Using Your Knowledge Base
+
+### Referencing Knowledge
+
+In future conversations, reference your existing knowledge:
+
+```
+You: "What water temperature did we decide was optimal for coffee brewing?"
+```
+
+Or directly reference notes using memory:// URLs:
+
+```
+You: "Take a look at memory://coffee-brewing-methods and let's discuss how to improve my technique."
+```
+
+### Building On Previous Knowledge
+
+Basic Memory enables continuous knowledge building:
+
+1. **Reference previous discussions** in new conversations
+2. **Add to existing notes** through conversations
+3. **Create connections** between related topics
+4. **Follow relationships** to build comprehensive context
+
+## Importing Existing Conversations
+
+Import your existing AI conversations:
+
+```bash
+# From Claude
+basic-memory import claude conversations
+
+# From ChatGPT
+basic-memory import chatgpt
+```
+
+After importing, the changes will be synced. Initial syncs may take a few moments. You can see info about your project by running `basic-memrory project info`.
+
+## Quick Tips
+
+- Basic Memory will sync changes from your project in real time.
+- Use special prompts (Continue Conversation, Recent Activity, Search) to start contextual discussions
+- Build connections between notes for a richer knowledge graph
+- Use direct `memory://` URLs with a permalink when you need precise context. See [[User Guide#Using memory // URLs]]
+- Use git to version control your knowledge base (git integration is on the roadmap)
+- Review and edit AI-generated notes for accuracy
+
+## Next Steps
+
+After getting started, explore these areas:
+
+1. **Read the [[User Guide]]** for comprehensive usage instructions
+2. **Understand the [[Knowledge Format]]** to learn how knowledge is structured
+3. **Set up [[Obsidian Integration]]** for visual knowledge navigation
+4. **Learn about [[Canvas]]** visualizations for mapping concepts
+5. **Review the [[CLI Reference]]** for command line tools

docs/Knowledge Format.md

@@ -0,0 +1,207 @@
+---
+title: Knowledge Format
+type: note
+permalink: docs/knowledge-format
+tags:
+- architecture
+- patterns
+- knowledge
+- design
+---
+
+# Knowledge Format
+
+Basic Memory uses standard Markdown with simple semantic patterns to create a knowledge graph. This document details the file structure and patterns used to organize knowledge.
+
+## File-First Architecture
+
+All knowledge in Basic Memory is stored in plain text Markdown files:
+
+- Files are the source of truth for all knowledge
+- Changes to files automatically update the knowledge graph
+- You maintain complete ownership and control
+- Files work with git and other version control systems
+- Knowledge persists independently of any AI conversation
+
+## Core Document Structure
+
+Every document uses this basic structure:
+
+```markdown
+---
+title: Document Title
+type: note
+tags: [tag1, tag2]
+permalink: custom-path
+---
+
+# Document Title
+
+Regular markdown content...
+
+## Observations
+- [category] Content with #tags (optional context)
+
+## Relations
+- relation_type [[Other Document]] (optional context)
+```
+
+### Frontmatter
+
+The YAML frontmatter at the top of each file defines essential metadata:
+
+```yaml
+---
+title: Document Title    # Used for linking and references
+type: note               # Document type
+tags: [tag1, tag2]       # For organization and searching
+permalink: custom-link   # Optional custom URL path
+---
+```
+
+The title is particularly important as it's used to create links between documents.
+
+### Observations
+
+Observations are facts or statements about a topic:
+
+```markdown
+## Observations
+- [tech] Uses SQLite for storage #database
+- [design] Follows local-first architecture #architecture
+- [decision] Selected bcrypt for passwords #security (Based on audit)
+```
+
+Each observation contains:
+- **Category** in [brackets] - classifies the information type
+- **Content text** - the main information
+- Optional **#tags** - additional categorization
+- Optional **(context)** - supporting details
+
+Common categories include:
+- `[tech]`: Technical details
+- `[design]`: Architecture decisions
+- `[feature]`: User capabilities
+- `[decision]`: Choices that were made
+- `[principle]`: Fundamental concepts
+- `[method]`: Approaches or techniques
+- `[preference]`: Personal opinions
+
+### Relations
+
+Relations connect documents to form the knowledge graph:
+
+```markdown
+## Relations
+- implements [[Search Design]]
+- depends_on [[Database Schema]]
+- relates_to [[User Interface]]
+```
+
+You can also create inline references:
+```markdown
+This builds on [[Core Design]] and uses [[Utility Functions]].
+```
+
+Common relation types include:
+- `implements`: Implementation of a specification
+- `depends_on`: Required dependency
+- `relates_to`: General connection
+- `inspired_by`: Source of ideas
+- `extends`: Enhancement
+- `part_of`: Component relationship
+- `contains`: Hierarchical relationship
+- `pairs_with`: Complementary relationship
+
+## Knowledge Graph
+
+Basic Memory automatically builds a knowledge graph from your document connections:
+
+- Each document becomes a node in the graph
+- Relations create edges between nodes
+- Relation types add semantic meaning to connections
+- Forward references can link to documents that don't exist yet
+
+This graph enables rich context building and navigation across your knowledge base.
+
+## Permalinks and memory:// URLs
+
+Every document in Basic Memory has a unique permalink that serves as its stable identifier:
+
+### How Permalinks Work
+
+- **Automatically assigned**: The system generates a permalink for each document
+- **Based on title**: By default, derived from the document title
+- **Always unique**: If conflicts exist, the system adds a suffix to ensure uniqueness
+- **Stable reference**: Remains the same even if the file moves in the directory structure
+- **Used in memory:// URLs**: Forms the basis of the memory:// addressing scheme
+
+You can specify a custom permalink in the frontmatter:
+```yaml
+---
+title: Authentication Approaches
+permalink: auth-approaches-2024
+---
+```
+
+If not specified, one will be generated automatically from the title, if the note has has a frontmatter section. 
+
+By default a  notes' permalink value will not change if the file is moved. It's a **stable** identifier :). But if you'd rather permalinks are always updated when a file moves, you can set the config setting in the global config. 
+
+The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
+
+To change the behavior, set the following value:
+```
+ ~/.basic-memory/config.json 
+{
+  "update_permalinks_on_move": true
+}
+```
+
+### Using memory:// URLs
+
+The memory:// URL scheme provides a reliable way to reference knowledge:
+
+```
+memory://auth-approaches-2024        # Direct access by permalink
+memory://Authentication Approaches   # Access by title (automatically resolves)
+memory://project/auth-approaches     # Access by path
+```
+
+Memory URLs support pattern matching for more powerful queries:
+
+```
+memory://auth*                      # All documents with permalinks starting with "auth"
+memory://*/approaches               # All documents with permalinks ending with "approaches"
+memory://project/*/requirements     # All requirements documents in the project folder
+memory://docs/search/implements/*   # Follow all implements relations from search docs
+```
+
+This addressing scheme ensures content remains accessible even as your knowledge base evolves and files are reorganized.
+
+## File Organization
+
+Organize files in any structure that suits your needs:
+
+```
+docs/
+  architecture/
+    design.md
+    patterns.md
+  features/
+    search.md
+    auth.md
+```
+
+You can:
+- Group by topic in folders
+- Use a flat structure with descriptive filenames
+- Tag files for easier discovery
+- Add custom metadata in frontmatter
+
+The system will build the semantic knowledge graph regardless of how you organize your files.
+
+## Relations
+- implemented_by [[User Guide]] (How to work with this format)
+- relates_to [[Getting Started with Basic Memory]] (Setup instructions)
+- explained_in [[Introduction to Basic Memory]] (Overview of the system)

docs/Obsidian Integration.md

@@ -0,0 +1,146 @@
+---
+title: Obsidian Integration
+type: note
+permalink: docs/obsidian-integration
+---
+
+# Obsidian Integration
+
+Basic Memory integrates seamlessly with [Obsidian](https://obsidian.md), providing powerful visualization and navigation capabilities for your knowledge graph.
+
+## Setup
+
+### Creating an Obsidian Vault
+
+1. Download and install [Obsidian](https://obsidian.md)
+2. Create a new vault
+3. Point it to your Basic Memory directory (~/basic-memory by default)
+4. Enable core plugins like Graph View, Backlinks, and Tags
+
+## Visualization Features
+
+### Graph View
+
+Obsidian's Graph View provides a visual representation of your knowledge network:
+
+- Each document appears as a node
+- Relations appear as connections between nodes
+- Colors can be customized to distinguish types
+- Filters let you focus on specific aspects
+- Local graphs show connections for individual documents
+
+### Backlinks
+
+Obsidian automatically tracks references between documents:
+
+- View all documents that reference the current one
+- See the exact context of each reference
+- Navigate easily through connections
+- Track how concepts relate to each other
+
+### Tag Explorer
+
+Use tags to organize and filter content:
+
+- View all tags in your knowledge base
+- See how many documents use each tag
+- Filter documents by tag combinations
+- Create hierarchical tag structures
+
+## Knowledge Elements
+
+Basic Memory's knowledge format works natively with Obsidian:
+
+### Wiki Links
+
+```markdown
+## Relations
+- implements [[Search Design]]
+- depends_on [[Database Schema]]
+```
+
+These display as clickable links in Obsidian and appear in the graph view.
+
+### Observations with Tags
+
+```markdown
+## Observations
+- [tech] Using SQLite #database
+- [design] Local-first #architecture
+```
+
+Tags become searchable and filterable in Obsidian's tag pane.
+
+### Frontmatter
+
+```yaml
+---
+title: Document Title
+type: note
+tags: [search, design]
+---
+```
+
+Frontmatter provides metadata for Obsidian to use in search and filtering.
+
+## Canvas Integration
+
+Basic Memory can create [Obsidian Canvas](https://obsidian.md/canvas) files:
+
+1. Ask Claude to create a visualization:
+   ```
+   You: "Create a canvas showing the structure of our project components."
+   ```
+
+2. Claude generates a .canvas file in your knowledge base
+
+3. Open the file in Obsidian to view and edit the visual representation
+
+4. Canvas files maintain references to your documents
+
+## Recommended Plugins
+
+These Obsidian plugins work especially well with Basic Memory:
+
+- **Dataview**: Query your knowledge base programmatically
+- **Kanban**: Organize tasks from knowledge files
+- **Calendar**: View and navigate temporal knowledge
+- **Templates**: Create consistent knowledge structures
+
+## Workflow Suggestions
+
+### Daily Notes
+
+```markdown
+# 2024-01-21
+
+## Progress
+- Updated [[Search Design]]
+- Fixed [[Bug Report 123]]
+
+## Notes
+- [idea] Better indexing #enhancement
+- [todo] Update docs #documentation
+
+## Links
+- relates_to [[Current Sprint]]
+- updates [[Project Status]]
+```
+
+### Project Tracking
+
+```markdown
+# Current Sprint
+
+## Tasks
+- [ ] Update [[Search]]
+- [ ] Fix [[Auth Bug]]
+
+## Tags
+#sprint #planning #current
+```
+
+## Relations
+- enhances [[Introduction to Basic Memory]] (Overview of system)
+- relates_to [[Canvas]] (Visual knowledge mapping)
+- complements [[User Guide]] (Using Basic Memory)

docs/Technical Information.md

@@ -0,0 +1,243 @@
+---
+title: Technical Information
+type: note
+permalink: docs/technical-information
+---
+
+# Technical Information
+
+This document provides technical details about Basic Memory's implementation, licensing, and integration with the Model Context Protocol (MCP).
+
+## Architecture
+
+Basic Memory consists of:
+
+1. **Core Knowledge Engine**: Parses and indexes Markdown files
+2. **SQLite Database**: Provides fast querying and search
+3. **MCP Server**: Implements the Model Context Protocol
+4. **CLI Tools**: Command-line utilities for management
+5. **Sync Service**: Monitors file changes and updates the database
+
+The system follows a file-first architecture where all knowledge is represented in standard Markdown files and the database serves as a secondary index.
+
+## Model Context Protocol (MCP)
+
+Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools:
+
+- **Standardized Interface**: Common protocol for tool integration
+- **Tool Registration**: Basic Memory registers as a tool provider
+- **Asynchronous Communication**: Enables efficient interaction with AI models
+- **Standardized Schema**: Structured data exchange format
+
+Integration with Claude Desktop uses the MCP to grant Claude access to your knowledge base through a set of specialized tools that search, read, and write knowledge.
+
+## Licensing
+
+Basic Memory is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.en.html):
+
+- **Free Software**: You can use, study, share, and modify the software
+- **Copyleft**: Derivative works must be distributed under the same license
+- **Network Use**: Network users must be able to receive the source code
+- **Commercial Use**: Allowed, subject to license requirements
+
+The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks.
+
+## Source Code
+
+Basic Memory is developed as an open-source project:
+
+- **GitHub Repository**: [https://github.com/basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory)
+- **Issue Tracker**: Report bugs and request features on GitHub
+- **Contributions**: Pull requests are welcome following the contributing guidelines
+- **Documentation**: Source for this documentation is also available in the repository
+
+## Data Storage and Privacy
+
+Basic Memory is designed with privacy as a core principle:
+
+- **Local-First**: All data remains on your local machine
+- **No Cloud Dependency**: No remote servers or accounts required
+- **Telemetry**: Optional and disabled by default
+- **Standard Formats**: All data is stored in standard file formats you control
+
+## Implementation Details
+
+Knowledge in Basic Memory is organized as a semantic graph:
+
+1. **Entities** - Distinct concepts represented by Markdown documents
+2. **Observations** - Categorized facts and information about entities
+3. **Relations** - Connections between entities that form the knowledge graph
+
+This structure emerges from simple text patterns in standard Markdown:
+
+```markdown
+---
+title: Coffee Brewing Methods
+type: note
+permalink: coffee/coffee-brewing-methods
+tags:
+- '#coffee'
+- '#brewing'
+- '#methods'
+- '#demo'
+---
+
+# Coffee Brewing Methods
+
+An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction.
+
+## Overview
+
+Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans,
+resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are:
+
+- Grind size
+- Water temperature
+- Brew time
+- Coffee-to-water ratio
+- Agitation/turbulence
+
+## Observations
+
+- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds
+  #extraction
+- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity
+
+## Relations
+
+- requires [[Proper Grinding Technique]]
+- affects [[Flavor Extraction]]
+```
+
+Becomes
+
+```json
+{
+  "entities": [
+    {
+      "permalink": "coffee/coffee-brewing-methods",
+      "title": "Coffee Brewing Methods",
+      "file_path": "Coffee Notes/Coffee Brewing Methods.md",
+      "entity_type": "note",
+      "entity_metadata": {
+        "title": "Coffee Brewing Methods",
+        "type": "note",
+        "permalink": "coffee/coffee-brewing-methods",
+        "tags": "['#coffee', '#brewing', '#methods', '#demo']"
+      },
+      "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c",
+      "content_type": "text/markdown",
+      "observations": [
+        {
+          "category": "principle",
+          "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction",
+          "tags": [
+            "extraction"
+          ],
+          "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction"
+        },
+        {
+          "category": "method",
+          "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity",
+          "tags": [
+            "clarity"
+          ],
+          "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity"
+        }
+      ],
+      "relations": [
+        {
+          "from_id": "coffee/coffee-bean-origins",
+          "to_id": "coffee/coffee-brewing-methods",
+          "relation_type": "pairs_with",
+          "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods",
+          "to_name": "Coffee Brewing Methods"
+        },
+        {
+          "from_id": "coffee/flavor-extraction",
+          "to_id": "coffee/coffee-brewing-methods",
+          "relation_type": "affected_by",
+          "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods",
+          "to_name": "Coffee Brewing Methods"
+        }
+      ],
+      "created_at": "2025-03-06T14:01:23.445071",
+      "updated_at": "2025-03-06T13:34:48.563606"
+    }
+  ]
+}
+```
+
+Basic Memory understands how to build context via its semantic graph.
+
+### Entity Model
+
+Basic Memory's core data model consists of:
+
+- **Entities**: Documents in your knowledge base
+- **Observations**: Facts or statements about entities
+- **Relations**: Connections between entities
+- **Tags**: Additional categorization for entities and observations
+
+The system parses Markdown files to extract this structured information while preserving the human-readable format.
+
+### Files as Source of Truth
+
+Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git.
+
+```mermaid
+flowchart TD
+    User((User)) <--> |Conversation| Claude["Claude or other LLM"]
+    Claude <-->|API Calls| BMCP["Basic Memory MCP Server"]
+    
+    subgraph "Local Storage"
+        KnowledgeFiles["Markdown Files - Source of Truth"]
+        KnowledgeIndex[(Knowledge Graph SQLite Index)]
+    end
+    
+    BMCP <-->|"write_note() read_note()"| KnowledgeFiles
+    BMCP <-->|"search_notes() build_context()"| KnowledgeIndex
+    KnowledgeFiles <-.->|Sync Process| KnowledgeIndex
+    KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git))
+    
+    User -.->|"Complete control, Privacy preserved"| KnowledgeFiles
+    
+    
+    class Claude primary
+    class BMCP secondary
+    class KnowledgeFiles tertiary
+    class KnowledgeIndex quaternary
+    class User,Editors user`;
+```
+
+### Sqlite Database
+
+A local SQLite database maintains the knowledge graph topology for fast queries and semantic traversal without cloud dependencies. It contains:
+- db tables for the knowledge graph schema
+- a search index table enabling full text search across the knowledge base
+
+
+### Sync Process
+
+The sync process:
+
+1. Detects changes to files in the knowledge directory
+2. Parses modified files to extract structured data
+3. Updates the SQLite database with changes
+4. Resolves forward references when new entities are created
+5. Updates the search index for fast querying
+
+### Search Engine
+
+The search functionality:
+
+1. Uses a combination of full-text search and semantic matching
+2. Indexes observations, relations, and content
+3. Supports wildcards and pattern matching in memory:// URLs
+4. Traverses the knowledge graph to follow relationships
+5. Ranks results by relevance to the query
+
+## Relations
+- relates_to [[Welcome to Basic memory]] (Overview)
+- relates_to [[CLI Reference]] (Command line tools)
+- implements [[Knowledge Format]] (File structure and format)

docs/User Guide.md

@@ -0,0 +1,556 @@
+---
+title: User Guide
+type: note
+permalink: docs/user-guide
+---
+
+# User Guide
+
+This guide explains how to effectively use Basic Memory in your daily workflow, from creating knowledge through
+conversations to building a rich semantic network.
+
+## Basic Memory Workflow
+
+Using Basic Memory follows a natural cycle:
+
+1. **Have conversations** with AI assistants like Claude
+2. **Capture knowledge** in Markdown files
+3. **Build connections** between pieces of knowledge
+4. **Reference your knowledge** in future conversations
+5. **Edit files directly** when needed
+6. **Sync changes** automatically
+
+## Creating Knowledge
+
+### Through Conversations
+
+To create knowledge during conversations with Claude:
+
+```
+You: We've covered several authentication approaches. Could you create a note summarizing what we've discussed?
+
+Claude: I'll create a note summarizing our authentication discussion.
+```
+
+This creates a Markdown file in your `~/basic-memory` directory with semantic markup.
+
+### Direct File Creation
+
+You can create files directly:
+
+1. Create a new Markdown file in your `~/basic-memory` directory
+2. Add frontmatter with title, type, and optional tags
+3. Structure content with observations and relations
+4. Save the file
+5. Run `basic-memory sync` if not in watch mode
+
+## Using Special Prompts
+
+Basic Memory includes several special prompts that help you leverage your knowledge base more effectively. In apps like
+Claude Desktop, these prompts trigger specific tools to search and analyze your knowledge base.
+
+### Continue Conversation
+
+When you want to pick up where you left off on a topic:
+
+```
+You: Let's continue our conversation about authentication systems.
+```
+
+Behind the scenes:
+
+- Claude searches your knowledge base for content about "authentication systems"
+- It retrieves relevant documents and their relations
+- It analyzes the context to understand where you left off
+- It builds a comprehensive picture of what you've previously discussed
+- It can then resume the conversation with all that context
+
+This is particularly useful when:
+
+- Starting a new session days or weeks after your last discussion
+- Switching between multiple ongoing projects
+- Building on previous work without repeating yourself
+
+### Recent Activity
+
+To get an overview of what you've been working on:
+
+```
+You: What have we been discussing recently?
+```
+
+Behind the scenes:
+
+- Claude retrieves documents modified recently
+- It analyzes patterns and themes
+- It summarizes the key topics and changes
+- It offers to continue working on any of those topics
+
+This is useful for:
+
+- Coming back after a break
+- Getting a quick reminder of ongoing projects
+- Deciding what to work on next
+
+### Search
+
+To find specific information in your knowledge base:
+
+```
+You: Find information about JWT authentication in my notes.
+```
+
+Behind the scenes:
+
+- Claude performs a semantic search for "JWT authentication"
+- It retrieves and ranks the most relevant documents
+- It summarizes the key findings
+- It offers to explore specific areas in more detail
+
+This is useful for:
+
+- Finding specific information quickly
+- Exploring what you know about a topic
+- Starting work on an existing topic
+
+### Example
+
+Choose "Continue Conversation"
+![[prompt 1.png|500]]
+
+Enter a topic
+![[prompt2.png|500]]
+
+Give instructions
+![[prompt3.png|500]]
+
+Claude Desktop lets you send a prompt to provide context. You can use this at the beginning of a chat to preload context
+without needing to copy paste all the time. By using one of the supplied prompts, Basic Memory will search the knowledge
+base and give the AI instructions for how to build context.
+
+Choose "Continue Conversation":
+
+![[prompt 1.png|500]]
+
+Enter a topic:
+
+![[prompt2.png|500]]
+
+Give optional additional instructions:
+
+![[prompt3.png|500]]
+
+Claude can build context from the supplied topic. This works independently of Claude Project information. All the
+context comes from your local knowledge base.
+
+![[prompt4.png|500]]
+
+## Searching Your Knowledge Base
+
+Basic Memory provides multiple ways to search and explore your knowledge base:
+
+### Natural Language Search
+
+The simplest way to search is to ask Claude directly:
+
+```
+You: What do I know about authentication methods?
+```
+
+Claude will search your knowledge base semantically and return relevant information.
+
+### Search Prompt
+
+Use the dedicated search prompt for more focused searches:
+
+```
+You: Search for "JWT authentication"
+```
+
+This triggers a specialized search that returns precise results with document titles, relevant excerpts, and offers to
+explore specific documents.
+
+### Boolean Search
+
+For more precise searches, use boolean operators to refine your queries:
+
+```
+You: Search for "authentication AND OAuth NOT basic"
+```
+
+Basic Memory supports standard boolean operators:
+
+- **AND**: Find documents containing both terms
+  ```
+  You: Search for "python AND flask"
+  ```
+  This finds documents containing both "python" and "flask"
+
+- **OR**: Find documents containing either term
+  ```
+  You: Search for "python OR javascript"
+  ```
+  This finds documents containing either "python" or "javascript"
+
+- **NOT**: Exclude documents containing specific terms
+  ```
+  You: Search for "python NOT django"
+  ```
+  This finds documents containing "python" but excludes those containing "django"
+
+- **Grouping with parentheses**: Control operator precedence
+  ```
+  You: Search for "(python OR javascript) AND web"
+  ```
+  This finds documents about web development that mention either Python or JavaScript
+
+Boolean search is particularly useful for:
+
+- Narrowing down results in large knowledge bases
+- Finding specific combinations of concepts
+- Excluding irrelevant content from search results
+- Creating complex queries for precise information retrieval
+
+### Memory URL Pattern Matching
+
+For advanced searches, use memory:// URL patterns with wildcards:
+
+```
+You: Look at memory://auth* and summarize all authentication approaches.
+```
+
+Pattern matching supports:
+
+- **Wildcards**: `memory://auth*` matches all permalinks starting with "auth"
+- **Path patterns**: `memory://project/*/auth` matches auth documents in any project subfolder
+- **Relation traversal**: `memory://auth-system/implements/*` finds all documents that implement the auth system
+
+### Combining Search with Context Building
+
+The most powerful searches build comprehensive context by following relationships:
+
+```
+You: Search for JWT authentication and then follow all implementation relations.
+```
+
+This builds a complete picture by:
+
+1. Finding documents about JWT authentication
+2. Following implementation relationships from those documents
+3. Building a complete picture of how JWT is implemented across your system
+
+### Search Best Practices
+
+For effective searching:
+
+1. **Be specific** with search terms and phrases
+2. **Use boolean operators** to refine searches and find precise information
+3. **Use technical terms** when searching for technical content
+4. **Follow up** on search results by asking for more details about specific documents
+5. **Combine approaches** by starting with search and then using memory:// URLs for precision
+6. **Use relation traversal** to explore connected concepts after finding initial documents
+
+## Referencing Knowledge
+
+### Using memory:// URLs
+
+Reference specific knowledge directly:
+
+```
+You: Please look at memory://authentication-approaches and suggest which approach would be best for our mobile app.
+```
+
+### Natural Language References
+
+Reference knowledge conversationally:
+
+```
+You: What did we decide about authentication for the project?
+```
+
+### Advanced References
+
+Follow connections across your knowledge graph:
+
+```
+You: Look at memory://project-architecture and check related documents to give me a complete picture.
+```
+
+## Working with Files
+
+### File Location and Organization
+
+By default, Basic Memory stores files in `~/basic-memory`:
+
+- Browse this directory in your file explorer
+- Organize files into subfolders
+- Use git for version control
+
+### File Format
+
+Each knowledge file follows this structure:
+
+```markdown
+---
+title: Authentication Approaches
+type: note
+tags: [security, architecture]
+permalink: authentication-approaches
+---
+
+# Authentication Approaches
+
+A comparison of authentication methods.
+
+## Observations
+
+- [approach] JWT provides stateless authentication #security
+- [limitation] Session tokens require server-side storage #infrastructure
+
+## Relations
+
+- implements [[Security Requirements]]
+- affects [[User Login Flow]]
+```
+
+### Editing Files
+
+Modify files in any text editor:
+
+1. Open the file in your preferred editor
+2. Make changes to content, observations, or relations
+3. Save the file
+4. Basic Memory detects changes automatically when running in watch mode
+
+## Building a Knowledge Graph
+
+The value of Basic Memory comes from connections between pieces of knowledge.
+
+### Creating Relations
+
+When creating or editing notes, build connections:
+
+```markdown
+## Relations
+
+- implements [[Security Requirements]]
+- depends_on [[User Authentication]]
+```
+
+Relations can be:
+
+- Hierarchical (part_of, contains)
+- Directional (implements, depends_on)
+- Associative (relates_to, similar_to)
+- Temporal (precedes, follows)
+
+Relations are also created via regular wiki-link style links within the body text.
+
+### Forward References
+
+Reference documents that don't exist yet:
+
+```markdown
+- will_impact [[Future Feature]]
+```
+
+These references resolve automatically when you create the referenced document.
+
+## Conversation Continuity
+
+Basic Memory maintains context across different conversations.
+
+### Starting New Sessions with Context
+
+When starting a new conversation with Claude, you can:
+
+1. **Use special prompts** like "Continue conversation about..." or "What were we working on?"
+2. **Reference specific documents** with memory:// URLs
+3. **Ask about recent work** with "What have we been discussing recently?"
+4. **Search for specific topics** with "Find information about..."
+
+### Long-Term Projects
+
+Maintain context for complex projects over time:
+
+1. **Document key decisions** as you make them
+2. **Create relationships** between project components
+3. **Reference past decisions** when implementing features
+4. **Update documentation** as the project evolves
+
+### Tips for Effective Continuity
+
+1. **Be specific about topics** when continuing a conversation
+2. **Reference documents directly** with memory:// URLs for precision
+3. **Create summary notes** after important discussions
+4. **Update existing notes** rather than creating duplicates
+5. **Build robust connections** between related topics
+
+## Advanced Features
+
+### Importing External Knowledge
+
+Import existing conversations:
+
+```bash
+# From Claude
+basic-memory import claude conversations
+
+# From ChatGPT
+basic-memory import chatgpt
+```
+
+After importing, run `basic-memory sync` to index everything.
+
+### Obsidian Integration
+
+Use with [Obsidian](https://obsidian.md):
+
+1. Point Obsidian to your `~/basic-memory` directory
+2. Use Obsidian's graph view to visualize your knowledge network
+3. All changes sync back to Basic Memory
+
+### Canvas Visualizations
+
+Create visual knowledge maps:
+
+```
+You: Could you create a canvas visualization of our project components?
+```
+
+This generates an Obsidian canvas file showing the relationships between concepts.
+
+### Advanced Memory URI Patterns
+
+Use wildcards and patterns:
+
+```
+You: Review memory://project/*/requirements to summarize all project requirements.
+```
+
+## Command Line Interface
+
+### Sync Commands
+
+```bash
+# One-time sync
+basic-memory sync
+
+# Watch for changes
+basic-memory sync --watch
+```
+
+### Status and Information
+
+```bash
+# Check system status
+basic-memory status
+
+# View CLI help
+basic-memory --help
+```
+
+### Import Commands
+
+```bash
+# Import from Claude
+basic-memory import claude conversations
+
+# Import from ChatGPT
+basic-memory import chatgpt
+```
+
+## Multiple Projects
+
+Basic Memory supports managing multiple separate knowledge bases through projects. This feature allows you to maintain  
+separate knowledge graphs for different purposes (e.g., personal notes, work projects, research topics).
+
+Basic Memory keeps a list of projects in a config file: ` ~/.basic-memory/config.json`
+
+### Managing Projects
+
+```bash  
+# List all configured projects  
+basic-memory project list  
+  
+# Add a new project  
+basic-memory project add work ~/work-basic-memory  
+  
+# Set the default project  
+basic-memory project default work  
+  
+# Remove a project (doesn't delete files)  
+basic-memory project remove personal  
+  
+# Show current project  
+basic-memory project current  
+```  
+
+### Using Projects in Commands
+
+All commands support the `--project` flag to specify which project to use:
+
+```bash  
+# Sync a specific project  
+basic-memory --project=work sync  
+  
+# Run MCP server for a specific project  
+basic-memory --project=personal mcp  
+```  
+
+You can also set the `BASIC_MEMORY_PROJECT` environment variable:
+
+```bash  
+BASIC_MEMORY_PROJECT=work basic-memory sync  
+```  
+
+### Project Isolation
+
+Each project maintains:
+
+- Its own collection of markdown files in the specified directory
+- A separate SQLite database for that project
+- Complete knowledge graph isolation from other projects
+
+## Workflow Tips
+
+1. Run sync in watch mode for automatic updates
+2. Use git for version control of your knowledge base
+3. Review and edit AI-created content for accuracy
+4. Periodically organize and refine your knowledge structure
+5. Build rich connections between related ideas
+6. Use forward references to plan future documentation
+7. Start conversations with special prompts to leverage existing knowledge
+
+## Troubleshooting
+
+### Sync Issues
+
+If changes aren't showing up:
+
+1. Verify `basic-memory sync --watch` is running
+2. Run `basic-memory status` to check system state
+3. Try a manual sync with `basic-memory sync`
+
+### Missing Content
+
+If content isn't found:
+
+1. Check the exact path and permalink
+2. Try searching with more general terms
+3. Verify the file exists in your knowledge base
+
+### Relation Problems
+
+If relations aren't working:
+
+1. Ensure exact title matching in [[WikiLinks]]
+2. Check for typos in relation types
+3. Verify both documents exist
+
+## Relations
+
+- implements [[Knowledge Format]] (How knowledge is structured)
+- relates_to [[Getting Started with Basic Memory]] (Setup and first steps)
+- relates_to [[Canvas]] (Creating visual knowledge maps)
+- relates_to [[CLI Reference]] (Command line tools)

docs/Welcome to Basic memory.md

@@ -0,0 +1,68 @@
+---
+title: Introduction to Basic Memory
+type: docs
+permalink: docs/introduction
+tags:
+  - documentation
+  - index
+  - overview
+---
+
+# BASIC MEMORY
+
+Basic Memory is a knowledge management system that allows you to build a persistent semantic graph from conversations
+with AI assistants. All knowledge is stored in standard Markdown files on your computer, giving you full control and
+ownership of your data.
+
+Basic Memory connects you and AI assistants through shared knowledge:
+
+1. **Captures knowledge** from natural conversations with AI assistants
+2. **Structures information** using simple semantic patterns in Markdown
+3. **Enables knowledge reuse** across different conversations and sessions
+4. **Maintains persistence** through local files you control completely
+
+Both you and AI assistants like Claude can read from and write to the same knowledge base, creating a continuous
+learning environment where each conversation builds upon previous ones.
+
+## Pick up your conversation right where you left off
+
+- AI assistants can load context from local files in a new conversation
+- Notes are saved locally as Markdown files in real time
+- No project knowledge or special prompting required
+
+![[Claude-Obsidian-Demo.mp4]]
+
+Basic Memory uses:
+
+- **Files as the source of truth** - Everything is stored in plain Markdown files
+- **Git-compatible storage** - All knowledge can be versioned, branched, and merged
+- **Local SQLite database** - For fast indexing and searching only (not primary storage)
+- **Model Context Protocol (MCP)** - For seamless AI assistant integration
+
+Basic Memory gives you complete control over your knowledge:
+
+- **Local-first storage** - All knowledge lives on your computer
+- **Standard file formats** - Plain Markdown compatible with any editor
+- **Directory organization** - Knowledge stored in `~/basic-memory` by default
+- **Version control ready** - Use git for history, branching, and collaboration
+- **Edit anywhere** - Modify files with any text editor or Obsidian
+
+Changes to files automatically sync with the knowledge graph, and AI assistants can see your edits in conversations.
+
+## Documentation Map
+
+Continue exploring Basic Memory with these guides:
+
+- Installation and setup [[Getting Started with Basic Memory]]
+- Comprehensive usage instructions [[User Guide]]
+- Detailed explanation of knowledge structure [[Knowledge Format]]
+- Obsidian integration guide [[Obsidian Integration]]
+- Canvas visualization guide [[Canvas]]
+- Command line tool reference [[CLI Reference]]
+- Reference for AI assistants using Basic Memory [[AI Assistant Guide]]
+- Technical implementation details [[Technical Information]]
+
+## Next Steps
+
+Start with the [[Getting Started with Basic Memory]] guide to install Basic Memory and configure it with your AI
+assistant.

docs/publish.js

@@ -0,0 +1,5 @@
+var analyticsScript = document.createElement('script');
+analyticsScript.defer = true;
+analyticsScript.setAttribute('data-website-id', '8d51086e-5c67-401e-97b0-b24706a6d4f3');
+analyticsScript.src = 'https://cloud.umami.is/script.js';
+document.head.appendChild(analyticsScript);

examples/.obsidian/app.json

@@ -0,0 +1,3 @@
+{
+  "promptDelete": false
+}

examples/.obsidian/appearance.json

@@ -0,0 +1 @@
+{}

examples/.obsidian/community-plugins.json

@@ -0,0 +1,3 @@
+[
+  "optimize-canvas-connections"
+]

examples/.obsidian/core-plugins.json

@@ -0,0 +1,31 @@
+{
+  "file-explorer": true,
+  "global-search": true,
+  "switcher": true,
+  "graph": true,
+  "backlink": true,
+  "canvas": true,
+  "outgoing-link": true,
+  "tag-pane": true,
+  "properties": false,
+  "page-preview": true,
+  "daily-notes": true,
+  "templates": true,
+  "note-composer": true,
+  "command-palette": true,
+  "slash-command": false,
+  "editor-status": true,
+  "bookmarks": true,
+  "markdown-importer": false,
+  "zk-prefixer": false,
+  "random-note": false,
+  "outline": true,
+  "word-count": true,
+  "slides": false,
+  "audio-recorder": false,
+  "workspaces": false,
+  "file-recovery": true,
+  "publish": true,
+  "sync": true,
+  "webviewer": false
+}

examples/.obsidian/plugins/optimize-canvas-connections/main.js

@@ -0,0 +1,158 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// main.ts
+var main_exports = {};
+__export(main_exports, {
+  default: () => OptimizeCanvasConnectionsPlugin
+});
+module.exports = __toCommonJS(main_exports);
+var import_obsidian = require("obsidian");
+var OptimizeCanvasConnectionsPlugin = class extends import_obsidian.Plugin {
+  async onload() {
+    this.addCommand({
+      id: "optimize-preserve-axes-selection",
+      name: "Optimize selection (preserve axes)",
+      checkCallback: (checking) => {
+        const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
+        if ((canvasView == null ? void 0 : canvasView.getViewType()) == "canvas") {
+          if (!checking) {
+            this.optimize("preserve-axes");
+          }
+          return true;
+        }
+        return false;
+      }
+    });
+    this.addCommand({
+      id: "optimize-shortest-path-selection",
+      name: "Optimize selection (shortest path)",
+      checkCallback: (checking) => {
+        const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
+        if ((canvasView == null ? void 0 : canvasView.getViewType()) == "canvas") {
+          if (!checking) {
+            this.optimize("shortest-path");
+          }
+          return true;
+        }
+        return false;
+      }
+    });
+  }
+  onunload() {
+  }
+  async optimize(option) {
+    const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
+    const canvas = canvasView == null ? void 0 : canvasView.canvas;
+    const currentSelection = canvas == null ? void 0 : canvas.selection;
+    let selectedIDs = new Array();
+    currentSelection.forEach(function(selection) {
+      selectedIDs.push(selection.id);
+    });
+    let applyToAll = false;
+    if (selectedIDs.length == 0) {
+      applyToAll = true;
+    }
+    for (let [edgeKey, edge] of canvas["edges"]) {
+      let fromNode = edge["from"]["node"];
+      let toNode = edge["to"]["node"];
+      let fromPossibilities = [edge["from"]["side"]];
+      if (applyToAll || selectedIDs.includes(fromNode["id"])) {
+        switch (option) {
+          case "shortest-path":
+            fromPossibilities = ["top", "bottom", "left", "right"];
+            break;
+          case "preserve-axes":
+            switch (edge["from"]["side"]) {
+              case "top":
+              case "bottom":
+                fromPossibilities = ["top", "bottom"];
+                break;
+              case "left":
+              case "right":
+                fromPossibilities = ["left", "right"];
+                break;
+            }
+        }
+      }
+      let toPossibilities = [edge["to"]["side"]];
+      if (applyToAll || selectedIDs.includes(toNode["id"])) {
+        switch (option) {
+          case "shortest-path":
+            toPossibilities = ["top", "bottom", "left", "right"];
+            break;
+          case "preserve-axes":
+            switch (edge["to"]["side"]) {
+              case "top":
+              case "bottom":
+                toPossibilities = ["top", "bottom"];
+                break;
+              case "left":
+              case "right":
+                toPossibilities = ["left", "right"];
+                break;
+            }
+        }
+      }
+      let distances = [];
+      for (const fromSide of fromPossibilities) {
+        let fromPoint = { "x": 0, "y": 0 };
+        if (fromSide == "top") {
+          fromPoint = { "x": fromNode["x"] + fromNode["width"] / 2, "y": fromNode["y"] };
+        } else if (fromSide == "bottom") {
+          fromPoint = { "x": fromNode["x"] + fromNode["width"] / 2, "y": fromNode["y"] + fromNode["height"] };
+        } else if (fromSide == "left") {
+          fromPoint = { "x": fromNode["x"], "y": fromNode["y"] + fromNode["height"] / 2 };
+        } else if (fromSide == "right") {
+          fromPoint = { "x": fromNode["x"] + fromNode["width"], "y": fromNode["y"] + fromNode["height"] / 2 };
+        }
+        for (const toSide of toPossibilities) {
+          let toPoint = { "x": 0, "y": 0 };
+          if (toSide == "top") {
+            toPoint = { "x": toNode["x"] + toNode["width"] / 2, "y": toNode["y"] };
+          } else if (toSide == "bottom") {
+            toPoint = { "x": toNode["x"] + toNode["width"] / 2, "y": toNode["y"] + toNode["height"] };
+          } else if (toSide == "left") {
+            toPoint = { "x": toNode["x"], "y": toNode["y"] + toNode["height"] / 2 };
+          } else if (toSide == "right") {
+            toPoint = { "x": toNode["x"] + toNode["width"], "y": toNode["y"] + toNode["height"] / 2 };
+          }
+          distances.push({
+            "fromSide": fromSide,
+            "toSide": toSide,
+            "distance": (toPoint.x - fromPoint.x) ** 2 + (toPoint.y - fromPoint.y) ** 2
+          });
+        }
+      }
+      distances = distances.sort(function(a, b) {
+        return a.distance - b.distance;
+      });
+      edge["from"]["side"] = distances[0]["fromSide"];
+      edge["to"]["side"] = distances[0]["toSide"];
+      edge.render();
+    }
+    canvas.requestSave();
+  }
+};
+
+/* nosourcemap */

examples/.obsidian/plugins/optimize-canvas-connections/manifest.json

@@ -0,0 +1,10 @@
+{
+	"id": "optimize-canvas-connections",
+	"name": "Optimize Canvas Connections",
+	"version": "1.0.0",
+	"minAppVersion": "1.1.9",
+	"description": "An Obsidian plugin that declutters a canvas by reconnecting notes using their nearest edges.",
+	"author": "Félix Chénier",
+	"authorUrl": "https://felixchenier.uqam.ca",
+	"isDesktopOnly": false
+}

examples/.obsidian/publish.json

@@ -0,0 +1,6 @@
+{
+  "siteId": null,
+  "host": null,
+  "included": [],
+  "excluded": []
+}

examples/Coffee Notes/Brewing Equipment.md

@@ -0,0 +1,83 @@
+---
+title: Brewing Equipment
+type: note
+permalink: coffee/brewing-equipment
+tags:
+- '#coffee'
+- '#equipment'
+- '#gear'
+- '#brewing'
+- '#demo'
+---
+
+# Brewing Equipment
+
+Essential tools and equipment for brewing coffee, their characteristics, and how they affect the brewing process.
+
+## Overview
+
+The equipment used to brew coffee plays a crucial role in determining the final cup quality. From grinders to brewers to kettles, each piece of equipment contributes to different aspects of the brewing process.
+
+## Observations
+
+- [principle] Equipment quality often has a bigger impact on consistency than on absolute quality potential #quality
+- [principle] Good grind consistency is the most important technical factor in extraction quality #grind
+- [investment] A good burr grinder is often the most important investment for improving home coffee #gear
+- [technique] Equipment maintenance and cleaning significantly impact flavor consistency over time #maintenance
+
+## Grinders
+
+- [equipment] Burr grinders crush beans between two abrasive surfaces for more consistent particle size #grinders
+- [equipment] Blade grinders chop beans unevenly, leading to inconsistent extraction #grinders
+- [equipment] Flat burr grinders produce very consistent particle size but generate more heat #burrs
+- [equipment] Conical burr grinders create slightly less uniform grounds but with less heat and noise #burrs
+- [feature] Grind adjustment mechanisms range from stepped to stepless for different precision levels #adjustment
+- [feature] Retention (grounds trapped in grinder) affects dose consistency and freshness #retention
+- [price] Hand grinders offer excellent value, with models like Timemore C2 and 1Zpresso JX providing excellent results around $100-150 #budget
+- [price] Entry-level electric burr grinders like Baratza Encore start around $170 but provide significant improvement over blade grinders #value
+
+## Brewers
+
+### Pour Over Brewers
+- [equipment] Hario V60 uses a conical design with spiral ridges to control flow rate #pourover
+- [equipment] Kalita Wave has a flat bottom with three small holes for more consistent extraction #pourover
+- [equipment] Chemex combines brewer and server with thick proprietary filters for ultra-clean cup #pourover
+- [material] Ceramic brewers retain heat better than plastic but are more fragile #materials
+- [material] Glass brewers provide neutral flavor but less heat retention #materials
+- [material] Plastic brewers are inexpensive, durable, and surprisingly good for heat retention #materials
+
+### Immersion Brewers
+- [equipment] French Press uses a metal mesh to separate grounds, allowing oils and fine particles to pass #immersion
+- [equipment] AeroPress uses pressure and paper filter for clean, versatile brewing #immersion
+- [equipment] Clever Dripper combines immersion and drip methods with a valve mechanism #hybrid
+- [material] Glass French presses look elegant but break easily and have poor heat retention #materials
+- [material] Stainless steel or ceramic French presses offer better durability and heat retention #materials
+
+### Pressure Brewers
+- [equipment] Espresso machines use 9 bars of pressure, requiring significant investment for good results #espresso
+- [equipment] Moka pot uses steam pressure for strong, concentrated coffee at affordable price #moka
+- [equipment] Manual lever machines like Flair or Robot provide espresso-style coffee with manual control #manual_espresso
+
+## Kettles
+
+- [equipment] Gooseneck kettles provide precision pouring control essential for pour over methods #kettles
+- [feature] Variable temperature kettles allow precise temperature control for different roast levels #temp_control
+- [feature] Flow restrictors can help beginners maintain consistent pour rates #pour_control
+- [material] Electric kettles offer convenience and temperature stability #convenience
+- [material] Stovetop kettles may be more durable but offer less temperature control #durability
+
+## Accessories
+
+- [equipment] Coffee scale with 0.1g precision helps maintain consistent ratios #measurement
+- [equipment] Timer ensures consistent extraction times #consistency
+- [equipment] Quality filters significantly impact flavor clarity and body #filters
+- [equipment] Storage containers with one-way valves help preserve bean freshness #storage
+- [equipment] Blind shaker or dosing cup reduces grinder mess and improves workflow #workflow
+
+## Relations
+
+- improves [[Coffee Brewing Methods]]
+- affects [[Flavor Extraction]]
+- requires [[Proper Maintenance]]
+- enhances [[Home Coffee Setup]]
+- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Bean Origins.md

@@ -0,0 +1,78 @@
+---
+title: Coffee Bean Origins
+type: note
+permalink: coffee/coffee-bean-origins
+tags:
+- '#coffee'
+- '#origins'
+- '#beans'
+- '#regions'
+- '#demo'
+---
+
+# Coffee Bean Origins
+
+An exploration of coffee-growing regions around the world and how geography, climate, and processing methods affect flavor profiles.
+
+## Overview
+
+Coffee beans are grown in various regions around the world, primarily in what's known as the "Coffee Belt" - the area between the Tropics of Cancer and Capricorn. The flavor characteristics of coffee beans are influenced by:
+
+- Geographic region and climate
+- Altitude
+- Soil composition
+- Variety of coffee plant
+- Processing method
+- Harvest and sorting practices
+
+## Observations
+
+- [principle] Higher altitude generally produces harder, denser beans with more complex acidity #altitude
+- [region] Ethiopian beans often feature bright, fruity notes with floral aromatics #ethiopia
+- [region] Colombian coffee typically offers balanced acidity with caramel sweetness and nutty undertones #colombia
+- [region] Guatemalan coffee presents complex acidity with chocolate notes and sometimes spice characteristics #guatemala
+- [region] Brazilian coffee tends toward nutty, chocolate notes with lower acidity and fuller body #brazil
+- [region] Kenyan coffee is known for bright, wine-like acidity and berry or citrus notes #kenya
+- [processing] Natural (dry) processing tends to create fruitier, more fermented flavors #processing
+- [processing] Washed (wet) processing generally results in cleaner, brighter cups with more clarity #processing
+- [processing] Honey processing creates a middle ground with some fruity notes while maintaining clarity #processing
+- [factor] Shade-grown coffee typically develops more slowly, resulting in more complex flavors #cultivation
+- [factor] Soil volcanic soil often imparts distinctive mineral characteristics to coffee #terroir
+- [variety] Gesha/Geisha variety is known for exceptional floral and tea-like qualities #varieties
+- [variety] Bourbon varieties often feature sweet, complex cup profiles #varieties
+- [variety] Robusta beans have higher caffeine content but generally less complex flavor than Arabica #varieties
+
+## Major Growing Regions
+
+- [africa] Ethiopian coffees: Yirgacheffe, Sidamo, Harrar regions each with distinctive profiles #ethiopia
+- [africa] Kenyan coffees: Often categorized by grade (AA, AB, etc.) based on bean size #kenya
+- [americas] Colombian regions: Huila, Nariño, Antioquia each with unique characteristics #colombia
+- [americas] Central American producers: Guatemala, Costa Rica, Panama known for balanced profiles #central_america
+- [americas] Brazilian regions: Cerrado, Sul de Minas, Mogiana with varying profiles #brazil
+- [asia] Indonesian islands: Sumatra, Java, Sulawesi producing earthy, full-bodied coffees #indonesia
+- [asia] Vietnamese coffee: World's largest Robusta producer, often used in blends and commercial coffee #vietnam
+
+## Processing Methods
+
+- [natural] Beans dried inside the fruit, creating fruity, fermented notes and heavier body #processing
+- [washed] Fruit removed before drying, resulting in cleaner cup with more pronounced acidity #processing
+- [honey] Some fruit mucilage left on during drying, creates balanced sweetness and body #processing
+- [wet-hulled] Unique to Indonesia, creates earthy, herbal, low-acid profiles #processing
+- [experimental] Anaerobic fermentation, wine-yeast inoculation, and other newer methods #innovation
+
+## Tasting Notes by Region
+
+- [ethiopia] Blueberry, jasmine, bergamot, stone fruit, citrus #flavor_notes
+- [kenya] Blackcurrant, tomato, tropical fruit, wine-like acidity #flavor_notes
+- [colombia] Caramel, nuts, red apple, chocolate, balanced acidity #flavor_notes
+- [guatemala] Chocolate, spice, green apple, balanced #flavor_notes
+- [brazil] Nuts, chocolate, low acidity, full body #flavor_notes
+- [indonesia] Earthy, herbal, spice, cedar, full body, low acidity #flavor_notes
+
+## Relations
+
+- influences [[Flavor Extraction]]
+- pairs_with [[Coffee Brewing Methods]]
+- affects [[Tasting Notes]]
+- relates_to [[Specialty Coffee]]
+- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Brewing Methods.md

@@ -0,0 +1,70 @@
+---
+title: Coffee Brewing Methods
+type: note
+permalink: coffee/coffee-brewing-methods
+tags:
+- '#coffee'
+- '#brewing'
+- '#methods'
+- '#demo'
+---
+
+# Coffee Brewing Methods
+
+An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction.
+
+## Overview
+
+Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans, resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are:
+
+- Grind size
+- Water temperature
+- Brew time
+- Coffee-to-water ratio
+- Agitation/turbulence
+
+## Observations
+
+- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction
+- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity
+- [method] Immersion methods like French press create fuller body and more rounded flavors #body
+- [technique] Water at 195-205°F (90-96°C) extracts optimal flavor compounds for most brewing methods #temperature
+- [technique] Grind size directly correlates with ideal extraction time (finer = shorter, coarser = longer) #grind
+- [preference] Medium-light roasts often showcase more origin characteristics in pour over methods #roast
+- [equipment] Burr grinders produce more consistent particle size than blade grinders, resulting in more even extraction #gear
+- [ratio] 1:15 to 1:17 coffee-to-water ratio (by weight) works well for most brew methods #brewing
+- [science] Different brewing temperatures extract different chemical compounds from the beans #chemistry
+- [technique] Bloom phase (pre-infusion with small amount of water) allows CO2 to escape and improves extraction #bloom
+
+## Pour Over Methods
+
+- [method] V60 produces very clean cup with excellent clarity of flavor #pourover
+- [method] Chemex uses thicker filter paper, resulting in even cleaner cup with fewer oils #pourover
+- [method] Kalita Wave provides more consistent extraction due to flat bottom design #pourover
+- [technique] Concentric circular pouring pattern ensures even saturation of grounds #technique
+- [timing] Most pour over methods complete in 2:30-3:30 total brew time #brewing
+
+## Immersion Methods
+
+- [method] French Press creates full-bodied cup with rich mouthfeel due to metal filter allowing oils to pass #immersion
+- [method] AeroPress is versatile, capable of producing both espresso-like and filter-style coffee #immersion
+- [method] Cold brew uses time instead of heat to extract, resulting in lower acidity #immersion
+- [technique] French press ideal steep time is 4-5 minutes before plunging #timing
+- [technique] AeroPress inverted method prevents dripping during extraction phase #technique
+
+## Pressure Methods
+
+- [method] Espresso uses 9 bars of pressure to force water through finely ground coffee #pressure
+- [method] Moka pot uses steam pressure to push water through grounds, creating strong, concentrated coffee #pressure
+- [technique] Espresso requires very fine grind, almost powder-like consistency #grind
+- [timing] Espresso shots typically extract in 25-30 seconds #timing
+- [principle] Pressure methods can extract compounds that aren't soluble in regular brewing methods #extraction
+
+## Relations
+
+- requires [[Proper Grinding Technique]]
+- affects [[Flavor Extraction]]
+- pairs_with [[Coffee Bean Origins]]
+- uses [[Brewing Equipment]]
+- influences [[Tasting Notes]]
+- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Flavor Map.md

@@ -0,0 +1,89 @@
+---
+title: Coffee Flavor Map
+type: note
+permalink: coffee/coffee-flavor-map
+tags:
+- '#coffee'
+- '#visualization'
+- '#canvas'
+- '#demo'
+---
+
+# Coffee Flavor Map
+
+A visual mapping of coffee flavor attributes, brewing methods, and their relationships. This note describes a canvas visualization that could be generated to demonstrate Basic Memory's visualization capabilities.
+
+## Overview
+
+The Coffee Flavor Map provides a visual representation of how different brewing methods, coffee origins, and equipment choices affect flavor outcomes. This canvas visualization helps users understand the complex relationships in coffee brewing and tasting.
+
+## Canvas Visualization Elements
+
+### Core Nodes
+- **Flavor Attributes**: Acidity, Sweetness, Body, Clarity, Bitterness, Complexity
+- **Brewing Methods**: Pour Over, French Press, AeroPress, Espresso, Moka Pot, Cold Brew
+- **Origin Regions**: Ethiopia, Kenya, Colombia, Brazil, Guatemala, Indonesia
+- **Equipment Elements**: Grinder Quality, Water Temperature, Brewing Device, Filter Type
+
+### Node Connections
+- Lines connecting brewing methods to their typical flavor outcomes
+- Arrows showing how equipment choices affect extraction variables
+- Connections between origins and their characteristic flavor profiles
+- Highlighting of optimal brewing methods for different origins
+
+### Visual Organization
+- Flavor outcomes in the center
+- Brewing methods on the left side
+- Origins on the right side
+- Equipment variables at the bottom
+- Color coding by category (methods, origins, equipment, flavors)
+
+## Using This Visualization
+
+### For Coffee Exploration
+- Identify which brewing methods might highlight the characteristics you prefer
+- See which origins naturally pair well with your preferred brewing method
+- Understand how equipment changes can modify flavor outcomes
+- Visualize the complex interplay between all coffee variables
+
+### As a Basic Memory Demo
+- Demonstrates Canvas visualization capabilities
+- Shows how relations can be visually mapped
+- Illustrates complex knowledge organization
+- Provides an intuitive way to navigate coffee knowledge
+
+## How To Generate This Canvas
+
+In a conversation with Claude, you could request:
+
+```
+Please create a canvas visualization mapping the relationships between coffee brewing methods, origins, and flavor outcomes. Show how different equipment and techniques influence extraction and resulting flavor profiles.
+```
+
+This would generate a `.canvas` file in your Basic Memory directory that could be opened with Obsidian for an interactive visualization of these coffee relationships.
+
+## Example Visualization Snippets
+
+### Pour Over Method Node
+- Connected to: High Clarity, Bright Acidity, Medium Body
+- Best pairs with: Ethiopian and Kenyan beans
+- Equipment dependencies: Gooseneck Kettle, Paper Filter, Burr Grinder
+
+### Ethiopian Coffee Node
+- Characteristic flavors: Floral, Fruity, Bright
+- Best brewing methods: Pour Over, AeroPress
+- Challenging with: French Press (loses clarity of delicate notes)
+
+### Grind Size Node
+- Affects: Extraction Rate, Flavor Balance
+- Fine grind increases: Extraction Speed, Surface Area
+- Coarse grind increases: Flow Rate, Reduces Bitter Compounds
+
+## Relations
+
+- visualizes [[Coffee Knowledge Base]]
+- relates_to [[Coffee Brewing Methods]]
+- relates_to [[Coffee Bean Origins]]
+- relates_to [[Flavor Extraction]]
+- relates_to [[Tasting Notes]]
+- demonstrates [[Canvas]]

examples/Coffee Notes/Coffee Knowledge Base.md

@@ -0,0 +1,73 @@
+---
+title: Coffee Knowledge Base
+type: note
+permalink: coffee/coffee-knowledge-base
+tags:
+- '#coffee'
+- '#index'
+- '#demo'
+- '#knowledge'
+---
+
+# Coffee Knowledge Base
+
+A comprehensive collection of coffee knowledge, from bean origins to brewing methods to tasting notes. This knowledge base demonstrates Basic Memory's ability to organize and connect information in a meaningful way.
+
+## Overview
+
+This Coffee Knowledge Base captures key information about coffee, structured with semantic observations and relations that connect different aspects of coffee knowledge. It serves as both a useful reference for coffee enthusiasts and a demonstration of how Basic Memory organizes information.
+
+## Key Topics
+
+### Core Coffee Knowledge
+
+- [[Coffee Brewing Methods]] - Different techniques for preparing coffee
+- [[Coffee Bean Origins]] - Where coffee comes from and how region affects flavor
+- [[Brewing Equipment]] - Tools and devices used to prepare coffee
+- [[Flavor Extraction]] - The science of dissolving flavor compounds from coffee
+- [[Tasting Notes]] - How to taste and describe coffee flavors
+
+### Brewing Techniques
+
+- Proper grinding is fundamental to good extraction
+- Water quality significantly impacts flavor
+- Different brewing methods highlight different characteristics
+- Time, temperature, and grind size are the key variables to control
+- Freshness of beans dramatically affects quality
+
+### Coffee Preferences
+
+- Light roasts preserve more origin characteristics and acidity
+- Dark roasts emphasize body and chocolatey/roasted flavors
+- Pour over methods highlight clarity and distinct flavor notes
+- Immersion methods create fuller body and rounded flavor
+- Personal preference matters more than "correctness"
+
+## Using This Knowledge Base
+
+### For Learning
+
+Use this knowledge base to:
+- Understand coffee fundamentals
+- Explore connections between brewing methods and flavor outcomes
+- Learn how different origins produce distinct flavor profiles
+- Discover how equipment affects the brewing process
+- Develop a vocabulary for describing coffee experiences
+
+### As a Demo
+
+This knowledge base demonstrates:
+- Semantic knowledge organization with categories and relations
+- Building connections between related concepts
+- Creating a navigable knowledge graph
+- Structuring information in a way both humans and AI assistants can understand
+- How Basic Memory enables persistent knowledge across conversations
+
+## Relations
+
+- contains [[Coffee Brewing Methods]]
+- contains [[Coffee Bean Origins]]
+- contains [[Brewing Equipment]]
+- contains [[Flavor Extraction]]
+- contains [[Tasting Notes]]
+- demonstrates [[Basic Memory Capabilities]]

examples/Coffee Notes/Flavor Extraction.md

@@ -0,0 +1,79 @@
+---
+title: Flavor Extraction
+type: note
+permalink: coffee/flavor-extraction
+tags:
+- '#coffee'
+- '#extraction'
+- '#brewing'
+- '#science'
+- '#demo'
+---
+
+# Flavor Extraction
+
+Understanding the science of coffee extraction, how different compounds dissolve at different rates, and how to control extraction to achieve desired flavor profiles.
+
+## Overview
+
+Coffee extraction is the process of dissolving flavor compounds from ground coffee into water. The science of extraction is key to producing a balanced, flavorful cup. Extraction is affected by numerous variables including grind size, water temperature, contact time, agitation, and pressure.
+
+## Observations
+
+- [science] Coffee contains over 1,000 aroma compounds and hundreds of flavor compounds #chemistry
+- [principle] Extraction occurs in a predictable sequence: acids → sugars → bitter compounds #extraction_order
+- [principle] Under-extraction results in sour, bright, thin coffee lacking sweetness and body #under_extraction
+- [principle] Over-extraction results in bitter, hollow, astringent flavors #over_extraction
+- [principle] The goal is typically balanced extraction (18-22% of coffee solubles dissolved) #balanced_extraction
+- [technique] Finer grind size increases extraction rate due to greater surface area #grind_size
+- [technique] Higher water temperature increases extraction rate and solubility of compounds #temperature
+- [technique] Longer contact time allows more complete extraction #brew_time
+- [technique] Agitation (stirring, turbulence) increases extraction rate by preventing saturation zones #agitation
+- [technique] Pressure (as in espresso) can extract compounds that aren't water-soluble at atmospheric pressure #pressure
+
+## Factors Affecting Extraction
+
+- [factor] Grind size: Finer = faster extraction, coarser = slower extraction #grind
+- [factor] Water temperature: Higher = faster extraction, lower = slower extraction #temperature
+- [factor] Contact time: Longer = more extraction, shorter = less extraction #time
+- [factor] Agitation: More = faster extraction, less = slower extraction #agitation
+- [factor] Coffee-to-water ratio: More coffee = lower extraction percentage #ratio
+- [factor] Water quality: Mineral content affects extraction of different compounds #water
+- [factor] Roast level: Darker roasts extract more easily than lighter roasts #roast
+- [factor] Bean density: Denser beans (typically high-altitude) require more effort to extract #density
+- [factor] Freshness: Freshly roasted coffee extracts differently than aged coffee #freshness
+- [factor] Brewing method: Different methods extract different compounds at different rates #method
+
+## Signs of Extraction Levels
+
+- [under] Sour, bright, lack of sweetness, thin body, quick finish #flavor
+- [under] Typically from: too coarse grind, too cool water, too short brew time #causes
+- [balanced] Sweet, bright but not sour, rich but not bitter, pleasing finish #flavor
+- [balanced] Achieved through proper ratio of variables for given coffee #technique
+- [over] Bitter, hollow, astringent, dry finish, sometimes papery #flavor
+- [over] Typically from: too fine grind, too hot water, too long brew time #causes
+
+## Measuring Extraction
+
+- [method] Total Dissolved Solids (TDS) meters measure concentration of coffee solution #measurement
+- [method] Extraction yield = percentage of coffee grounds dissolved in the final brew #calculation
+- [preference] Specialty coffee typically targets 18-22% extraction yield #standards
+- [preference] Some specialty light roasts may taste best at higher extraction percentages #speciality
+
+## Controlling Extraction
+
+- [technique] Adjust grind size as primary extraction control #basics
+- [technique] Use water temperature to fine-tune extraction #fine_tuning
+- [technique] Modify pour technique to control agitation level #technique
+- [technique] Adjust coffee-to-water ratio to balance strength and extraction #ratio
+- [technique] Pre-infusion (blooming) helps achieve even extraction #blooming
+- [technique] Pulse pouring creates different extraction dynamics than continuous pour #pour_technique
+
+## Relations
+
+- affected_by [[Coffee Brewing Methods]]
+- influenced_by [[Coffee Bean Origins]]
+- enhanced_by [[Brewing Equipment]]
+- determines [[Tasting Notes]]
+- requires [[Water Quality]]
+- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Perfect Pour Over Coffee Method.canvas

@@ -0,0 +1,161 @@
+{
+	"nodes":[
+		{
+			"id":"node-5",
+			"type":"text",
+			"text":"## Main Pour Phase\n- Use concentric circles from center outward\n- Maintain steady, controlled flow rate\n- Avoid pouring directly on filter walls\n- Keep water level consistent\n- Pulse pour in 2-3 stages (or continuous pour)\n- Total brew time target: 2:30-3:30",
+			"position":{"x":450,"y":200},
+			"x":530,
+			"y":-100,
+			"width":300,
+			"height":200,
+			"color":"1"
+		},
+		{
+			"id":"node-8",
+			"type":"text",
+			"text":"## Drawdown\n- Allow water to fully drain\n- Flat bed indicates even extraction\n- Total brew time should be ~2:30-3:30\n- Remove filter promptly after brewing",
+			"position":{"x":450,"y":700},
+			"x":540,
+			"y":375,
+			"width":300,
+			"height":150,
+			"color":"1"
+		},
+		{
+			"id":"node-6",
+			"type":"text",
+			"text":"## Pour Pattern\n\nConcentric circles ensure even saturation of coffee grounds. Begin at the center and work outward, avoiding filter edges. Pour height of 1-2 inches above coffee bed.",
+			"position":{"x":250,"y":450},
+			"x":960,
+			"y":25,
+			"width":300,
+			"height":150,
+			"color":"5"
+		},
+		{
+			"id":"node-12",
+			"type":"text",
+			"text":"## Tasting Notes\n\n- Balanced extraction: sweet, bright, complex\n- Under-extraction: sour, lacking sweetness\n- Over-extraction: bitter, astringent, hollow\n\nTake notes on each brew to track improvements and preferences.",
+			"position":{"x":-250,"y":700},
+			"x":1020,
+			"y":420,
+			"width":300,
+			"height":150,
+			"color":"6"
+		},
+		{
+			"id":"node-9",
+			"type":"text",
+			"text":"## Troubleshooting\n\n- Too sour/weak: Grind finer, water hotter, increase brew time\n- Too bitter/strong: Grind coarser, water cooler, decrease brew time\n- Uneven extraction: Improve pour technique, better grinder\n- Channeling: More careful pouring, better bloom\n- Slow drawdown: Coarser grind, less agitation\n- Fast drawdown: Finer grind, more careful pouring",
+			"position":{"x":100,"y":700},
+			"x":30,
+			"y":570,
+			"width":300,
+			"height":200,
+			"color":"6"
+		},
+		{
+			"id":"node-3",
+			"type":"text",
+			"text":"## Preparation\n- Heat water to 195-205°F (90-96°C)\n- Measure coffee (1:15 to 1:17 ratio)\n- Medium-fine grind (sea salt consistency)\n- Rinse filter with hot water\n- Discard rinse water\n- Add ground coffee to filter\n- Level coffee bed",
+			"position":{"x":-250,"y":200},
+			"x":30,
+			"y":-500,
+			"width":300,
+			"height":200,
+			"color":"3"
+		},
+		{
+			"id":"node-1",
+			"type":"text",
+			"text":"# Perfect Pour Over Method\n\nA systematic approach to brewing exceptional pour over coffee by controlling key variables and following proper technique.",
+			"position":{"x":0,"y":0},
+			"x":-580,
+			"y":-760,
+			"width":400,
+			"height":120,
+			"color":"4"
+		},
+		{
+			"id":"node-10",
+			"type":"text",
+			"text":"## Grinding Parameters\n\n- V60: Medium-fine (sea salt)\n- Chemex: Medium (slightly coarser than V60)\n- Kalita Wave: Medium (between V60 and Chemex)\n\nConsistent particle size is critical; use quality burr grinder.",
+			"position":{"x":-250,"y":450},
+			"x":30,
+			"y":-910,
+			"width":300,
+			"height":150,
+			"color":"5"
+		},
+		{
+			"id":"node-2",
+			"type":"text",
+			"text":"## Equipment Setup\n- Clean V60/Chemex/Kalita Wave\n- Paper filter (rinsed)\n- Server/mug\n- Scale with timer\n- Gooseneck kettle\n- Burr grinder\n- Fresh coffee beans",
+			"position":{"x":-600,"y":200},
+			"x":-530,
+			"y":-500,
+			"width":300,
+			"height":200,
+			"color":"3"
+		},
+		{
+			"id":"node-4",
+			"type":"text",
+			"text":"## The Bloom\n- Start timer\n- Pour 2-3x coffee weight water\n- Ensure all grounds are saturated\n- Gentle stir or swirl if needed\n- Allow 30-45 seconds for degassing\n- Look for bubbling and dome formation",
+			"position":{"x":100,"y":200},
+			"x":530,
+			"y":-500,
+			"width":300,
+			"height":200,
+			"color":"1"
+		},
+		{
+			"id":"node-13",
+			"type":"text",
+			"text":"## Coffee-to-Water Ratio\n\n- Standard: 1:15 to 1:17 (coffee:water)\n- Stronger cup: 1:15 (67g/L)\n- Medium cup: 1:16 (62.5g/L)\n- Lighter cup: 1:17 (58.8g/L)\n\nExample: For 300ml water, use ~18-20g coffee",
+			"position":{"x":-600,"y":700},
+			"x":30,
+			"y":-100,
+			"width":300,
+			"height":150,
+			"color":"6"
+		},
+		{
+			"id":"node-7",
+			"type":"text",
+			"text":"## Brew Time Guideline\n\n- Bloom: 30-45 seconds\n- First pour: 1:00-1:15\n- Second pour: 1:45-2:00\n- Final pour: 2:15-2:30\n- Drawdown complete: 2:45-3:30\n\nAdjust for taste: shorter for lighter, longer for stronger",
+			"position":{"x":600,"y":450},
+			"x":-80,
+			"y":220,
+			"width":300,
+			"height":200,
+			"color":"5"
+		},
+		{
+			"id":"node-11",
+			"type":"text",
+			"text":"## Water Quality\n\n- Clean, filtered water\n- No strong odors or flavors\n- Ideal TDS: 75-150 ppm\n- Ideal pH: 7.0-7.5\n- Avoid distilled water (lacks minerals)\n- Avoid hard water (scaling issues)",
+			"position":{"x":-600,"y":450},
+			"x":-780,
+			"y":-125,
+			"width":300,
+			"height":150,
+			"color":"5"
+		}
+	],
+	"edges":[
+		{"id":"edge-1","fromNode":"node-1","fromSide":"bottom","toNode":"node-2","toSide":"top","label":"Step 1"},
+		{"id":"edge-2","fromNode":"node-2","fromSide":"right","toNode":"node-3","toSide":"left","label":"Step 2"},
+		{"id":"edge-3","fromNode":"node-3","fromSide":"right","toNode":"node-4","toSide":"left","label":"Step 3"},
+		{"id":"edge-4","fromNode":"node-4","fromSide":"bottom","toNode":"node-5","toSide":"top","label":"Step 4"},
+		{"id":"edge-5","fromNode":"node-5","fromSide":"bottom","toNode":"node-8","toSide":"top","label":"Step 5"},
+		{"id":"edge-6","fromNode":"node-5","fromSide":"left","toNode":"node-7","toSide":"right","label":"Timing"},
+		{"id":"edge-7","fromNode":"node-5","fromSide":"right","toNode":"node-6","toSide":"left","label":"Technique"},
+		{"id":"edge-8","fromNode":"node-8","fromSide":"left","toNode":"node-9","toSide":"right","label":"if problems"},
+		{"id":"edge-9","fromNode":"node-3","fromSide":"top","toNode":"node-10","toSide":"bottom","label":"Grinding details"},
+		{"id":"edge-10","fromNode":"node-2","fromSide":"bottom","toNode":"node-11","toSide":"right","label":"Water details"},
+		{"id":"edge-11","fromNode":"node-8","fromSide":"right","toNode":"node-12","toSide":"left","label":"Evaluate"},
+		{"id":"edge-12","fromNode":"node-3","fromSide":"bottom","toNode":"node-13","toSide":"top","label":"Ratio details"}
+	]
+}

examples/Coffee Notes/Tasting Notes.md

@@ -0,0 +1,84 @@
+---
+title: Tasting Notes
+type: note
+permalink: coffee/tasting-notes
+tags:
+- '#coffee'
+- '#tasting'
+- '#flavor'
+- '#cupping'
+- '#demo'
+---
+
+# Tasting Notes
+
+How to taste and evaluate coffee, identify flavor characteristics, and develop a personal coffee palate.
+
+## Overview
+
+Coffee tasting, or "cupping" in professional contexts, is the practice of observing the tastes and aromas of brewed coffee. Developing a coffee palate helps identify preferences, communicate about coffee experiences, and better understand how brewing variables affect the cup.
+
+## Observations
+
+- [principle] Flavor perception includes taste, aroma, mouthfeel, and retronasal perception #sensory
+- [principle] Our taste buds can only perceive sweet, sour, salty, bitter, and umami #taste
+- [principle] Most of what we call "flavor" is actually aroma detected retronasally #aroma
+- [technique] Professional coffee tasting (cupping) uses a standardized protocol for consistency #cupping
+- [technique] Slurping coffee aerates it and spreads it across all taste receptors #technique
+- [technique] Allowing coffee to cool reveals different flavor notes at different temperatures #temperature
+
+## Coffee Flavor Wheel
+
+- [tool] The SCA Coffee Flavor Wheel provides a standardized vocabulary for describing coffee #flavor_wheel
+- [category] Primary categories include: Fruity, Floral, Sweet, Nutty/Cocoa, Spice, Roasted, Other #categories
+- [subcategory] Fruity breaks down into: Berry, Dried Fruit, Citrus Fruit, Stone Fruit, Tropical Fruit, etc. #fruit_notes
+- [subcategory] Floral includes: Floral, Black Tea, Chamomile, Rose, Jasmine, etc. #floral_notes
+- [subcategory] Sweet includes: Brown Sugar, Molasses, Honey, Maple Syrup, Vanilla, etc. #sweet_notes
+- [subcategory] Nutty/Cocoa includes: Nut, Cocoa, Dark Chocolate, Chocolate, etc. #nutty_notes
+- [subcategory] Spice includes: Brown Spice, Pepper, Anise, Nutmeg, Cinnamon, etc. #spice_notes
+
+## Basic Tasting Components
+
+- [component] Acidity: The bright, tangy quality (not sourness from under-extraction) #acidity
+- [component] Sweetness: The pleasant, sugary quality balancing other elements #sweetness
+- [component] Body: The physical mouthfeel and weight of the coffee #body
+- [component] Finish/Aftertaste: The flavor that lingers after swallowing #finish
+- [component] Balance: How well all elements work together #balance
+- [component] Complexity: The range and layers of distinct flavors #complexity
+- [component] Cleanliness: Absence of defects or off-flavors #cleanliness
+
+## Common Flavor Notes by Origin
+
+- [ethiopia] Blueberry, jasmine, bergamot, lemon, tea-like #flavor_notes
+- [kenya] Blackcurrant, grapefruit, tomato-like acidity, winey #flavor_notes
+- [colombia] Caramel, red apple, nuts, chocolate, balanced acidity #flavor_notes
+- [guatemala] Chocolate, spice, apple, medium acidity #flavor_notes
+- [brazil] Nuts, chocolate, low-to-medium acidity, full body #flavor_notes
+- [indonesia] Earthy, herbal, spice, cedar, full body, low acidity #flavor_notes
+- [costa_rica] Clean, bright, citrus, balanced, light chocolate #flavor_notes
+
+## Developing Your Palate
+
+- [technique] Taste coffees side-by-side to identify differences #comparison
+- [technique] Try describing flavors before looking at roaster's notes #blind_tasting
+- [technique] Keep a coffee journal with detailed notes about each coffee #journaling
+- [technique] Explore different processing methods of the same origin #processing
+- [technique] Try the same coffee brewed with different methods #brewing_comparison
+- [technique] Use reference flavors (actual fruits, chocolates, etc.) to calibrate your palate #calibration
+
+## Personal Coffee Experiences
+
+- [experience] Ethiopian Yirgacheffe prepared as pour over: intense blueberry, jasmine aromatics, tea-like body
+- [experience] Sumatra Mandheling in French press: earthy, cedar, herbal, tobacco, full body
+- [experience] Panama Gesha as pour over: intense floral notes, jasmine, bergamot, delicate body
+- [experience] Brazil Cerrado as espresso: nutty, chocolate, caramel, low acidity, great crema
+- [experience] Kenya AA as pour over: bright blackcurrant, tomato-like acidity, winey finish
+
+## Relations
+
+- determined_by [[Flavor Extraction]]
+- influenced_by [[Coffee Bean Origins]]
+- varies_with [[Coffee Brewing Methods]]
+- enhanced_by [[Proper Grinding Technique]]
+- documented_in [[Coffee Journal]]
+- part_of [[Coffee Knowledge Base]]

installer/README.md

@@ -7,10 +7,20 @@ This installer configures Basic Memory to work with Claude Desktop.
 1. Download the latest installer from the [releases page](https://github.com/basicmachines-co/basic-memory/releases)
 2. Unzip the downloaded file
 3. Since the app is currently unsigned, you'll need to:
-   - Right-click (or Control-click) the app
-   - Select "Open" from the context menu
-   - Click "Open" in the warning dialog
-4. Follow the installation instructions
+
+   On your Mac, choose Apple menu  > System Settings, then click Privacy & Security in the sidebar. (You may need to
+   scroll down.)
+
+   Go to Security, then click Open.
+
+   Click Open Anyway.
+
+   This button is available for about an hour after you try to open the app.
+
+   Enter your login password, then click OK.
+
+   https://support.apple.com/guide/mac-help/apple-cant-check-app-for-malicious-software-mchleab3a043/mac
+
 5. Restart Claude Desktop
 
-The warning only appears the first time you open the app. Future updates will include proper code signing.
+The warning only appears the first time you open the app. Future updates will include proper code signing.

installer/installer.py

@@ -8,6 +8,7 @@ if sys.platform == "darwin":
     import tkinter as tk
     from tkinter import messagebox
 
+
 def ensure_uv_installed():
     """Check if uv is installed, install if not."""
     try:
@@ -43,12 +44,15 @@ def update_claude_config():
 
     # Load existing config or create new
     if config_path.exists():
-        config = json.loads(config_path.read_text())
+        config = json.loads(config_path.read_text(encoding="utf-8"))
     else:
         config = {"mcpServers": {}}
 
     # Add/update basic-memory config
-    config["mcpServers"]["basic-memory"] = {"command": "uvx", "args": ["basic-memory", "mcp"]}
+    config["mcpServers"]["basic-memory"] = {
+        "command": "uvx",
+        "args": ["basic-memory@latest", "mcp"],
+    }
 
     # Write back config
     config_path.write_text(json.dumps(config, indent=2))

installer/setup.py

@@ -4,38 +4,24 @@ import sys
 # Build options for all platforms
 build_exe_options = {
     "packages": ["json", "pathlib"],
-    "excludes": [
-        "tkinter",
-        "unittest", 
-        "email",
-        "html",
-        "http",
-        "xml",
-        "pydoc",
-        "_tkinter",
-        "test"
-    ],
-    "include_msvcr": False,
+    "excludes": ["unittest", "pydoc", "test"],
 }
 
 # Platform-specific options
 if sys.platform == "win32":
     base = "Win32GUI"  # Use GUI base for Windows
-    build_exe_options.update({
-        "include_msvcr": True,  # Include Visual C++ runtime
-    })
+    build_exe_options.update(
+        {
+            "include_msvcr": True,
+        }
+    )
     target_name = "Basic Memory Installer.exe"
 else:  # darwin
     base = None  # Don't use GUI base for macOS
     target_name = "Basic Memory Installer"
 
 executables = [
-    Executable(
-        script="installer.py",
-        target_name=target_name,
-        base=base,
-        icon="Basic.icns"
-    )
+    Executable(script="installer.py", target_name=target_name, base=base, icon="Basic.icns")
 ]
 
 setup(
@@ -46,8 +32,9 @@ setup(
         "build_exe": build_exe_options,
         "bdist_mac": {
             "bundle_name": "Basic Memory Installer",
-            "iconfile": "Basic.icns"
-        }
+            "iconfile": "Basic.icns",
+            "codesign_identity": "-",  # Force ad-hoc signing
+        },
     },
     executables=executables,
-)
+)

llms-install.md

@@ -0,0 +1,128 @@
+# Basic Memory Installation Guide for LLMs
+
+This guide is specifically designed to help AI assistants like Cline install and configure Basic Memory. Follow these
+steps in order.
+
+## Installation Steps
+
+### 1. Install Basic Memory Package
+
+Use one of the following package managers to install:
+
+```bash
+# Install with uv (recommended)
+uv tool install basic-memory
+
+# Or with pip
+pip install basic-memory
+```
+
+### 2. Configure MCP Server
+
+Add the following to your config:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+For Claude Desktop, this file is located at:
+
+macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+Windows: %APPDATA%\Claude\claude_desktop_config.json
+
+### 3. Start Synchronization (optional)
+
+To synchronize files in real-time, run:
+
+```bash
+basic-memory sync --watch
+```
+
+Or for a one-time sync:
+
+```bash
+basic-memory sync
+```
+
+## Configuration Options
+
+### Custom Directory
+
+To use a directory other than the default `~/basic-memory`:
+
+```bash
+basic-memory project add custom-project /path/to/your/directory
+basic-memory project default custom-project
+```
+
+### Multiple Projects
+
+To manage multiple knowledge bases:
+
+```bash
+# List all projects
+basic-memory project list
+
+# Add a new project
+basic-memory project add work ~/work-basic-memory
+
+# Set default project
+basic-memory project default work
+```
+
+## Importing Existing Data
+
+### From Claude.ai
+
+```bash
+basic-memory import claude conversations path/to/conversations.json
+basic-memory import claude projects path/to/projects.json
+```
+
+### From ChatGPT
+
+```bash
+basic-memory import chatgpt path/to/conversations.json
+```
+
+### From MCP Memory Server
+
+```bash
+basic-memory import memory-json path/to/memory.json
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check that Basic Memory is properly installed:
+   ```bash
+   basic-memory --version
+   ```
+
+2. Verify the sync process is running:
+   ```bash
+   ps aux | grep basic-memory
+   ```
+
+3. Check sync output for errors:
+   ```bash
+   basic-memory sync --verbose
+   ```
+
+4. Check log output:
+   ```bash
+   cat ~/.basic-memory/basic-memory.log
+   ```
+
+For more detailed information, refer to the [full documentation](https://memory.basicmachines.co/).

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.2.8"
+version = "0.12.3"
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"
@@ -29,6 +29,7 @@ dependencies = [
     "fastapi[standard]>=0.115.8",
     "alembic>=1.14.1",
     "qasync>=0.27.1",
+    "pillow>=11.1.0",
 ]
 
 
@@ -39,6 +40,7 @@ Documentation = "https://github.com/basicmachines-co/basic-memory#readme"
 
 [project.scripts]
 basic-memory = "basic_memory.cli.main:app"
+bm = "basic_memory.cli.main:app"
 
 [build-system]
 requires = ["hatchling"]
@@ -84,7 +86,9 @@ pythonVersion = "3.12"
 
 
 [tool.semantic_release]
-version_variable = "src/basic_memory/__init__.py:__version__"
+version_variables = [
+    "src/basic_memory/__init__.py:__version__",
+]
 version_toml = [
     "pyproject.toml:project.version",
 ]
@@ -98,3 +102,6 @@ commit_message = "chore(release): {version} [skip ci]"
 
 [tool.coverage.run]
 concurrency = ["thread", "gevent"]
+
+[tool.logfire]
+ignore_no_config = true

smithery.yaml

@@ -0,0 +1,15 @@
+# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
+
+startCommand:
+  type: stdio
+  configSchema:
+    # JSON Schema defining the configuration options for the MCP.
+    type: object
+    properties: {}
+    description: No configuration required. This MCP server runs using the default command.
+  commandFunction: |-
+    (config) => ({
+      command: 'basic-memory',
+      args: ['mcp']
+    })
+  exampleConfig: {}

src/basic_memory/__init__.py

@@ -1,3 +1,3 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-__version__ = "0.0.1"
+__version__ = "0.12.3"

src/basic_memory/alembic/README

@@ -1 +0,0 @@
-Generic single-database configuration.

src/basic_memory/alembic/alembic.ini

@@ -3,7 +3,7 @@
 [alembic]
 # path to migration scripts
 # Use forward slashes (/) also on windows to provide an os agnostic path
-script_location = src/basic_memory/alembic
+script_location = .
 
 # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
 # Uncomment the line below if you want the files to be prepended with date and time

src/basic_memory/alembic/env.py

@@ -1,5 +1,6 @@
 """Alembic environment configuration."""
 
+import os
 from logging.config import fileConfig
 
 from sqlalchemy import engine_from_config
@@ -8,6 +9,10 @@ from sqlalchemy import pool
 from alembic import context
 
 from basic_memory.models import Base
+
+# set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
+os.environ["BASIC_MEMORY_ENV"] = "test"
+
 from basic_memory.config import config as app_config
 
 # this is the Alembic Config object, which provides
@@ -18,6 +23,8 @@ config = context.config
 sqlalchemy_url = f"sqlite:///{app_config.database_path}"
 config.set_main_option("sqlalchemy.url", sqlalchemy_url)
 
+# print(f"Using SQLAlchemy URL: {sqlalchemy_url}")
+
 # Interpret the config file for Python logging.
 if config.config_file_name is not None:
     fileConfig(config.config_file_name)
@@ -27,6 +34,14 @@ if config.config_file_name is not None:
 target_metadata = Base.metadata
 
 
+# Add this function to tell Alembic what to include/exclude
+def include_object(object, name, type_, reflected, compare_to):
+    # Ignore SQLite FTS tables
+    if type_ == "table" and name.startswith("search_index"):
+        return False
+    return True
+
+
 def run_migrations_offline() -> None:
     """Run migrations in 'offline' mode.
 
@@ -44,6 +59,8 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        include_object=include_object,
+        render_as_batch=True,
     )
 
     with context.begin_transaction():
@@ -63,7 +80,12 @@ def run_migrations_online() -> None:
     )
 
     with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            include_object=include_object,
+            render_as_batch=True,
+        )
 
         with context.begin_transaction():
             context.run_migrations()

src/basic_memory/alembic/migrations.py

@@ -1,6 +1,5 @@
 """Functions for managing database migrations."""
 
-import asyncio
 from pathlib import Path
 from loguru import logger
 from alembic.config import Config
@@ -10,20 +9,16 @@ from alembic import command
 def get_alembic_config() -> Config:  # pragma: no cover
     """Get alembic config with correct paths."""
     migrations_path = Path(__file__).parent
-    alembic_ini = migrations_path.parent.parent.parent / "alembic.ini"
+    alembic_ini = migrations_path / "alembic.ini"
 
     config = Config(alembic_ini)
     config.set_main_option("script_location", str(migrations_path))
     return config
 
 
-async def reset_database():  # pragma: no cover
+def reset_database():  # pragma: no cover
     """Drop and recreate all tables."""
     logger.info("Resetting database...")
     config = get_alembic_config()
-
-    def _reset(cfg):
-        command.downgrade(cfg, "base")
-        command.upgrade(cfg, "head")
-
-    await asyncio.get_event_loop().run_in_executor(None, _reset, config)
+    command.downgrade(config, "base")
+    command.upgrade(config, "head")

src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py

@@ -0,0 +1,51 @@
+"""remove required from entity.permalink
+
+Revision ID: 502b60eaa905
+Revises: b3c3938bacdb
+Create Date: 2025-02-24 13:33:09.790951
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "502b60eaa905"
+down_revision: Union[str, None] = "b3c3938bacdb"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=True)
+        batch_op.drop_index("ix_entity_permalink")
+        batch_op.create_index(batch_op.f("ix_entity_permalink"), ["permalink"], unique=False)
+        batch_op.drop_constraint("uix_entity_permalink", type_="unique")
+        batch_op.create_index(
+            "uix_entity_permalink",
+            ["permalink"],
+            unique=True,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.drop_index(
+            "uix_entity_permalink",
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.create_unique_constraint("uix_entity_permalink", ["permalink"])
+        batch_op.drop_index(batch_op.f("ix_entity_permalink"))
+        batch_op.create_index("ix_entity_permalink", ["permalink"], unique=1)
+        batch_op.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=False)
+
+    # ### end Alembic commands ###

src/basic_memory/alembic/versions/b3c3938bacdb_relation_to_name_unique_index.py

@@ -0,0 +1,44 @@
+"""relation to_name unique index
+
+Revision ID: b3c3938bacdb
+Revises: 3dae7c7b1564
+Create Date: 2025-02-22 14:59:30.668466
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "b3c3938bacdb"
+down_revision: Union[str, None] = "3dae7c7b1564"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # SQLite doesn't support constraint changes through ALTER
+    # Need to recreate table with desired constraints
+    with op.batch_alter_table("relation") as batch_op:
+        # Drop existing unique constraint
+        batch_op.drop_constraint("uix_relation", type_="unique")
+
+        # Add new constraints
+        batch_op.create_unique_constraint(
+            "uix_relation_from_id_to_id", ["from_id", "to_id", "relation_type"]
+        )
+        batch_op.create_unique_constraint(
+            "uix_relation_from_id_to_name", ["from_id", "to_name", "relation_type"]
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("relation") as batch_op:
+        # Drop new constraints
+        batch_op.drop_constraint("uix_relation_from_id_to_name", type_="unique")
+        batch_op.drop_constraint("uix_relation_from_id_to_id", type_="unique")
+
+        # Restore original constraint
+        batch_op.create_unique_constraint("uix_relation", ["from_id", "to_id", "relation_type"])

src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py

@@ -0,0 +1,106 @@
+"""Update search index schema
+
+Revision ID: cc7172b46608
+Revises: 502b60eaa905
+Create Date: 2025-02-28 18:48:23.244941
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "cc7172b46608"
+down_revision: Union[str, None] = "502b60eaa905"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade database schema to use new search index with content_stems and content_snippet."""
+
+    # First, drop the existing search_index table
+    op.execute("DROP TABLE IF EXISTS search_index")
+
+    # Create new search_index with updated schema
+    op.execute("""
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+        -- Core entity fields
+        id UNINDEXED,          -- Row ID
+        title,                 -- Title for searching
+        content_stems,         -- Main searchable content split into stems
+        content_snippet,       -- File content snippet for display
+        permalink,             -- Stable identifier (now indexed for path search)
+        file_path UNINDEXED,   -- Physical location
+        type UNINDEXED,        -- entity/relation/observation
+        
+        -- Relation fields 
+        from_id UNINDEXED,     -- Source entity
+        to_id UNINDEXED,       -- Target entity
+        relation_type UNINDEXED, -- Type of relation
+        
+        -- Observation fields
+        entity_id UNINDEXED,   -- Parent entity
+        category UNINDEXED,    -- Observation category
+        
+        -- Common fields
+        metadata UNINDEXED,    -- JSON metadata
+        created_at UNINDEXED,  -- Creation timestamp
+        updated_at UNINDEXED,  -- Last update
+        
+        -- Configuration
+        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
+        prefix='1,2,3,4'                    -- Support longer prefixes for paths
+    );
+    """)
+
+    # Print instruction to manually reindex after migration
+    print("\n------------------------------------------------------------------")
+    print("IMPORTANT: After migration completes, manually run the reindex command:")
+    print("basic-memory sync")
+    print("------------------------------------------------------------------\n")
+
+
+def downgrade() -> None:
+    """Downgrade database schema to use old search index."""
+    # Drop the updated search_index table
+    op.execute("DROP TABLE IF EXISTS search_index")
+
+    # Recreate the original search_index schema
+    op.execute("""
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+        -- Core entity fields
+        id UNINDEXED,          -- Row ID
+        title,                 -- Title for searching
+        content,               -- Main searchable content
+        permalink,             -- Stable identifier (now indexed for path search)
+        file_path UNINDEXED,   -- Physical location
+        type UNINDEXED,        -- entity/relation/observation
+        
+        -- Relation fields 
+        from_id UNINDEXED,     -- Source entity
+        to_id UNINDEXED,       -- Target entity
+        relation_type UNINDEXED, -- Type of relation
+        
+        -- Observation fields
+        entity_id UNINDEXED,   -- Parent entity
+        category UNINDEXED,    -- Observation category
+        
+        -- Common fields
+        metadata UNINDEXED,    -- JSON metadata
+        created_at UNINDEXED,  -- Creation timestamp
+        updated_at UNINDEXED,  -- Last update
+        
+        -- Configuration
+        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
+        prefix='1,2,3,4'                    -- Support longer prefixes for paths
+    );
+    """)
+
+    # Print instruction to manually reindex after migration
+    print("\n------------------------------------------------------------------")
+    print("IMPORTANT: After downgrade completes, manually run the reindex command:")
+    print("basic-memory sync")
+    print("------------------------------------------------------------------\n")

src/basic_memory/api/app.py

@@ -7,39 +7,24 @@ from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
 from basic_memory import db
-from basic_memory.config import config as app_config
-from basic_memory.api.routers import knowledge, search, memory, resource
-from alembic import command
-from alembic.config import Config
-
-from basic_memory.db import DatabaseType
-from basic_memory.repository.search_repository import SearchRepository
-
-
-async def run_migrations():  # pragma: no cover
-    """Run any pending alembic migrations."""
-    logger.info("Running database migrations...")
-    try:
-        config = Config("alembic.ini")
-        command.upgrade(config, "head")
-        logger.info("Migrations completed successfully")
-
-        _, session_maker = await db.get_or_create_db(
-            app_config.database_path, DatabaseType.FILESYSTEM
-        )
-        await SearchRepository(session_maker).init_search_index()
-    except Exception as e:
-        logger.error(f"Error running migrations: {e}")
-        raise
+from basic_memory.api.routers import knowledge, memory, project_info, resource, search
+from basic_memory.config import config as project_config
+from basic_memory.services.initialization import initialize_app
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
-    logger.info("Starting Basic Memory API")
-    await run_migrations()
+    # Initialize database and file sync services
+    watch_task = await initialize_app(project_config)
+
+    # proceed with startup
     yield
+
     logger.info("Shutting down Basic Memory API")
+    if watch_task:
+        watch_task.cancel()
+
     await db.shutdown_db()
 
 
@@ -51,16 +36,24 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+
 # Include routers
 app.include_router(knowledge.router)
 app.include_router(search.router)
 app.include_router(memory.router)
 app.include_router(resource.router)
+app.include_router(project_info.router)
 
 
 @app.exception_handler(Exception)
 async def exception_handler(request, exc):  # pragma: no cover
     logger.exception(
-        f"An unhandled exception occurred for request '{request.url}', exception: {exc}"
+        "API unhandled exception",
+        url=str(request.url),
+        method=request.method,
+        client=request.client.host if request.client else None,
+        path=request.url.path,
+        error_type=type(exc).__name__,
+        error=str(exc),
     )
     return await http_exception_handler(request, HTTPException(status_code=500, detail=str(exc)))

src/basic_memory/api/routers/__init__.py

@@ -4,5 +4,6 @@ from . import knowledge_router as knowledge
 from . import memory_router as memory
 from . import resource_router as resource
 from . import search_router as search
+from . import project_info_router as project_info
 
-__all__ = ["knowledge", "memory", "resource", "search"]
+__all__ = ["knowledge", "memory", "resource", "search", "project_info"]

src/basic_memory/api/routers/knowledge_router.py

@@ -33,7 +33,9 @@ async def create_entity(
     search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create an entity."""
-    logger.info(f"request: create_entity with data={data}")
+    logger.info(
+        "API request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
+    )
 
     entity = await entity_service.create_entity(data)
 
@@ -41,7 +43,13 @@ async def create_entity(
     await search_service.index_entity(entity, background_tasks=background_tasks)
     result = EntityResponse.model_validate(entity)
 
-    logger.info(f"response: create_entity with result={result}")
+    logger.info(
+        "API response",
+        endpoint="create_entity",
+        title=result.title,
+        permalink=result.permalink,
+        status_code=201,
+    )
     return result
 
 
@@ -55,10 +63,23 @@ async def create_or_update_entity(
     search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create or update an entity. If entity exists, it will be updated, otherwise created."""
-    logger.info(f"request: create_or_update_entity with permalink={permalink}, data={data}")
+    logger.info(
+        "API request",
+        endpoint="create_or_update_entity",
+        permalink=permalink,
+        entity_type=data.entity_type,
+        title=data.title,
+    )
 
     # Validate permalink matches
     if data.permalink != permalink:
+        logger.warning(
+            "API validation error",
+            endpoint="create_or_update_entity",
+            permalink=permalink,
+            data_permalink=data.permalink,
+            error="Permalink mismatch",
+        )
         raise HTTPException(status_code=400, detail="Entity permalink must match URL path")
 
     # Try create_or_update operation
@@ -70,7 +91,12 @@ async def create_or_update_entity(
     result = EntityResponse.model_validate(entity)
 
     logger.info(
-        f"response: create_or_update_entity with result={result}, status_code={response.status_code}"
+        "API response",
+        endpoint="create_or_update_entity",
+        title=result.title,
+        permalink=result.permalink,
+        created=created,
+        status_code=response.status_code,
     )
     return result
 
@@ -94,11 +120,8 @@ async def get_entity(
     try:
         entity = await entity_service.get_by_permalink(permalink)
         result = EntityResponse.model_validate(entity)
-
-        logger.info(f"response: get_entity with result={result}")
         return result
     except EntityNotFoundError:
-        logger.error(f"Error: Entity with {permalink} not found")
         raise HTTPException(status_code=404, detail=f"Entity with {permalink} not found")
 
 
@@ -114,8 +137,6 @@ async def get_entities(
     result = EntityListResponse(
         entities=[EntityResponse.model_validate(entity) for entity in entities]
     )
-
-    logger.info(f"response: get_entities with result={result}")
     return result
 
 
@@ -135,17 +156,15 @@ async def delete_entity(
 
     entity = await link_resolver.resolve_link(identifier)
     if entity is None:
-        logger.info("response: delete_entity with result=DeleteEntitiesResponse(deleted=False)")
         return DeleteEntitiesResponse(deleted=False)
 
     # Delete the entity
-    deleted = await entity_service.delete_entity(entity.permalink)
+    deleted = await entity_service.delete_entity(entity.permalink or entity.id)
 
     # Remove from search index
     background_tasks.add_task(search_service.delete_by_permalink, entity.permalink)
 
     result = DeleteEntitiesResponse(deleted=deleted)
-    logger.info(f"response: delete_entity with result={result}")
     return result
 
 
@@ -166,5 +185,4 @@ async def delete_entities(
         background_tasks.add_task(search_service.delete_by_permalink, permalink)
 
     result = DeleteEntitiesResponse(deleted=deleted)
-    logger.info(f"response: delete_entities with result={result}")
     return result

src/basic_memory/api/routers/memory_router.py

@@ -24,39 +24,38 @@ from basic_memory.services.context_service import ContextResultRow
 router = APIRouter(prefix="/memory", tags=["memory"])
 
 
-async def to_graph_context(context, entity_repository: EntityRepository):
+async def to_graph_context(context, entity_repository: EntityRepository, page: int, page_size: int):
     # return results
     async def to_summary(item: SearchIndexRow | ContextResultRow):
         match item.type:
             case SearchItemType.ENTITY:
-                assert item.title is not None
-                assert item.created_at is not None
-
                 return EntitySummary(
-                    title=item.title,
+                    title=item.title,  # pyright: ignore
                     permalink=item.permalink,
+                    content=item.content,
                     file_path=item.file_path,
                     created_at=item.created_at,
                 )
             case SearchItemType.OBSERVATION:
-                assert item.category is not None
-                assert item.content is not None
-
                 return ObservationSummary(
-                    category=item.category, content=item.content, permalink=item.permalink
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    category=item.category,  # pyright: ignore
+                    content=item.content,  # pyright: ignore
+                    permalink=item.permalink,  # pyright: ignore
+                    created_at=item.created_at,
                 )
             case SearchItemType.RELATION:
-                assert item.from_id is not None
-                from_entity = await entity_repository.find_by_id(item.from_id)
-                assert from_entity is not None
-
+                from_entity = await entity_repository.find_by_id(item.from_id)  # pyright: ignore
                 to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
-
                 return RelationSummary(
-                    permalink=item.permalink,
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    permalink=item.permalink,  # pyright: ignore
                     relation_type=item.type,
-                    from_id=from_entity.permalink,
-                    to_id=to_entity.permalink if to_entity else None,
+                    from_entity=from_entity.permalink,  # pyright: ignore
+                    to_entity=to_entity.permalink if to_entity else None,
+                    created_at=item.created_at,
                 )
             case _:  # pragma: no cover
                 raise ValueError(f"Unexpected type: {item.type}")
@@ -66,7 +65,11 @@ async def to_graph_context(context, entity_repository: EntityRepository):
     metadata = MemoryMetadata.model_validate(context["metadata"])
     # Transform to GraphContext
     return GraphContext(
-        primary_results=primary_results, related_results=related_results, metadata=metadata
+        primary_results=primary_results,
+        related_results=related_results,
+        metadata=metadata,
+        page=page,
+        page_size=page_size,
     )
 
 
@@ -77,7 +80,9 @@ async def recent(
     type: Annotated[list[SearchItemType] | None, Query()] = None,
     depth: int = 1,
     timeframe: TimeFrame = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     # return all types by default
     types = (
@@ -87,16 +92,22 @@ async def recent(
     )
 
     logger.debug(
-        f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+        f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
     )
     # Parse timeframe
     since = parse(timeframe)
+    limit = page_size
+    offset = (page - 1) * page_size
 
     # Build context
     context = await context_service.build_context(
-        types=types, depth=depth, since=since, max_results=max_results
+        types=types, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
     )
-    return await to_graph_context(context, entity_repository=entity_repository)
+    recent_context = await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
+    )
+    logger.debug(f"Recent context: {recent_context.model_dump_json()}")
+    return recent_context
 
 
 # get_memory_context needs to be declared last so other paths can match
@@ -109,21 +120,27 @@ async def get_memory_context(
     uri: str,
     depth: int = 1,
     timeframe: TimeFrame = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get rich context from memory:// URI."""
     # add the project name from the config to the url as the "host
     # Parse URI
     logger.debug(
-        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
     )
     memory_url = normalize_memory_url(uri)
 
     # Parse timeframe
     since = parse(timeframe)
+    limit = page_size
+    offset = (page - 1) * page_size
 
     # Build context
     context = await context_service.build_context(
-        memory_url, depth=depth, since=since, max_results=max_results
+        memory_url, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
+    )
+    return await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
     )
-    return await to_graph_context(context, entity_repository=entity_repository)

src/basic_memory/api/routers/project_info_router.py

@@ -0,0 +1,274 @@
+"""Router for statistics and system information."""
+
+import json
+from datetime import datetime
+
+from basic_memory.config import config, config_manager
+from basic_memory.deps import (
+    ProjectInfoRepositoryDep,
+)
+from basic_memory.repository.project_info_repository import ProjectInfoRepository
+from basic_memory.schemas import (
+    ProjectInfoResponse,
+    ProjectStatistics,
+    ActivityMetrics,
+    SystemStatus,
+)
+from basic_memory.sync.watch_service import WATCH_STATUS_JSON
+from fastapi import APIRouter
+from sqlalchemy import text
+
+router = APIRouter(prefix="/stats", tags=["statistics"])
+
+
+@router.get("/project-info", response_model=ProjectInfoResponse)
+async def get_project_info(
+    repository: ProjectInfoRepositoryDep,
+) -> ProjectInfoResponse:
+    """Get comprehensive information about the current Basic Memory project."""
+    # Get statistics
+    statistics = await get_statistics(repository)
+
+    # Get activity metrics
+    activity = await get_activity_metrics(repository)
+
+    # Get system status
+    system = await get_system_status()
+
+    # Get project configuration information
+    project_name = config.project
+    project_path = str(config.home)
+    available_projects = config_manager.projects
+    default_project = config_manager.default_project
+
+    # Construct the response
+    return ProjectInfoResponse(
+        project_name=project_name,
+        project_path=project_path,
+        available_projects=available_projects,
+        default_project=default_project,
+        statistics=statistics,
+        activity=activity,
+        system=system,
+    )
+
+
+async def get_statistics(repository: ProjectInfoRepository) -> ProjectStatistics:
+    """Get statistics about the current project."""
+    # Get basic counts
+    entity_count_result = await repository.execute_query(text("SELECT COUNT(*) FROM entity"))
+    total_entities = entity_count_result.scalar() or 0
+
+    observation_count_result = await repository.execute_query(
+        text("SELECT COUNT(*) FROM observation")
+    )
+    total_observations = observation_count_result.scalar() or 0
+
+    relation_count_result = await repository.execute_query(text("SELECT COUNT(*) FROM relation"))
+    total_relations = relation_count_result.scalar() or 0
+
+    unresolved_count_result = await repository.execute_query(
+        text("SELECT COUNT(*) FROM relation WHERE to_id IS NULL")
+    )
+    total_unresolved = unresolved_count_result.scalar() or 0
+
+    # Get entity counts by type
+    entity_types_result = await repository.execute_query(
+        text("SELECT entity_type, COUNT(*) FROM entity GROUP BY entity_type")
+    )
+    entity_types = {row[0]: row[1] for row in entity_types_result.fetchall()}
+
+    # Get observation counts by category
+    category_result = await repository.execute_query(
+        text("SELECT category, COUNT(*) FROM observation GROUP BY category")
+    )
+    observation_categories = {row[0]: row[1] for row in category_result.fetchall()}
+
+    # Get relation counts by type
+    relation_types_result = await repository.execute_query(
+        text("SELECT relation_type, COUNT(*) FROM relation GROUP BY relation_type")
+    )
+    relation_types = {row[0]: row[1] for row in relation_types_result.fetchall()}
+
+    # Find most connected entities (most outgoing relations)
+    connected_result = await repository.execute_query(
+        text("""
+        SELECT e.id, e.title, e.permalink, COUNT(r.id) AS relation_count
+        FROM entity e
+        JOIN relation r ON e.id = r.from_id
+        GROUP BY e.id
+        ORDER BY relation_count DESC
+        LIMIT 10
+    """)
+    )
+    most_connected = [
+        {"id": row[0], "title": row[1], "permalink": row[2], "relation_count": row[3]}
+        for row in connected_result.fetchall()
+    ]
+
+    # Count isolated entities (no relations)
+    isolated_result = await repository.execute_query(
+        text("""
+        SELECT COUNT(e.id)
+        FROM entity e
+        LEFT JOIN relation r1 ON e.id = r1.from_id
+        LEFT JOIN relation r2 ON e.id = r2.to_id
+        WHERE r1.id IS NULL AND r2.id IS NULL
+    """)
+    )
+    isolated_count = isolated_result.scalar() or 0
+
+    return ProjectStatistics(
+        total_entities=total_entities,
+        total_observations=total_observations,
+        total_relations=total_relations,
+        total_unresolved_relations=total_unresolved,
+        entity_types=entity_types,
+        observation_categories=observation_categories,
+        relation_types=relation_types,
+        most_connected_entities=most_connected,
+        isolated_entities=isolated_count,
+    )
+
+
+async def get_activity_metrics(repository: ProjectInfoRepository) -> ActivityMetrics:
+    """Get activity metrics for the current project."""
+    # Get recently created entities
+    created_result = await repository.execute_query(
+        text("""
+        SELECT id, title, permalink, entity_type, created_at 
+        FROM entity
+        ORDER BY created_at DESC
+        LIMIT 10
+    """)
+    )
+    recently_created = [
+        {
+            "id": row[0],
+            "title": row[1],
+            "permalink": row[2],
+            "entity_type": row[3],
+            "created_at": row[4],
+        }
+        for row in created_result.fetchall()
+    ]
+
+    # Get recently updated entities
+    updated_result = await repository.execute_query(
+        text("""
+        SELECT id, title, permalink, entity_type, updated_at 
+        FROM entity
+        ORDER BY updated_at DESC
+        LIMIT 10
+    """)
+    )
+    recently_updated = [
+        {
+            "id": row[0],
+            "title": row[1],
+            "permalink": row[2],
+            "entity_type": row[3],
+            "updated_at": row[4],
+        }
+        for row in updated_result.fetchall()
+    ]
+
+    # Get monthly growth over the last 6 months
+    # Calculate the start of 6 months ago
+    now = datetime.now()
+    six_months_ago = datetime(
+        now.year - (1 if now.month <= 6 else 0), ((now.month - 6) % 12) or 12, 1
+    )
+
+    # Query for monthly entity creation
+    entity_growth_result = await repository.execute_query(
+        text(f"""
+        SELECT 
+            strftime('%Y-%m', created_at) AS month,
+            COUNT(*) AS count
+        FROM entity
+        WHERE created_at >= '{six_months_ago.isoformat()}'
+        GROUP BY month
+        ORDER BY month
+    """)
+    )
+    entity_growth = {row[0]: row[1] for row in entity_growth_result.fetchall()}
+
+    # Query for monthly observation creation
+    observation_growth_result = await repository.execute_query(
+        text(f"""
+        SELECT 
+            strftime('%Y-%m', created_at) AS month,
+            COUNT(*) AS count
+        FROM observation
+        INNER JOIN entity ON observation.entity_id = entity.id
+        WHERE entity.created_at >= '{six_months_ago.isoformat()}'
+        GROUP BY month
+        ORDER BY month
+    """)
+    )
+    observation_growth = {row[0]: row[1] for row in observation_growth_result.fetchall()}
+
+    # Query for monthly relation creation
+    relation_growth_result = await repository.execute_query(
+        text(f"""
+        SELECT 
+            strftime('%Y-%m', created_at) AS month,
+            COUNT(*) AS count
+        FROM relation
+        INNER JOIN entity ON relation.from_id = entity.id
+        WHERE entity.created_at >= '{six_months_ago.isoformat()}'
+        GROUP BY month
+        ORDER BY month
+    """)
+    )
+    relation_growth = {row[0]: row[1] for row in relation_growth_result.fetchall()}
+
+    # Combine all monthly growth data
+    monthly_growth = {}
+    for month in set(
+        list(entity_growth.keys()) + list(observation_growth.keys()) + list(relation_growth.keys())
+    ):
+        monthly_growth[month] = {
+            "entities": entity_growth.get(month, 0),
+            "observations": observation_growth.get(month, 0),
+            "relations": relation_growth.get(month, 0),
+            "total": (
+                entity_growth.get(month, 0)
+                + observation_growth.get(month, 0)
+                + relation_growth.get(month, 0)
+            ),
+        }
+
+    return ActivityMetrics(
+        recently_created=recently_created,
+        recently_updated=recently_updated,
+        monthly_growth=monthly_growth,
+    )
+
+
+async def get_system_status() -> SystemStatus:
+    """Get system status information."""
+    import basic_memory
+
+    # Get database information
+    db_path = config.database_path
+    db_size = db_path.stat().st_size if db_path.exists() else 0
+    db_size_readable = f"{db_size / (1024 * 1024):.2f} MB"
+
+    # Get watch service status if available
+    watch_status = None
+    watch_status_path = config.home / ".basic-memory" / WATCH_STATUS_JSON
+    if watch_status_path.exists():
+        try:
+            watch_status = json.loads(watch_status_path.read_text(encoding="utf-8"))
+        except Exception:  # pragma: no cover
+            pass
+
+    return SystemStatus(
+        version=basic_memory.__version__,
+        database_path=str(db_path),
+        database_size=db_size_readable,
+        watch_status=watch_status,
+        timestamp=datetime.now(),
+    )

src/basic_memory/api/routers/resource_router.py

@@ -1,34 +1,225 @@
 """Routes for getting entity content."""
 
+import tempfile
 from pathlib import Path
+from typing import Annotated
 
-from fastapi import APIRouter, HTTPException
-from fastapi.responses import FileResponse
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
+from fastapi.responses import FileResponse, JSONResponse
 from loguru import logger
 
-from basic_memory.deps import ProjectConfigDep, LinkResolverDep
+from basic_memory.deps import (
+    ProjectConfigDep,
+    LinkResolverDep,
+    SearchServiceDep,
+    EntityServiceDep,
+    FileServiceDep,
+    EntityRepositoryDep,
+)
+from basic_memory.repository.search_repository import SearchIndexRow
+from basic_memory.schemas.memory import normalize_memory_url
+from basic_memory.schemas.search import SearchQuery, SearchItemType
+from basic_memory.models.knowledge import Entity as EntityModel
+from datetime import datetime
 
 router = APIRouter(prefix="/resource", tags=["resources"])
 
 
+def get_entity_ids(item: SearchIndexRow) -> set[int]:
+    match item.type:
+        case SearchItemType.ENTITY:
+            return {item.id}
+        case SearchItemType.OBSERVATION:
+            return {item.entity_id}  # pyright: ignore [reportReturnType]
+        case SearchItemType.RELATION:
+            from_entity = item.from_id
+            to_entity = item.to_id  # pyright: ignore [reportReturnType]
+            return {from_entity, to_entity} if to_entity else {from_entity}  # pyright: ignore [reportReturnType]
+        case _:  # pragma: no cover
+            raise ValueError(f"Unexpected type: {item.type}")
+
+
 @router.get("/{identifier:path}")
 async def get_resource_content(
     config: ProjectConfigDep,
     link_resolver: LinkResolverDep,
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    file_service: FileServiceDep,
+    background_tasks: BackgroundTasks,
     identifier: str,
+    page: int = 1,
+    page_size: int = 10,
 ) -> FileResponse:
     """Get resource content by identifier: name or permalink."""
-    logger.debug(f"Getting content for permalink: {identifier}")
+    logger.debug(f"Getting content for: {identifier}")
 
-    # Find entity by permalink
+    # Find single entity by permalink
     entity = await link_resolver.resolve_link(identifier)
-    if not entity:
-        raise HTTPException(status_code=404, detail=f"Entity not found: {identifier}")
+    results = [entity] if entity else []
 
-    file_path = Path(f"{config.home}/{entity.file_path}")
-    if not file_path.exists():
-        raise HTTPException(
-            status_code=404,
-            detail=f"File not found: {file_path}",
+    # pagination for multiple results
+    limit = page_size
+    offset = (page - 1) * page_size
+
+    # search using the identifier as a permalink
+    if not results:
+        # if the identifier contains a wildcard, use GLOB search
+        query = (
+            SearchQuery(permalink_match=identifier)
+            if "*" in identifier
+            else SearchQuery(permalink=identifier)
         )
-    return FileResponse(path=file_path)
+        search_results = await search_service.search(query, limit, offset)
+        if not search_results:
+            raise HTTPException(status_code=404, detail=f"Resource not found: {identifier}")
+
+        # get the deduplicated entities related to the search results
+        entity_ids = {id for result in search_results for id in get_entity_ids(result)}
+        results = await entity_service.get_entities_by_id(list(entity_ids))
+
+    # return single response
+    if len(results) == 1:
+        entity = results[0]
+        file_path = Path(f"{config.home}/{entity.file_path}")
+        if not file_path.exists():
+            raise HTTPException(
+                status_code=404,
+                detail=f"File not found: {file_path}",
+            )
+        return FileResponse(path=file_path)
+
+    # for multiple files, initialize a temporary file for writing the results
+    with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
+        temp_file_path = tmp_file.name
+
+        for result in results:
+            # Read content for each entity
+            content = await file_service.read_entity_content(result)
+            memory_url = normalize_memory_url(result.permalink)
+            modified_date = result.updated_at.isoformat()
+            checksum = result.checksum[:8] if result.checksum else ""
+
+            # Prepare the delimited content
+            response_content = f"--- {memory_url} {modified_date} {checksum}\n"
+            response_content += f"\n{content}\n"
+            response_content += "\n"
+
+            # Write content directly to the temporary file in append mode
+            tmp_file.write(response_content)
+
+        # Ensure all content is written to disk
+        tmp_file.flush()
+
+    # Schedule the temporary file to be deleted after the response
+    background_tasks.add_task(cleanup_temp_file, temp_file_path)
+
+    # Return the file response
+    return FileResponse(path=temp_file_path)
+
+
+def cleanup_temp_file(file_path: str):
+    """Delete the temporary file."""
+    try:
+        Path(file_path).unlink()  # Deletes the file
+        logger.debug(f"Temporary file deleted: {file_path}")
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error deleting temporary file {file_path}: {e}")
+
+
+@router.put("/{file_path:path}")
+async def write_resource(
+    config: ProjectConfigDep,
+    file_service: FileServiceDep,
+    entity_repository: EntityRepositoryDep,
+    search_service: SearchServiceDep,
+    file_path: str,
+    content: Annotated[str, Body()],
+) -> JSONResponse:
+    """Write content to a file in the project.
+
+    This endpoint allows writing content directly to a file in the project.
+    Also creates an entity record and indexes the file for search.
+
+    Args:
+        file_path: Path to write to, relative to project root
+        request: Contains the content to write
+
+    Returns:
+        JSON response with file information
+    """
+    try:
+        # Get content from request body
+
+        # Ensure it's UTF-8 string content
+        if isinstance(content, bytes):  # pragma: no cover
+            content_str = content.decode("utf-8")
+        else:
+            content_str = str(content)
+
+        # Get full file path
+        full_path = Path(f"{config.home}/{file_path}")
+
+        # Ensure parent directory exists
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content to file
+        checksum = await file_service.write_file(full_path, content_str)
+
+        # Get file info
+        file_stats = file_service.file_stats(full_path)
+
+        # Determine file details
+        file_name = Path(file_path).name
+        content_type = file_service.content_type(full_path)
+
+        entity_type = "canvas" if file_path.endswith(".canvas") else "file"
+
+        # Check if entity already exists
+        existing_entity = await entity_repository.get_by_file_path(file_path)
+
+        if existing_entity:
+            # Update existing entity
+            entity = await entity_repository.update(
+                existing_entity.id,
+                {
+                    "title": file_name,
+                    "entity_type": entity_type,
+                    "content_type": content_type,
+                    "file_path": file_path,
+                    "checksum": checksum,
+                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime),
+                },
+            )
+            status_code = 200
+        else:
+            # Create a new entity model
+            entity = EntityModel(
+                title=file_name,
+                entity_type=entity_type,
+                content_type=content_type,
+                file_path=file_path,
+                checksum=checksum,
+                created_at=datetime.fromtimestamp(file_stats.st_ctime),
+                updated_at=datetime.fromtimestamp(file_stats.st_mtime),
+            )
+            entity = await entity_repository.add(entity)
+            status_code = 201
+
+        # Index the file for search
+        await search_service.index_entity(entity)  # pyright: ignore
+
+        # Return success response
+        return JSONResponse(
+            status_code=status_code,
+            content={
+                "file_path": file_path,
+                "checksum": checksum,
+                "size": file_stats.st_size,
+                "created_at": file_stats.st_ctime,
+                "modified_at": file_stats.st_mtime,
+            },
+        )
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error writing resource {file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to write resource: {str(e)}")

src/basic_memory/api/routers/search_router.py

@@ -1,28 +1,54 @@
 """Router for search operations."""
 
-from dataclasses import asdict
+from fastapi import APIRouter, BackgroundTasks
 
-from fastapi import APIRouter, Depends, BackgroundTasks
-
-from basic_memory.services.search_service import SearchService
 from basic_memory.schemas.search import SearchQuery, SearchResult, SearchResponse
-from basic_memory.deps import get_search_service
+from basic_memory.deps import SearchServiceDep, EntityServiceDep
 
 router = APIRouter(prefix="/search", tags=["search"])
 
 
 @router.post("/", response_model=SearchResponse)
-async def search(query: SearchQuery, search_service: SearchService = Depends(get_search_service)):
+async def search(
+    query: SearchQuery,
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    page: int = 1,
+    page_size: int = 10,
+):
     """Search across all knowledge and documents."""
-    results = await search_service.search(query)
-    search_results = [SearchResult.model_validate(asdict(r)) for r in results]
-    return SearchResponse(results=search_results)
+    limit = page_size
+    offset = (page - 1) * page_size
+    results = await search_service.search(query, limit=limit, offset=offset)
+
+    search_results = []
+    for r in results:
+        entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+        search_results.append(
+            SearchResult(
+                title=r.title,  # pyright: ignore
+                type=r.type,  # pyright: ignore
+                permalink=r.permalink,
+                score=r.score,  # pyright: ignore
+                entity=entities[0].permalink if entities else None,
+                content=r.content,
+                file_path=r.file_path,
+                metadata=r.metadata,
+                category=r.category,
+                from_entity=entities[0].permalink if entities else None,
+                to_entity=entities[1].permalink if len(entities) > 1 else None,
+                relation_type=r.relation_type,
+            )
+        )
+    return SearchResponse(
+        results=search_results,
+        current_page=page,
+        page_size=page_size,
+    )
 
 
 @router.post("/reindex")
-async def reindex(
-    background_tasks: BackgroundTasks, search_service: SearchService = Depends(get_search_service)
-):
+async def reindex(background_tasks: BackgroundTasks, search_service: SearchServiceDep):
     """Recreate and populate the search index."""
     await search_service.reindex_all(background_tasks=background_tasks)
     return {"status": "ok", "message": "Reindex initiated"}

src/basic_memory/cli/app.py

@@ -1,3 +1,74 @@
+from typing import Optional
+
 import typer
 
-app = typer.Typer()
+
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:  # pragma: no cover
+        import basic_memory
+        from basic_memory.config import config
+
+        typer.echo(f"Basic Memory version: {basic_memory.__version__}")
+        typer.echo(f"Current project: {config.project}")
+        typer.echo(f"Project path: {config.home}")
+        raise typer.Exit()
+
+
+app = typer.Typer(name="basic-memory")
+
+
+@app.callback()
+def app_callback(
+    ctx: typer.Context,
+    project: Optional[str] = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Specify which project to use 1",
+        envvar="BASIC_MEMORY_PROJECT",
+    ),
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Basic Memory - Local-first personal knowledge management."""
+
+    # We use the project option to set the BASIC_MEMORY_PROJECT environment variable
+    # The config module will pick this up when loading
+    if project:  # pragma: no cover
+        import os
+        import importlib
+        from basic_memory import config as config_module
+
+        # Set the environment variable
+        os.environ["BASIC_MEMORY_PROJECT"] = project
+
+        # Reload the config module to pick up the new project
+        importlib.reload(config_module)
+
+        # Update the local reference
+        global config
+        from basic_memory.config import config as new_config
+
+        config = new_config
+
+    # Run migrations for every command unless --version was specified
+    if not version and ctx.invoked_subcommand is not None:
+        from basic_memory.config import config
+        from basic_memory.services.initialization import ensure_initialize_database
+
+        ensure_initialize_database(config)
+
+
+# Register sub-command groups
+import_app = typer.Typer(help="Import data from various sources")
+app.add_typer(import_app, name="import")
+
+claude_app = typer.Typer()
+import_app.add_typer(claude_app, name="claude")

src/basic_memory/cli/commands/__init__.py

@@ -1,5 +1,17 @@
 """CLI commands for basic-memory."""
 
-from . import status, sync, db, import_memory_json, mcp
+from . import status, sync, db, import_memory_json, mcp, import_claude_conversations
+from . import import_claude_projects, import_chatgpt, tool, project
 
-__all__ = ["status", "sync", "db", "import_memory_json", "mcp"]
+__all__ = [
+    "status",
+    "sync",
+    "db",
+    "import_memory_json",
+    "mcp",
+    "import_claude_conversations",
+    "import_claude_projects",
+    "import_chatgpt",
+    "tool",
+    "project",
+]

src/basic_memory/cli/commands/db.py

@@ -1,25 +1,37 @@
 """Database management commands."""
 
 import asyncio
+
 import typer
 from loguru import logger
 
-from basic_memory.alembic import migrations
+from basic_memory import db
 from basic_memory.cli.app import app
+from basic_memory.config import config
 
 
 @app.command()
 def reset(
-    reindex: bool = typer.Option(False, "--reindex", help="Rebuild indices from filesystem"),
+    reindex: bool = typer.Option(False, "--reindex", help="Rebuild db index from filesystem"),
 ):  # pragma: no cover
     """Reset database (drop all tables and recreate)."""
-    if typer.confirm("This will delete all data. Are you sure?"):
+    if typer.confirm("This will delete all data in your db. Are you sure?"):
         logger.info("Resetting database...")
-        asyncio.run(migrations.reset_database())
+        # Get database path
+        db_path = config.database_path
+
+        # Delete the database file if it exists
+        if db_path.exists():
+            db_path.unlink()
+            logger.info(f"Database file deleted: {db_path}")
+
+        # Create a new empty database
+        asyncio.run(db.run_migrations(config))
+        logger.info("Database reset complete")
 
         if reindex:
             # Import and run sync
             from basic_memory.cli.commands.sync import sync
 
             logger.info("Rebuilding search index from filesystem...")
-            asyncio.run(sync())  # pyright: ignore
+            sync(watch=False)  # pyright: ignore

src/basic_memory/cli/commands/import_chatgpt.py

@@ -0,0 +1,258 @@
+"""Import command for ChatGPT conversations."""
+
+import asyncio
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, List, Annotated, Set, Optional
+
+import typer
+from basic_memory.cli.app import import_app
+from basic_memory.config import config
+from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.markdown.schemas import EntityMarkdown, EntityFrontmatter
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+
+console = Console()
+
+
+def clean_filename(text: str) -> str:
+    """Convert text to safe filename."""
+    clean = "".join(c if c.isalnum() else "-" for c in text.lower()).strip("-")
+    return clean
+
+
+def format_timestamp(ts: float) -> str:
+    """Format Unix timestamp for display."""
+    dt = datetime.fromtimestamp(ts)
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def get_message_content(message: Dict[str, Any]) -> str:
+    """Extract clean message content."""
+    if not message or "content" not in message:
+        return ""  # pragma: no cover
+
+    content = message["content"]
+    if content.get("content_type") == "text":
+        return "\n".join(content.get("parts", []))
+    elif content.get("content_type") == "code":
+        return f"```{content.get('language', '')}\n{content.get('text', '')}\n```"
+    return ""  # pragma: no cover
+
+
+def traverse_messages(
+    mapping: Dict[str, Any], root_id: Optional[str], seen: Set[str]
+) -> List[Dict[str, Any]]:
+    """Traverse message tree and return messages in order."""
+    messages = []
+    node = mapping.get(root_id) if root_id else None
+
+    while node:
+        if node["id"] not in seen and node.get("message"):
+            seen.add(node["id"])
+            messages.append(node["message"])
+
+        # Follow children
+        children = node.get("children", [])
+        for child_id in children:
+            child_msgs = traverse_messages(mapping, child_id, seen)
+            messages.extend(child_msgs)
+
+        break  # Don't follow siblings
+
+    return messages
+
+
+def format_chat_markdown(
+    title: str,
+    mapping: Dict[str, Any],
+    root_id: Optional[str],
+    created_at: float,
+    modified_at: float,
+) -> str:
+    """Format chat as clean markdown."""
+
+    # Start with title
+    lines = [f"# {title}\n"]
+
+    # Traverse message tree
+    seen_msgs = set()
+    messages = traverse_messages(mapping, root_id, seen_msgs)
+
+    # Format each message
+    for msg in messages:
+        # Skip hidden messages
+        if msg.get("metadata", {}).get("is_visually_hidden_from_conversation"):
+            continue
+
+        # Get author and timestamp
+        author = msg["author"]["role"].title()
+        ts = format_timestamp(msg["create_time"]) if msg.get("create_time") else ""
+
+        # Add message header
+        lines.append(f"### {author} ({ts})")
+
+        # Add message content
+        content = get_message_content(msg)
+        if content:
+            lines.append(content)
+
+        # Add spacing
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_chat_content(folder: str, conversation: Dict[str, Any]) -> EntityMarkdown:
+    """Convert chat conversation to Basic Memory entity."""
+
+    # Extract timestamps
+    created_at = conversation["create_time"]
+    modified_at = conversation["update_time"]
+
+    root_id = None
+    # Find root message
+    for node_id, node in conversation["mapping"].items():
+        if node.get("parent") is None:
+            root_id = node_id
+            break
+
+    # Generate permalink
+    date_prefix = datetime.fromtimestamp(created_at).strftime("%Y%m%d")
+    clean_title = clean_filename(conversation["title"])
+
+    # Format content
+    content = format_chat_markdown(
+        title=conversation["title"],
+        mapping=conversation["mapping"],
+        root_id=root_id,
+        created_at=created_at,
+        modified_at=modified_at,
+    )
+
+    # Create entity
+    entity = EntityMarkdown(
+        frontmatter=EntityFrontmatter(
+            metadata={
+                "type": "conversation",
+                "title": conversation["title"],
+                "created": format_timestamp(created_at),
+                "modified": format_timestamp(modified_at),
+                "permalink": f"{folder}/{date_prefix}-{clean_title}",
+            }
+        ),
+        content=content,
+    )
+
+    return entity
+
+
+async def process_chatgpt_json(
+    json_path: Path, folder: str, markdown_processor: MarkdownProcessor
+) -> Dict[str, int]:
+    """Import conversations from ChatGPT JSON format."""
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+    ) as progress:
+        read_task = progress.add_task("Reading chat data...", total=None)
+
+        # Read conversations
+        conversations = json.loads(json_path.read_text(encoding="utf-8"))
+        progress.update(read_task, total=len(conversations))
+
+        # Process each conversation
+        messages_imported = 0
+        chats_imported = 0
+
+        for chat in conversations:
+            # Convert to entity
+            entity = format_chat_content(folder, chat)
+
+            # Write file
+            file_path = config.home / f"{entity.frontmatter.metadata['permalink']}.md"
+            # logger.info(f"Writing file: {file_path.absolute()}")
+            await markdown_processor.write_file(file_path, entity)
+
+            # Count messages
+            msg_count = sum(
+                1
+                for node in chat["mapping"].values()
+                if node.get("message")
+                and not node.get("message", {})
+                .get("metadata", {})
+                .get("is_visually_hidden_from_conversation")
+            )
+
+            chats_imported += 1
+            messages_imported += msg_count
+            progress.update(read_task, advance=1)
+
+    return {"conversations": chats_imported, "messages": messages_imported}
+
+
+async def get_markdown_processor() -> MarkdownProcessor:
+    """Get MarkdownProcessor instance."""
+    entity_parser = EntityParser(config.home)
+    return MarkdownProcessor(entity_parser)
+
+
+@import_app.command(name="chatgpt", help="Import conversations from ChatGPT JSON export.")
+def import_chatgpt(
+    conversations_json: Annotated[
+        Path, typer.Argument(help="Path to ChatGPT conversations.json file")
+    ] = Path("conversations.json"),
+    folder: Annotated[
+        str, typer.Option(help="The folder to place the files in.")
+    ] = "conversations",
+):
+    """Import chat conversations from ChatGPT JSON format.
+
+    This command will:
+    1. Read the complex tree structure of messages
+    2. Convert them to linear markdown conversations
+    3. Save as clean, readable markdown files
+
+    After importing, run 'basic-memory sync' to index the new files.
+    """
+
+    try:
+        if conversations_json:
+            if not conversations_json.exists():
+                typer.echo(f"Error: File not found: {conversations_json}", err=True)
+                raise typer.Exit(1)
+
+            # Get markdown processor
+            markdown_processor = asyncio.run(get_markdown_processor())
+
+            # Process the file
+            base_path = config.home / folder
+            console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
+            results = asyncio.run(
+                process_chatgpt_json(conversations_json, folder, markdown_processor)
+            )
+
+            # Show results
+            console.print(
+                Panel(
+                    f"[green]Import complete![/green]\n\n"
+                    f"Imported {results['conversations']} conversations\n"
+                    f"Containing {results['messages']} messages",
+                    expand=False,
+                )
+            )
+
+        console.print("\nRun 'basic-memory sync' to index the new files.")
+
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -0,0 +1,210 @@
+"""Import command for basic-memory CLI to import chat data from conversations2.json format."""
+
+import asyncio
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, List, Annotated
+
+import typer
+from basic_memory.cli.app import claude_app
+from basic_memory.config import config
+from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.markdown.schemas import EntityMarkdown, EntityFrontmatter
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+
+console = Console()
+
+
+def clean_filename(text: str) -> str:
+    """Convert text to safe filename."""
+    # Remove invalid characters and convert spaces
+    clean = "".join(c if c.isalnum() else "-" for c in text.lower()).strip("-")
+    return clean
+
+
+def format_timestamp(ts: str) -> str:
+    """Format ISO timestamp for display."""
+    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def format_chat_markdown(
+    name: str, messages: List[Dict[str, Any]], created_at: str, modified_at: str, permalink: str
+) -> str:
+    """Format chat as clean markdown."""
+
+    # Start with frontmatter and title
+    lines = [
+        f"# {name}\n",
+    ]
+
+    # Add messages
+    for msg in messages:
+        # Format timestamp
+        ts = format_timestamp(msg["created_at"])
+
+        # Add message header
+        lines.append(f"### {msg['sender'].title()} ({ts})")
+
+        # Handle message content
+        content = msg.get("text", "")
+        if msg.get("content"):
+            content = " ".join(c.get("text", "") for c in msg["content"])
+        lines.append(content)
+
+        # Handle attachments
+        attachments = msg.get("attachments", [])
+        for attachment in attachments:
+            if "file_name" in attachment:
+                lines.append(f"\n**Attachment: {attachment['file_name']}**")
+                if "extracted_content" in attachment:
+                    lines.append("```")
+                    lines.append(attachment["extracted_content"])
+                    lines.append("```")
+
+        # Add spacing between messages
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_chat_content(
+    base_path: Path, name: str, messages: List[Dict[str, Any]], created_at: str, modified_at: str
+) -> EntityMarkdown:
+    """Convert chat messages to Basic Memory entity format."""
+
+    # Generate permalink
+    date_prefix = datetime.fromisoformat(created_at.replace("Z", "+00:00")).strftime("%Y%m%d")
+    clean_title = clean_filename(name)
+    permalink = f"{base_path}/{date_prefix}-{clean_title}"
+
+    # Format content
+    content = format_chat_markdown(
+        name=name,
+        messages=messages,
+        created_at=created_at,
+        modified_at=modified_at,
+        permalink=permalink,
+    )
+
+    # Create entity
+    entity = EntityMarkdown(
+        frontmatter=EntityFrontmatter(
+            metadata={
+                "type": "conversation",
+                "title": name,
+                "created": created_at,
+                "modified": modified_at,
+                "permalink": permalink,
+            }
+        ),
+        content=content,
+    )
+
+    return entity
+
+
+async def process_conversations_json(
+    json_path: Path, base_path: Path, markdown_processor: MarkdownProcessor
+) -> Dict[str, int]:
+    """Import chat data from conversations2.json format."""
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+    ) as progress:
+        read_task = progress.add_task("Reading chat data...", total=None)
+
+        # Read chat data - handle array of arrays format
+        data = json.loads(json_path.read_text(encoding="utf-8"))
+        conversations = [chat for chat in data]
+        progress.update(read_task, total=len(conversations))
+
+        # Process each conversation
+        messages_imported = 0
+        chats_imported = 0
+
+        for chat in conversations:
+            # Convert to entity
+            entity = format_chat_content(
+                base_path=base_path,
+                name=chat["name"],
+                messages=chat["chat_messages"],
+                created_at=chat["created_at"],
+                modified_at=chat["updated_at"],
+            )
+
+            # Write file
+            file_path = Path(f"{entity.frontmatter.metadata['permalink']}.md")
+            await markdown_processor.write_file(file_path, entity)
+
+            chats_imported += 1
+            messages_imported += len(chat["chat_messages"])
+            progress.update(read_task, advance=1)
+
+    return {"conversations": chats_imported, "messages": messages_imported}
+
+
+async def get_markdown_processor() -> MarkdownProcessor:
+    """Get MarkdownProcessor instance."""
+    entity_parser = EntityParser(config.home)
+    return MarkdownProcessor(entity_parser)
+
+
+@claude_app.command(name="conversations", help="Import chat conversations from Claude.ai.")
+def import_claude(
+    conversations_json: Annotated[
+        Path, typer.Argument(..., help="Path to conversations.json file")
+    ] = Path("conversations.json"),
+    folder: Annotated[
+        str, typer.Option(help="The folder to place the files in.")
+    ] = "conversations",
+):
+    """Import chat conversations from conversations2.json format.
+
+    This command will:
+    1. Read chat data and nested messages
+    2. Create markdown files for each conversation
+    3. Format content in clean, readable markdown
+
+    After importing, run 'basic-memory sync' to index the new files.
+    """
+
+    try:
+        if not conversations_json.exists():
+            typer.echo(f"Error: File not found: {conversations_json}", err=True)
+            raise typer.Exit(1)
+
+        # Get markdown processor
+        markdown_processor = asyncio.run(get_markdown_processor())
+
+        # Process the file
+        base_path = config.home / folder
+        console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
+        results = asyncio.run(
+            process_conversations_json(conversations_json, base_path, markdown_processor)
+        )
+
+        # Show results
+        console.print(
+            Panel(
+                f"[green]Import complete![/green]\n\n"
+                f"Imported {results['conversations']} conversations\n"
+                f"Containing {results['messages']} messages",
+                expand=False,
+            )
+        )
+
+        console.print("\nRun 'basic-memory sync' to index the new files.")
+
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_claude_projects.py

@@ -0,0 +1,193 @@
+"""Import command for basic-memory CLI to import project data from Claude.ai."""
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Dict, Any, Annotated, Optional
+
+import typer
+from basic_memory.cli.app import claude_app
+from basic_memory.config import config
+from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.markdown.schemas import EntityMarkdown, EntityFrontmatter
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+
+console = Console()
+
+
+def clean_filename(text: str) -> str:
+    """Convert text to safe filename."""
+    clean = "".join(c if c.isalnum() else "-" for c in text.lower()).strip("-")
+    return clean
+
+
+def format_project_markdown(project: Dict[str, Any], doc: Dict[str, Any]) -> EntityMarkdown:
+    """Format a project document as a Basic Memory entity."""
+
+    # Extract timestamps
+    created_at = doc.get("created_at") or project["created_at"]
+    modified_at = project["updated_at"]
+
+    # Generate clean names for organization
+    project_dir = clean_filename(project["name"])
+    doc_file = clean_filename(doc["filename"])
+
+    # Create entity
+    entity = EntityMarkdown(
+        frontmatter=EntityFrontmatter(
+            metadata={
+                "type": "project_doc",
+                "title": doc["filename"],
+                "created": created_at,
+                "modified": modified_at,
+                "permalink": f"{project_dir}/docs/{doc_file}",
+                "project_name": project["name"],
+                "project_uuid": project["uuid"],
+                "doc_uuid": doc["uuid"],
+            }
+        ),
+        content=doc["content"],
+    )
+
+    return entity
+
+
+def format_prompt_markdown(project: Dict[str, Any]) -> Optional[EntityMarkdown]:
+    """Format project prompt template as a Basic Memory entity."""
+
+    if not project.get("prompt_template"):
+        return None
+
+    # Extract timestamps
+    created_at = project["created_at"]
+    modified_at = project["updated_at"]
+
+    # Generate clean project directory name
+    project_dir = clean_filename(project["name"])
+
+    # Create entity
+    entity = EntityMarkdown(
+        frontmatter=EntityFrontmatter(
+            metadata={
+                "type": "prompt_template",
+                "title": f"Prompt Template: {project['name']}",
+                "created": created_at,
+                "modified": modified_at,
+                "permalink": f"{project_dir}/prompt-template",
+                "project_name": project["name"],
+                "project_uuid": project["uuid"],
+            }
+        ),
+        content=f"# Prompt Template: {project['name']}\n\n{project['prompt_template']}",
+    )
+
+    return entity
+
+
+async def process_projects_json(
+    json_path: Path, base_path: Path, markdown_processor: MarkdownProcessor
+) -> Dict[str, int]:
+    """Import project data from Claude.ai projects.json format."""
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+    ) as progress:
+        read_task = progress.add_task("Reading project data...", total=None)
+
+        # Read project data
+        data = json.loads(json_path.read_text(encoding="utf-8"))
+        progress.update(read_task, total=len(data))
+
+        # Track import counts
+        docs_imported = 0
+        prompts_imported = 0
+
+        # Process each project
+        for project in data:
+            project_dir = clean_filename(project["name"])
+
+            # Create project directories
+            docs_dir = base_path / project_dir / "docs"
+            docs_dir.mkdir(parents=True, exist_ok=True)
+
+            # Import prompt template if it exists
+            if prompt_entity := format_prompt_markdown(project):
+                file_path = base_path / f"{prompt_entity.frontmatter.metadata['permalink']}.md"
+                await markdown_processor.write_file(file_path, prompt_entity)
+                prompts_imported += 1
+
+            # Import project documents
+            for doc in project.get("docs", []):
+                entity = format_project_markdown(project, doc)
+                file_path = base_path / f"{entity.frontmatter.metadata['permalink']}.md"
+                await markdown_processor.write_file(file_path, entity)
+                docs_imported += 1
+
+            progress.update(read_task, advance=1)
+
+    return {"documents": docs_imported, "prompts": prompts_imported}
+
+
+async def get_markdown_processor() -> MarkdownProcessor:
+    """Get MarkdownProcessor instance."""
+    entity_parser = EntityParser(config.home)
+    return MarkdownProcessor(entity_parser)
+
+
+@claude_app.command(name="projects", help="Import projects from Claude.ai.")
+def import_projects(
+    projects_json: Annotated[Path, typer.Argument(..., help="Path to projects.json file")] = Path(
+        "projects.json"
+    ),
+    base_folder: Annotated[
+        str, typer.Option(help="The base folder to place project files in.")
+    ] = "projects",
+):
+    """Import project data from Claude.ai.
+
+    This command will:
+    1. Create a directory for each project
+    2. Store docs in a docs/ subdirectory
+    3. Place prompt template in project root
+
+    After importing, run 'basic-memory sync' to index the new files.
+    """
+    try:
+        if projects_json:
+            if not projects_json.exists():
+                typer.echo(f"Error: File not found: {projects_json}", err=True)
+                raise typer.Exit(1)
+
+            # Get markdown processor
+            markdown_processor = asyncio.run(get_markdown_processor())
+
+            # Process the file
+            base_path = config.home / base_folder if base_folder else config.home
+            console.print(f"\nImporting projects from {projects_json}...writing to {base_path}")
+            results = asyncio.run(
+                process_projects_json(projects_json, base_path, markdown_processor)
+            )
+
+            # Show results
+            console.print(
+                Panel(
+                    f"[green]Import complete![/green]\n\n"
+                    f"Imported {results['documents']} project documents\n"
+                    f"Imported {results['prompts']} prompt templates",
+                    expand=False,
+                )
+            )
+
+        console.print("\nRun 'basic-memory sync' to index the new files.")
+
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_memory_json.py

@@ -3,7 +3,7 @@
 import asyncio
 import json
 from pathlib import Path
-from typing import Dict, Any, List
+from typing import Dict, Any, List, Annotated
 
 import typer
 from loguru import logger
@@ -11,12 +11,11 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
 
-from basic_memory.cli.app import app
+from basic_memory.cli.app import import_app
 from basic_memory.config import config
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from basic_memory.markdown.schemas import EntityMarkdown, EntityFrontmatter, Observation, Relation
 
-
 console = Console()
 
 
@@ -39,7 +38,7 @@ async def process_memory_json(
         read_task = progress.add_task("Reading memory.json...", total=None)
 
         # First pass - collect entities and relations
-        with open(json_path) as f:
+        with open(json_path, encoding="utf-8") as f:
             lines = f.readlines()
             progress.update(read_task, total=len(lines))
 
@@ -98,9 +97,11 @@ async def get_markdown_processor() -> MarkdownProcessor:
     return MarkdownProcessor(entity_parser)
 
 
-@app.command()
-def import_json(
-    json_path: Path = typer.Argument(..., help="Path to memory.json file to import"),
+@import_app.command()
+def memory_json(
+    json_path: Annotated[Path, typer.Argument(..., help="Path to memory.json file")] = Path(
+        "memory.json"
+    ),
 ):
     """Import entities and relations from a memory.json file.
 
@@ -138,6 +139,6 @@ def import_json(
         console.print("\nRun 'basic-memory sync' to index the new files.")
 
     except Exception as e:
-        logger.exception("Import failed")
+        logger.error("Import failed")
         typer.echo(f"Error during import: {e}", err=True)
         raise typer.Exit(1)

src/basic_memory/cli/commands/mcp.py

@@ -1,8 +1,7 @@
 """MCP server command."""
 
-from loguru import logger
+import basic_memory
 from basic_memory.cli.app import app
-from basic_memory.config import config
 
 # Import mcp instance
 from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
@@ -12,9 +11,25 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 
 
 @app.command()
-def mcp():
-    """Run the MCP server for Claude Desktop integration."""
-    home_dir = config.home
-    logger.info("Starting Basic Memory MCP server")
-    logger.info(f"Home directory: {home_dir}")
+def mcp():  # pragma: no cover
+    """Run the MCP server"""
+    from basic_memory.config import config
+    import asyncio
+    from basic_memory.services.initialization import initialize_database
+
+    # First, run just the database migrations synchronously
+    asyncio.run(initialize_database(config))
+
+    # Load config to check if sync is enabled
+    from basic_memory.config import config_manager
+
+    basic_memory_config = config_manager.load_config()
+
+    if basic_memory_config.sync_changes:
+        # For now, we'll just log that sync will be handled by the MCP server
+        from loguru import logger
+
+        logger.info("File sync will be handled by the MCP server")
+
+    # Start the MCP server
     mcp_server.run()

src/basic_memory/cli/commands/project.py

@@ -0,0 +1,285 @@
+"""Command module for basic-memory project management."""
+
+import asyncio
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager, config
+from basic_memory.mcp.tools.project_info import project_info
+import json
+from datetime import datetime
+
+from rich.panel import Panel
+from rich.tree import Tree
+
+console = Console()
+
+# Create a project subcommand
+project_app = typer.Typer(help="Manage multiple Basic Memory projects")
+app.add_typer(project_app, name="project")
+
+
+def format_path(path: str) -> str:
+    """Format a path for display, using ~ for home directory."""
+    home = str(Path.home())
+    if path.startswith(home):
+        return path.replace(home, "~", 1)
+    return path
+
+
+@project_app.command("list")
+def list_projects() -> None:
+    """List all configured projects."""
+    config_manager = ConfigManager()
+    projects = config_manager.projects
+
+    table = Table(title="Basic Memory Projects")
+    table.add_column("Name", style="cyan")
+    table.add_column("Path", style="green")
+    table.add_column("Default", style="yellow")
+    table.add_column("Active", style="magenta")
+
+    default_project = config_manager.default_project
+    active_project = config.project
+
+    for name, path in projects.items():
+        is_default = "✓" if name == default_project else ""
+        is_active = "✓" if name == active_project else ""
+        table.add_row(name, format_path(path), is_default, is_active)
+
+    console.print(table)
+
+
+@project_app.command("add")
+def add_project(
+    name: str = typer.Argument(..., help="Name of the project"),
+    path: str = typer.Argument(..., help="Path to the project directory"),
+) -> None:
+    """Add a new project."""
+    config_manager = ConfigManager()
+
+    try:
+        # Resolve to absolute path
+        resolved_path = os.path.abspath(os.path.expanduser(path))
+        config_manager.add_project(name, resolved_path)
+        console.print(f"[green]Project '{name}' added at {format_path(resolved_path)}[/green]")
+
+        # Display usage hint
+        console.print("\nTo use this project:")
+        console.print(f"  basic-memory --project={name} <command>")
+        console.print("  # or")
+        console.print(f"  basic-memory project default {name}")
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("remove")
+def remove_project(
+    name: str = typer.Argument(..., help="Name of the project to remove"),
+) -> None:
+    """Remove a project from configuration."""
+    config_manager = ConfigManager()
+
+    try:
+        config_manager.remove_project(name)
+        console.print(f"[green]Project '{name}' removed from configuration[/green]")
+        console.print("[yellow]Note: The project files have not been deleted from disk.[/yellow]")
+    except ValueError as e:  # pragma: no cover
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("default")
+def set_default_project(
+    name: str = typer.Argument(..., help="Name of the project to set as default"),
+) -> None:
+    """Set the default project and activate it for the current session."""
+    config_manager = ConfigManager()
+
+    try:
+        # Set the default project
+        config_manager.set_default_project(name)
+
+        # Also activate it for the current session by setting the environment variable
+        os.environ["BASIC_MEMORY_PROJECT"] = name
+
+        # Reload configuration to apply the change
+        from importlib import reload
+        from basic_memory import config as config_module
+
+        reload(config_module)
+        console.print(f"[green]Project '{name}' set as default and activated[/green]")
+    except ValueError as e:  # pragma: no cover
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("current")
+def show_current_project() -> None:
+    """Show the current project."""
+    config_manager = ConfigManager()
+    current = os.environ.get("BASIC_MEMORY_PROJECT", config_manager.default_project)
+
+    try:
+        path = config_manager.get_project_path(current)
+        console.print(f"Current project: [cyan]{current}[/cyan]")
+        console.print(f"Path: [green]{format_path(str(path))}[/green]")
+        console.print(f"Database: [blue]{format_path(str(config.database_path))}[/blue]")
+    except ValueError:  # pragma: no cover
+        console.print(f"[yellow]Warning: Project '{current}' not found in configuration[/yellow]")
+        console.print(f"Using default project: [cyan]{config_manager.default_project}[/cyan]")
+
+
+@project_app.command("info")
+def display_project_info(
+    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
+):
+    """Display detailed information and statistics about the current project."""
+    try:
+        # Get project info
+        info = asyncio.run(project_info())
+
+        if json_output:
+            # Convert to JSON and print
+            print(json.dumps(info.model_dump(), indent=2, default=str))
+        else:
+            # Create rich display
+            console = Console()
+
+            # Project configuration section
+            console.print(
+                Panel(
+                    f"[bold]Project:[/bold] {info.project_name}\n"
+                    f"[bold]Path:[/bold] {info.project_path}\n"
+                    f"[bold]Default Project:[/bold] {info.default_project}\n",
+                    title="📊 Basic Memory Project Info",
+                    expand=False,
+                )
+            )
+
+            # Statistics section
+            stats_table = Table(title="📈 Statistics")
+            stats_table.add_column("Metric", style="cyan")
+            stats_table.add_column("Count", style="green")
+
+            stats_table.add_row("Entities", str(info.statistics.total_entities))
+            stats_table.add_row("Observations", str(info.statistics.total_observations))
+            stats_table.add_row("Relations", str(info.statistics.total_relations))
+            stats_table.add_row(
+                "Unresolved Relations", str(info.statistics.total_unresolved_relations)
+            )
+            stats_table.add_row("Isolated Entities", str(info.statistics.isolated_entities))
+
+            console.print(stats_table)
+
+            # Entity types
+            if info.statistics.entity_types:
+                entity_types_table = Table(title="📑 Entity Types")
+                entity_types_table.add_column("Type", style="blue")
+                entity_types_table.add_column("Count", style="green")
+
+                for entity_type, count in info.statistics.entity_types.items():
+                    entity_types_table.add_row(entity_type, str(count))
+
+                console.print(entity_types_table)
+
+            # Most connected entities
+            if info.statistics.most_connected_entities:
+                connected_table = Table(title="🔗 Most Connected Entities")
+                connected_table.add_column("Title", style="blue")
+                connected_table.add_column("Permalink", style="cyan")
+                connected_table.add_column("Relations", style="green")
+
+                for entity in info.statistics.most_connected_entities:
+                    connected_table.add_row(
+                        entity["title"], entity["permalink"], str(entity["relation_count"])
+                    )
+
+                console.print(connected_table)
+
+            # Recent activity
+            if info.activity.recently_updated:
+                recent_table = Table(title="🕒 Recent Activity")
+                recent_table.add_column("Title", style="blue")
+                recent_table.add_column("Type", style="cyan")
+                recent_table.add_column("Last Updated", style="green")
+
+                for entity in info.activity.recently_updated[:5]:  # Show top 5
+                    updated_at = (
+                        datetime.fromisoformat(entity["updated_at"])
+                        if isinstance(entity["updated_at"], str)
+                        else entity["updated_at"]
+                    )
+                    recent_table.add_row(
+                        entity["title"],
+                        entity["entity_type"],
+                        updated_at.strftime("%Y-%m-%d %H:%M"),
+                    )
+
+                console.print(recent_table)
+
+            # System status
+            system_tree = Tree("🖥️ System Status")
+            system_tree.add(f"Basic Memory version: [bold green]{info.system.version}[/bold green]")
+            system_tree.add(
+                f"Database: [cyan]{info.system.database_path}[/cyan] ([green]{info.system.database_size}[/green])"
+            )
+
+            # Watch status
+            if info.system.watch_status:  # pragma: no cover
+                watch_branch = system_tree.add("Watch Service")
+                running = info.system.watch_status.get("running", False)
+                status_color = "green" if running else "red"
+                watch_branch.add(
+                    f"Status: [bold {status_color}]{'Running' if running else 'Stopped'}[/bold {status_color}]"
+                )
+
+                if running:
+                    start_time = (
+                        datetime.fromisoformat(info.system.watch_status.get("start_time", ""))
+                        if isinstance(info.system.watch_status.get("start_time"), str)
+                        else info.system.watch_status.get("start_time")
+                    )
+                    watch_branch.add(
+                        f"Running since: [cyan]{start_time.strftime('%Y-%m-%d %H:%M')}[/cyan]"
+                    )
+                    watch_branch.add(
+                        f"Files synced: [green]{info.system.watch_status.get('synced_files', 0)}[/green]"
+                    )
+                    watch_branch.add(
+                        f"Errors: [{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]{info.system.watch_status.get('error_count', 0)}[/{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]"
+                    )
+            else:
+                system_tree.add("[yellow]Watch service not running[/yellow]")
+
+            console.print(system_tree)
+
+            # Available projects
+            projects_table = Table(title="📁 Available Projects")
+            projects_table.add_column("Name", style="blue")
+            projects_table.add_column("Path", style="cyan")
+            projects_table.add_column("Default", style="green")
+
+            for name, path in info.available_projects.items():
+                is_default = name == info.default_project
+                projects_table.add_row(name, path, "✓" if is_default else "")
+
+            console.print(projects_table)
+
+            # Timestamp
+            current_time = (
+                datetime.fromisoformat(str(info.system.timestamp))
+                if isinstance(info.system.timestamp, str)
+                else info.system.timestamp
+            )
+            console.print(f"\nTimestamp: [cyan]{current_time.strftime('%Y-%m-%d %H:%M:%S')}[/cyan]")
+
+    except Exception as e:  # pragma: no cover
+        typer.echo(f"Error getting project info: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/status.py

@@ -9,31 +9,16 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.tree import Tree
 
-from basic_memory import db
 from basic_memory.cli.app import app
+from basic_memory.cli.commands.sync import get_sync_service
 from basic_memory.config import config
-from basic_memory.db import DatabaseType
-from basic_memory.repository import EntityRepository
-from basic_memory.sync import FileChangeScanner
-from basic_memory.sync.utils import SyncReport
+from basic_memory.sync import SyncService
+from basic_memory.sync.sync_service import SyncReport
 
 # Create rich console
 console = Console()
 
 
-async def get_file_change_scanner(
-    db_type=DatabaseType.FILESYSTEM,
-) -> FileChangeScanner:  # pragma: no cover
-    """Get sync service instance."""
-    async with db.engine_session_factory(db_path=config.database_path, db_type=db_type) as (
-        engine,
-        session_maker,
-    ):
-        entity_repository = EntityRepository(session_maker)
-        file_change_scanner = FileChangeScanner(entity_repository)
-        return file_change_scanner
-
-
 def add_files_to_tree(
     tree: Tree, paths: Set[str], style: str, checksums: Dict[str, str] | None = None
 ):
@@ -105,7 +90,7 @@ def display_changes(title: str, changes: SyncReport, verbose: bool = False):
     """Display changes using Rich for better visualization."""
     tree = Tree(title)
 
-    if changes.total_changes == 0:
+    if changes.total == 0:
         tree.add("No changes")
         console.print(Panel(tree, expand=False))
         return
@@ -136,11 +121,11 @@ def display_changes(title: str, changes: SyncReport, verbose: bool = False):
     console.print(Panel(tree, expand=False))
 
 
-async def run_status(sync_service: FileChangeScanner, verbose: bool = False):
+async def run_status(sync_service: SyncService, verbose: bool = False):
     """Check sync status of files vs database."""
     # Check knowledge/ directory
-    knowledge_changes = await sync_service.find_knowledge_changes(config.home)
-    display_changes("Knowledge Files", knowledge_changes, verbose)
+    knowledge_changes = await sync_service.scan(config.home)
+    display_changes("Status", knowledge_changes, verbose)
 
 
 @app.command()
@@ -149,8 +134,9 @@ def status(
 ):
     """Show sync status between files and database."""
     try:
-        sync_service = asyncio.run(get_file_change_scanner())
+        sync_service = asyncio.run(get_sync_service())
         asyncio.run(run_status(sync_service, verbose))  # pragma: no cover
     except Exception as e:
         logger.exception(f"Error checking status: {e}")
+        typer.echo(f"Error checking status: {e}", err=True)
         raise typer.Exit(code=1)  # pragma: no cover

src/basic_memory/cli/commands/sync.py

@@ -14,7 +14,6 @@ from rich.tree import Tree
 from basic_memory import db
 from basic_memory.cli.app import app
 from basic_memory.config import config
-from basic_memory.db import DatabaseType
 from basic_memory.markdown import EntityParser
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.repository import (
@@ -26,8 +25,8 @@ from basic_memory.repository.search_repository import SearchRepository
 from basic_memory.services import EntityService, FileService
 from basic_memory.services.link_resolver import LinkResolver
 from basic_memory.services.search_service import SearchService
-from basic_memory.sync import SyncService, FileChangeScanner
-from basic_memory.sync.utils import SyncReport
+from basic_memory.sync import SyncService
+from basic_memory.sync.sync_service import SyncReport
 from basic_memory.sync.watch_service import WatchService
 
 console = Console()
@@ -39,50 +38,48 @@ class ValidationIssue:
     error: str
 
 
-async def get_sync_service(db_type=DatabaseType.FILESYSTEM):  # pragma: no cover
+async def get_sync_service():  # pragma: no cover
     """Get sync service instance with all dependencies."""
-    async with db.engine_session_factory(db_path=config.database_path, db_type=db_type) as (
-        engine,
-        session_maker,
-    ):
-        entity_parser = EntityParser(config.home)
-        markdown_processor = MarkdownProcessor(entity_parser)
-        file_service = FileService(config.home, markdown_processor)
+    _, session_maker = await db.get_or_create_db(
+        db_path=config.database_path, db_type=db.DatabaseType.FILESYSTEM
+    )
 
-        # Initialize repositories
-        entity_repository = EntityRepository(session_maker)
-        observation_repository = ObservationRepository(session_maker)
-        relation_repository = RelationRepository(session_maker)
-        search_repository = SearchRepository(session_maker)
+    entity_parser = EntityParser(config.home)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(config.home, markdown_processor)
 
-        # Initialize services
-        search_service = SearchService(search_repository, entity_repository, file_service)
-        link_resolver = LinkResolver(entity_repository, search_service)
+    # Initialize repositories
+    entity_repository = EntityRepository(session_maker)
+    observation_repository = ObservationRepository(session_maker)
+    relation_repository = RelationRepository(session_maker)
+    search_repository = SearchRepository(session_maker)
 
-        # Initialize scanner
-        file_change_scanner = FileChangeScanner(entity_repository)
+    # Initialize services
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    link_resolver = LinkResolver(entity_repository, search_service)
 
-        # Initialize services
-        entity_service = EntityService(
-            entity_parser,
-            entity_repository,
-            observation_repository,
-            relation_repository,
-            file_service,
-            link_resolver,
-        )
+    # Initialize services
+    entity_service = EntityService(
+        entity_parser,
+        entity_repository,
+        observation_repository,
+        relation_repository,
+        file_service,
+        link_resolver,
+    )
 
-        # Create sync service
-        sync_service = SyncService(
-            scanner=file_change_scanner,
-            entity_service=entity_service,
-            entity_parser=entity_parser,
-            entity_repository=entity_repository,
-            relation_repository=relation_repository,
-            search_service=search_service,
-        )
+    # Create sync service
+    sync_service = SyncService(
+        config=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,
+    )
 
-        return sync_service
+    return sync_service
 
 
 def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[ValidationIssue]]:
@@ -96,9 +93,11 @@ def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[V
 
 def display_sync_summary(knowledge: SyncReport):
     """Display a one-line summary of sync changes."""
-    total_changes = knowledge.total_changes
+    total_changes = knowledge.total
+    project_name = config.project
+
     if total_changes == 0:
-        console.print("[green]Everything up to date[/green]")
+        console.print(f"[green]Project '{project_name}': Everything up to date[/green]")
         return
 
     # Format as: "Synced X files (A new, B modified, C moved, D deleted)"
@@ -117,18 +116,20 @@ def display_sync_summary(knowledge: SyncReport):
     if del_count:
         changes.append(f"[red]{del_count} deleted[/red]")
 
-    console.print(f"Synced {total_changes} files ({', '.join(changes)})")
+    console.print(f"Project '{project_name}': Synced {total_changes} files ({', '.join(changes)})")
 
 
 def display_detailed_sync_results(knowledge: SyncReport):
     """Display detailed sync results with trees."""
-    if knowledge.total_changes == 0:
-        console.print("\n[green]Everything up to date[/green]")
+    project_name = config.project
+
+    if knowledge.total == 0:
+        console.print(f"\n[green]Project '{project_name}': Everything up to date[/green]")
         return
 
-    console.print("\n[bold]Sync Results[/bold]")
+    console.print(f"\n[bold]Sync Results for Project '{project_name}'[/bold]")
 
-    if knowledge.total_changes > 0:
+    if knowledge.total > 0:
         knowledge_tree = Tree("[bold]Knowledge Files[/bold]")
         if knowledge.new:
             created = knowledge_tree.add("[green]Created[/green]")
@@ -152,22 +153,54 @@ def display_detailed_sync_results(knowledge: SyncReport):
         console.print(knowledge_tree)
 
 
-async def run_sync(verbose: bool = False, watch: bool = False):
+async def run_sync(verbose: bool = False, watch: bool = False, console_status: bool = False):
     """Run sync operation."""
+    import time
+
+    start_time = time.time()
+
+    logger.info(
+        "Sync command started",
+        project=config.project,
+        watch_mode=watch,
+        verbose=verbose,
+        directory=str(config.home),
+    )
+
     sync_service = await get_sync_service()
 
     # Start watching if requested
     if watch:
+        logger.info("Starting watch service after initial sync")
         watch_service = WatchService(
             sync_service=sync_service,
             file_service=sync_service.entity_service.file_service,
             config=config,
         )
-        await watch_service.handle_changes(config.home)
+
+        # full sync - no progress bars in watch mode
+        await sync_service.sync(config.home)
+
+        # watch changes
         await watch_service.run()  # pragma: no cover
     else:
         # one time sync
+        logger.info("Running one-time sync")
         knowledge_changes = await sync_service.sync(config.home)
+
+        # Log results
+        duration_ms = int((time.time() - start_time) * 1000)
+        logger.info(
+            "Sync command completed",
+            project=config.project,
+            total_changes=knowledge_changes.total,
+            new_files=len(knowledge_changes.new),
+            modified_files=len(knowledge_changes.modified),
+            deleted_files=len(knowledge_changes.deleted),
+            moved_files=len(knowledge_changes.moves),
+            duration_ms=duration_ms,
+        )
+
         # Display results
         if verbose:
             display_detailed_sync_results(knowledge_changes)
@@ -192,12 +225,24 @@ def sync(
 ) -> None:
     """Sync knowledge files with the database."""
     try:
+        # Show which project we're syncing
+        if not watch:  # Don't show in watch mode as it would break the UI
+            typer.echo(f"Syncing project: {config.project}")
+            typer.echo(f"Project path: {config.home}")
+
         # Run sync
         asyncio.run(run_sync(verbose=verbose, watch=watch))
 
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
-            logger.exception("Sync failed")
+            logger.exception(
+                "Sync command failed",
+                f"project={config.project},"
+                f"error={str(e)},"
+                f"error_type={type(e).__name__},"
+                f"watch_mode={watch},"
+                f"directory={str(config.home)}",
+            )
             typer.echo(f"Error during sync: {e}", err=True)
             raise typer.Exit(1)
         raise

src/basic_memory/cli/commands/tool.py

@@ -0,0 +1,270 @@
+"""CLI tool commands for Basic Memory."""
+
+import asyncio
+import sys
+from typing import Annotated, List, Optional
+
+import typer
+from loguru import logger
+from rich import print as rprint
+
+from basic_memory.cli.app import app
+
+# Import prompts
+from basic_memory.mcp.prompts.continue_conversation import (
+    continue_conversation as mcp_continue_conversation,
+)
+from basic_memory.mcp.prompts.recent_activity import (
+    recent_activity_prompt as recent_activity_prompt,
+)
+from basic_memory.mcp.tools import build_context as mcp_build_context
+from basic_memory.mcp.tools import read_note as mcp_read_note
+from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
+from basic_memory.mcp.tools import search_notes as mcp_search
+from basic_memory.mcp.tools import write_note as mcp_write_note
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import MemoryUrl
+from basic_memory.schemas.search import SearchItemType
+
+tool_app = typer.Typer()
+app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
+
+
+@tool_app.command()
+def write_note(
+    title: Annotated[str, typer.Option(help="The title of the note")],
+    folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    content: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The content of the note. If not provided, content will be read from stdin. This allows piping content from other commands, e.g.: cat file.md | basic-memory tools write-note"
+        ),
+    ] = None,
+    tags: Annotated[
+        Optional[List[str]], typer.Option(help="A list of tags to apply to the note")
+    ] = None,
+):
+    """Create or update a markdown note. Content can be provided as an argument or read from stdin.
+
+    Content can be provided in two ways:
+    1. Using the --content parameter
+    2. Piping content through stdin (if --content is not provided)
+
+    Examples:
+
+    # Using content parameter
+    basic-memory tools write-note --title "My Note" --folder "notes" --content "Note content"
+
+    # Using stdin pipe
+    echo "# My Note Content" | basic-memory tools write-note --title "My Note" --folder "notes"
+
+    # Using heredoc
+    cat << EOF | basic-memory tools write-note --title "My Note" --folder "notes"
+    # My Document
+
+    This is my document content.
+
+    - Point 1
+    - Point 2
+    EOF
+
+    # Reading from a file
+    cat document.md | basic-memory tools write-note --title "Document" --folder "docs"
+    """
+    try:
+        # If content is not provided, read from stdin
+        if content is None:
+            # Check if we're getting data from a pipe or redirect
+            if not sys.stdin.isatty():
+                content = sys.stdin.read()
+            else:  # pragma: no cover
+                # If stdin is a terminal (no pipe/redirect), inform the user
+                typer.echo(
+                    "No content provided. Please provide content via --content or by piping to stdin.",
+                    err=True,
+                )
+                raise typer.Exit(1)
+
+        # Also check for empty content
+        if content is not None and not content.strip():
+            typer.echo("Empty content provided. Please provide non-empty content.", err=True)
+            raise typer.Exit(1)
+
+        note = asyncio.run(mcp_write_note(title, content, folder, tags))
+        rprint(note)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during write_note: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def read_note(identifier: str, page: int = 1, page_size: int = 10):
+    """Read a markdown note from the knowledge base."""
+    try:
+        note = asyncio.run(mcp_read_note(identifier, page, page_size))
+        rprint(note)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during read_note: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def build_context(
+    url: MemoryUrl,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+):
+    """Get context needed to continue a discussion."""
+    try:
+        context = asyncio.run(
+            mcp_build_context(
+                url=url,
+                depth=depth,
+                timeframe=timeframe,
+                page=page,
+                page_size=page_size,
+                max_related=max_related,
+            )
+        )
+        # Use json module for more controlled serialization
+        import json
+
+        context_dict = context.model_dump(exclude_none=True)
+        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during build_context: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def recent_activity(
+    type: Annotated[Optional[List[SearchItemType]], typer.Option()] = None,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+):
+    """Get recent activity across the knowledge base."""
+    try:
+        context = asyncio.run(
+            mcp_recent_activity(
+                type=type,  # pyright: ignore [reportArgumentType]
+                depth=depth,
+                timeframe=timeframe,
+                page=page,
+                page_size=page_size,
+                max_related=max_related,
+            )
+        )
+        # Use json module for more controlled serialization
+        import json
+
+        context_dict = context.model_dump(exclude_none=True)
+        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during build_context: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command("search-notes")
+def search_notes(
+    query: str,
+    permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
+    title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
+    after_date: Annotated[
+        Optional[str],
+        typer.Option("--after_date", help="Search results after date, eg. '2d', '1 week'"),
+    ] = None,
+    page: int = 1,
+    page_size: int = 10,
+):
+    """Search across all content in the knowledge base."""
+    if permalink and title:  # pragma: no cover
+        print("Cannot search both permalink and title")
+        raise typer.Abort()
+
+    try:
+        if permalink and title:  # pragma: no cover
+            typer.echo(
+                "Use either --permalink or --title, not both. Exiting.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        # set search type
+        search_type = ("permalink" if permalink else None,)
+        search_type = ("permalink_match" if permalink and "*" in query else None,)
+        search_type = ("title" if title else None,)
+        search_type = "text" if search_type is None else search_type
+
+        results = asyncio.run(
+            mcp_search(
+                query,
+                search_type=search_type,
+                page=page,
+                after_date=after_date,
+                page_size=page_size,
+            )
+        )
+        # Use json module for more controlled serialization
+        import json
+
+        results_dict = results.model_dump(exclude_none=True)
+        print(json.dumps(results_dict, indent=2, ensure_ascii=True, default=str))
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception("Error during search", e)
+            typer.echo(f"Error during search: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command(name="continue-conversation")
+def continue_conversation(
+    topic: Annotated[Optional[str], typer.Option(help="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[str], typer.Option(help="How far back to look for activity")
+    ] = None,
+):
+    """Prompt to continue a previous conversation or work session."""
+    try:
+        # Prompt functions return formatted strings directly
+        session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
+        rprint(session)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception("Error continuing conversation", e)
+            typer.echo(f"Error continuing conversation: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+# @tool_app.command(name="show-recent-activity")
+# def show_recent_activity(
+#     timeframe: Annotated[
+#         str, typer.Option(help="How far back to look for activity")
+#     ] = "7d",
+# ):
+#     """Prompt to show recent activity."""
+#     try:
+#         # Prompt functions return formatted strings directly
+#         session = asyncio.run(recent_activity_prompt(timeframe=timeframe))
+#         rprint(session)
+#     except Exception as e:  # pragma: no cover
+#         if not isinstance(e, typer.Exit):
+#             logger.exception("Error continuing conversation", e)
+#             typer.echo(f"Error continuing conversation: {e}", err=True)
+#             raise typer.Exit(1)
+#         raise

src/basic_memory/cli/main.py

@@ -1,14 +1,26 @@
 """Main CLI entry point for basic-memory."""  # pragma: no cover
 
 from basic_memory.cli.app import app  # pragma: no cover
-from basic_memory.utils import setup_logging  # pragma: no cover
 
 # Register commands
-from basic_memory.cli.commands import status, sync, db, import_memory_json, mcp  # noqa: F401  # pragma: no cover
-
-
-# Set up logging when module is imported
-setup_logging(log_file=".basic-memory/basic-memory-cli.log")  # pragma: no cover
+from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
+    db,
+    import_chatgpt,
+    import_claude_conversations,
+    import_claude_projects,
+    import_memory_json,
+    mcp,
+    project,
+    status,
+    sync,
+    tool,
+)
+from basic_memory.config import config
+from basic_memory.services.initialization import ensure_initialization
 
 if __name__ == "__main__":  # pragma: no cover
+    # Run initialization if we are starting as a module
+    ensure_initialization(config)
+
+    # start the app
     app()

src/basic_memory/config.py

@@ -1,17 +1,29 @@
 """Configuration management for basic-memory."""
 
+import json
+import os
 from pathlib import Path
+from typing import Any, Dict, Literal, Optional
 
+from loguru import logger
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+import basic_memory
+from basic_memory.utils import setup_logging
+
 DATABASE_NAME = "memory.db"
 DATA_DIR_NAME = ".basic-memory"
+CONFIG_FILE_NAME = "config.json"
+
+Environment = Literal["test", "dev", "user"]
 
 
 class ProjectConfig(BaseSettings):
     """Configuration for a specific basic-memory project."""
 
+    env: Environment = Field(default="dev", description="Environment name")
+
     # Default to ~/basic-memory but allow override with env var: BASIC_MEMORY_HOME
     home: Path = Field(
         default_factory=lambda: Path.home() / "basic-memory",
@@ -23,10 +35,14 @@ class ProjectConfig(BaseSettings):
 
     # Watch service configuration
     sync_delay: int = Field(
-        default=500, description="Milliseconds to wait after changes before syncing", gt=0
+        default=1000, description="Milliseconds to wait after changes before syncing", gt=0
     )
 
-    log_level: str = "INFO"
+    # update permalinks on move
+    update_permalinks_on_move: bool = Field(
+        default=False,
+        description="Whether to update permalinks when files are moved or renamed. default (False)",
+    )
 
     model_config = SettingsConfigDict(
         env_prefix="BASIC_MEMORY_",
@@ -53,5 +69,214 @@ class ProjectConfig(BaseSettings):
         return v
 
 
-# Load project config
-config = ProjectConfig()
+class BasicMemoryConfig(BaseSettings):
+    """Pydantic model for Basic Memory global configuration."""
+
+    projects: Dict[str, str] = Field(
+        default_factory=lambda: {"main": str(Path.home() / "basic-memory")},
+        description="Mapping of project names to their filesystem paths",
+    )
+    default_project: str = Field(
+        default="main",
+        description="Name of the default project to use",
+    )
+
+    log_level: str = "INFO"
+
+    update_permalinks_on_move: bool = Field(
+        default=False,
+        description="Whether to update permalinks when files are moved or renamed. default (False)",
+    )
+
+    sync_changes: bool = Field(
+        default=True,
+        description="Whether to sync changes in real time. default (True)",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="BASIC_MEMORY_",
+        extra="ignore",
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        """Ensure configuration is valid after initialization."""
+        # Ensure main project exists
+        if "main" not in self.projects:
+            self.projects["main"] = str(Path.home() / "basic-memory")
+
+        # Ensure default project is valid
+        if self.default_project not in self.projects:
+            self.default_project = "main"
+
+
+class ConfigManager:
+    """Manages Basic Memory configuration."""
+
+    def __init__(self) -> None:
+        """Initialize the configuration manager."""
+        self.config_dir = Path.home() / DATA_DIR_NAME
+        self.config_file = self.config_dir / CONFIG_FILE_NAME
+
+        # Ensure config directory exists
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Load or create configuration
+        self.config = self.load_config()
+
+    def load_config(self) -> BasicMemoryConfig:
+        """Load configuration from file or create default."""
+        if self.config_file.exists():
+            try:
+                data = json.loads(self.config_file.read_text(encoding="utf-8"))
+                return BasicMemoryConfig(**data)
+            except Exception as e:
+                logger.error(f"Failed to load config: {e}")
+                config = BasicMemoryConfig()
+                self.save_config(config)
+                return config
+        else:
+            config = BasicMemoryConfig()
+            self.save_config(config)
+            return config
+
+    def save_config(self, config: BasicMemoryConfig) -> None:
+        """Save configuration to file."""
+        try:
+            self.config_file.write_text(json.dumps(config.model_dump(), indent=2))
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Failed to save config: {e}")
+
+    @property
+    def projects(self) -> Dict[str, str]:
+        """Get all configured projects."""
+        return self.config.projects.copy()
+
+    @property
+    def default_project(self) -> str:
+        """Get the default project name."""
+        return self.config.default_project
+
+    def get_project_path(self, project_name: Optional[str] = None) -> Path:
+        """Get the path for a specific project or the default project."""
+        name = project_name or self.config.default_project
+
+        # Check if specified in environment variable
+        if not project_name and "BASIC_MEMORY_PROJECT" in os.environ:
+            name = os.environ["BASIC_MEMORY_PROJECT"]
+
+        if name not in self.config.projects:
+            raise ValueError(f"Project '{name}' not found in configuration")
+
+        return Path(self.config.projects[name])
+
+    def add_project(self, name: str, path: str) -> None:
+        """Add a new project to the configuration."""
+        if name in self.config.projects:
+            raise ValueError(f"Project '{name}' already exists")
+
+        # Ensure the path exists
+        project_path = Path(path)
+        project_path.mkdir(parents=True, exist_ok=True)
+
+        self.config.projects[name] = str(project_path)
+        self.save_config(self.config)
+
+    def remove_project(self, name: str) -> None:
+        """Remove a project from the configuration."""
+        if name not in self.config.projects:
+            raise ValueError(f"Project '{name}' not found")
+
+        if name == self.config.default_project:
+            raise ValueError(f"Cannot remove the default project '{name}'")
+
+        del self.config.projects[name]
+        self.save_config(self.config)
+
+    def set_default_project(self, name: str) -> None:
+        """Set the default project."""
+        if name not in self.config.projects:  # pragma: no cover
+            raise ValueError(f"Project '{name}' not found")
+
+        self.config.default_project = name
+        self.save_config(self.config)
+
+
+def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
+    """Get a project configuration for the specified project."""
+    config_manager = ConfigManager()
+
+    # Get project name from environment variable or use provided name or default
+    actual_project_name = os.environ.get(
+        "BASIC_MEMORY_PROJECT", project_name or config_manager.default_project
+    )
+
+    update_permalinks_on_move = config_manager.load_config().update_permalinks_on_move
+    try:
+        project_path = config_manager.get_project_path(actual_project_name)
+        return ProjectConfig(
+            home=project_path,
+            project=actual_project_name,
+            update_permalinks_on_move=update_permalinks_on_move,
+        )
+    except ValueError:  # pragma: no cover
+        logger.warning(f"Project '{actual_project_name}' not found, using default")
+        project_path = config_manager.get_project_path(config_manager.default_project)
+        return ProjectConfig(home=project_path, project=config_manager.default_project)
+
+
+# Create config manager
+config_manager = ConfigManager()
+
+# Load project config for current context
+config = get_project_config()
+
+# setup logging to a single log file in user home directory
+user_home = Path.home()
+log_dir = user_home / DATA_DIR_NAME
+log_dir.mkdir(parents=True, exist_ok=True)
+
+
+def get_process_name():  # pragma: no cover
+    """
+    get the type of process for logging
+    """
+    import sys
+
+    if "sync" in sys.argv:
+        return "sync"
+    elif "mcp" in sys.argv:
+        return "mcp"
+    elif "cli" in sys.argv:
+        return "cli"
+    else:
+        return "api"
+
+
+process_name = get_process_name()
+
+# Global flag to track if logging has been set up
+_LOGGING_SETUP = False
+
+
+def setup_basic_memory_logging():  # pragma: no cover
+    """Set up logging for basic-memory, ensuring it only happens once."""
+    global _LOGGING_SETUP
+    if _LOGGING_SETUP:
+        # We can't log before logging is set up
+        # print("Skipping duplicate logging setup")
+        return
+
+    setup_logging(
+        env=config.env,
+        home_dir=user_home,  # Use user home for logs
+        log_level=config_manager.load_config().log_level,
+        log_file=f"{DATA_DIR_NAME}/basic-memory-{process_name}.log",
+        console=False,
+    )
+
+    logger.info(f"Basic Memory {basic_memory.__version__} (Project: {config.project})")
+    _LOGGING_SETUP = True
+
+
+# Set up logging
+setup_basic_memory_logging()

src/basic_memory/db.py

@@ -4,6 +4,11 @@ from enum import Enum, auto
 from pathlib import Path
 from typing import AsyncGenerator, Optional
 
+
+from basic_memory.config import ProjectConfig
+from alembic import command
+from alembic.config import Config
+
 from loguru import logger
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import (
@@ -14,8 +19,7 @@ from sqlalchemy.ext.asyncio import (
     async_scoped_session,
 )
 
-from basic_memory.models import Base
-from basic_memory.models.search import CREATE_SEARCH_INDEX
+from basic_memory.repository.search_repository import SearchRepository
 
 # Module level state
 _engine: Optional[AsyncEngine] = None
@@ -35,7 +39,7 @@ class DatabaseType(Enum):
             logger.info("Using in-memory SQLite database")
             return "sqlite+aiosqlite://"
 
-        return f"sqlite+aiosqlite:///{db_path}"
+        return f"sqlite+aiosqlite:///{db_path}"  # pragma: no cover
 
 
 def get_scoped_session_factory(
@@ -69,24 +73,6 @@ async def scoped_session(
         await factory.remove()
 
 
-async def init_db() -> None:
-    """Initialize database with required tables."""
-    if _session_maker is None:  # pragma: no cover
-        raise RuntimeError("Database session maker not initialized")
-
-    logger.info("Initializing database...")
-
-    async with scoped_session(_session_maker) as session:
-        await session.execute(text("PRAGMA foreign_keys=ON"))
-        conn = await session.connection()
-        await conn.run_sync(Base.metadata.create_all)
-
-        # recreate search index
-        await session.execute(CREATE_SEARCH_INDEX)
-
-        await session.commit()
-
-
 async def get_or_create_db(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.FILESYSTEM,
@@ -100,11 +86,16 @@ async def get_or_create_db(
         _engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 
-        # Initialize database
-        await init_db()
+    # These checks should never fail since we just created the engine and session maker
+    # if they were None, but we'll check anyway for the type checker
+    if _engine is None:
+        logger.error("Failed to create database engine", db_path=str(db_path))
+        raise RuntimeError("Database engine initialization failed")
+
+    if _session_maker is None:
+        logger.error("Failed to create session maker", db_path=str(db_path))
+        raise RuntimeError("Session maker initialization failed")
 
-    assert _engine is not None  # for type checker
-    assert _session_maker is not None  # for type checker
     return _engine, _session_maker
 
 
@@ -122,7 +113,6 @@ async def shutdown_db() -> None:  # pragma: no cover
 async def engine_session_factory(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.MEMORY,
-    init: bool = True,
 ) -> AsyncGenerator[tuple[AsyncEngine, async_sessionmaker[AsyncSession]], None]:
     """Create engine and session factory.
 
@@ -139,14 +129,50 @@ async def engine_session_factory(
     try:
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 
-        if init:
-            await init_db()
+        # Verify that engine and session maker are initialized
+        if _engine is None:  # pragma: no cover
+            logger.error("Database engine is None in engine_session_factory")
+            raise RuntimeError("Database engine initialization failed")
+
+        if _session_maker is None:  # pragma: no cover
+            logger.error("Session maker is None in engine_session_factory")
+            raise RuntimeError("Session maker initialization failed")
 
-        assert _engine is not None  # for type checker
-        assert _session_maker is not None  # for type checker
         yield _engine, _session_maker
     finally:
         if _engine:
             await _engine.dispose()
             _engine = None
             _session_maker = None
+
+
+async def run_migrations(
+    app_config: ProjectConfig, database_type=DatabaseType.FILESYSTEM
+):  # pragma: no cover
+    """Run any pending alembic migrations."""
+    logger.info("Running database migrations...")
+    try:
+        # Get the absolute path to the alembic directory relative to this file
+        alembic_dir = Path(__file__).parent / "alembic"
+        config = Config()
+
+        # Set required Alembic config options programmatically
+        config.set_main_option("script_location", str(alembic_dir))
+        config.set_main_option(
+            "file_template",
+            "%%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s",
+        )
+        config.set_main_option("timezone", "UTC")
+        config.set_main_option("revision_environment", "false")
+        config.set_main_option(
+            "sqlalchemy.url", DatabaseType.get_db_url(app_config.database_path, database_type)
+        )
+
+        command.upgrade(config, "head")
+        logger.info("Migrations completed successfully")
+
+        _, session_maker = await get_or_create_db(app_config.database_path, database_type)
+        await SearchRepository(session_maker).init_search_index()
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error running migrations: {e}")
+        raise

src/basic_memory/deps.py

@@ -15,6 +15,7 @@ from basic_memory.markdown import EntityParser
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.observation_repository import ObservationRepository
+from basic_memory.repository.project_info_repository import ProjectInfoRepository
 from basic_memory.repository.relation_repository import RelationRepository
 from basic_memory.repository.search_repository import SearchRepository
 from basic_memory.services import (
@@ -43,7 +44,8 @@ async def get_engine_factory(
     project_config: ProjectConfigDep,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
     """Get engine and session maker."""
-    return await db.get_or_create_db(project_config.database_path)
+    engine, session_maker = await db.get_or_create_db(project_config.database_path)
+    return engine, session_maker
 
 
 EngineFactoryDep = Annotated[
@@ -103,6 +105,15 @@ async def get_search_repository(
 SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
 
 
+def get_project_info_repository(
+    session_maker: SessionMakerDep,
+):
+    """Dependency for StatsRepository."""
+    return ProjectInfoRepository(session_maker)
+
+
+ProjectInfoRepositoryDep = Annotated[ProjectInfoRepository, Depends(get_project_info_repository)]
+
 ## services
 
 

src/basic_memory/file_utils.py

@@ -2,11 +2,13 @@
 
 import hashlib
 from pathlib import Path
-from typing import Dict, Any
+from typing import Any, Dict, Union
 
 import yaml
 from loguru import logger
 
+from basic_memory.utils import FilePath
+
 
 class FileError(Exception):
     """Base exception for file operations."""
@@ -26,12 +28,12 @@ class ParseError(FileError):
     pass
 
 
-async def compute_checksum(content: str) -> str:
+async def compute_checksum(content: Union[str, bytes]) -> str:
     """
     Compute SHA-256 checksum of content.
 
     Args:
-        content: Text content to hash
+        content: Content to hash (either text string or bytes)
 
     Returns:
         SHA-256 hex digest
@@ -40,48 +42,55 @@ async def compute_checksum(content: str) -> str:
         FileError: If checksum computation fails
     """
     try:
-        return hashlib.sha256(content.encode()).hexdigest()
+        if isinstance(content, str):
+            content = content.encode()
+        return hashlib.sha256(content).hexdigest()
     except Exception as e:  # pragma: no cover
         logger.error(f"Failed to compute checksum: {e}")
         raise FileError(f"Failed to compute checksum: {e}")
 
 
-async def ensure_directory(path: Path) -> None:
+async def ensure_directory(path: FilePath) -> None:
     """
     Ensure directory exists, creating if necessary.
 
     Args:
-        path: Directory path to ensure
+        path: Directory path to ensure (Path or string)
 
     Raises:
         FileWriteError: If directory creation fails
     """
     try:
-        path.mkdir(parents=True, exist_ok=True)
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        path_obj.mkdir(parents=True, exist_ok=True)
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to create directory: {path}: {e}")
+        logger.error("Failed to create directory", path=str(path), error=str(e))
         raise FileWriteError(f"Failed to create directory {path}: {e}")
 
 
-async def write_file_atomic(path: Path, content: str) -> None:
+async def write_file_atomic(path: FilePath, content: str) -> None:
     """
     Write file with atomic operation using temporary file.
 
     Args:
-        path: Target file path
+        path: Target file path (Path or string)
         content: Content to write
 
     Raises:
         FileWriteError: If write operation fails
     """
-    temp_path = path.with_suffix(".tmp")
+    # Convert string to Path if needed
+    path_obj = Path(path) if isinstance(path, str) else path
+    temp_path = path_obj.with_suffix(".tmp")
+
     try:
-        temp_path.write_text(content)
-        temp_path.replace(path)
-        logger.debug(f"wrote file: {path}")
+        temp_path.write_text(content, encoding="utf-8")
+        temp_path.replace(path_obj)
+        logger.debug("Wrote file atomically", path=str(path_obj), content_length=len(content))
     except Exception as e:  # pragma: no cover
         temp_path.unlink(missing_ok=True)
-        logger.error(f"Failed to write file: {path}: {e}")
+        logger.error("Failed to write file", path=str(path_obj), error=str(e))
         raise FileWriteError(f"Failed to write file {path}: {e}")
 
 
@@ -95,6 +104,9 @@ def has_frontmatter(content: str) -> bool:
     Returns:
         True if content has valid frontmatter markers (---), False otherwise
     """
+    if not content:
+        return False
+
     content = content.strip()
     if not content.startswith("---"):
         return False
@@ -171,7 +183,7 @@ def remove_frontmatter(content: str) -> str:
     return parts[2].strip()
 
 
-async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
+async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
     """Update frontmatter fields in a file while preserving all content.
 
     Only modifies the frontmatter section, leaving all content untouched.
@@ -179,7 +191,7 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
     Returns checksum of updated file.
 
     Args:
-        path: Path to markdown file
+        path: Path to markdown file (Path or string)
         updates: Dict of frontmatter fields to update
 
     Returns:
@@ -190,8 +202,11 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         ParseError: If frontmatter parsing fails
     """
     try:
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+
         # Read current content
-        content = path.read_text()
+        content = path_obj.read_text(encoding="utf-8")
 
         # Parse current frontmatter
         current_fm = {}
@@ -203,12 +218,18 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         new_fm = {**current_fm, **updates}
 
         # Write new file with updated frontmatter
-        yaml_fm = yaml.dump(new_fm, sort_keys=False)
+        yaml_fm = yaml.dump(new_fm, sort_keys=False, allow_unicode=True)
         final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
 
-        await write_file_atomic(path, final_content)
+        logger.debug("Updating frontmatter", path=str(path_obj), update_keys=list(updates.keys()))
+
+        await write_file_atomic(path_obj, final_content)
         return await compute_checksum(final_content)
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to update frontmatter in {path}: {e}")
+        logger.error(
+            "Failed to update frontmatter",
+            path=str(path) if isinstance(path, (str, Path)) else "<unknown>",
+            error=str(e),
+        )
         raise FileError(f"Failed to update frontmatter: {e}")

src/basic_memory/markdown/entity_parser.py

@@ -4,21 +4,22 @@ Uses markdown-it with plugins to parse structured data from markdown content.
 """
 
 from dataclasses import dataclass, field
-from pathlib import Path
 from datetime import datetime
+from pathlib import Path
 from typing import Any, Optional
-import dateparser
 
-from markdown_it import MarkdownIt
+import dateparser
 import frontmatter
+from markdown_it import MarkdownIt
 
 from basic_memory.markdown.plugins import observation_plugin, relation_plugin
 from basic_memory.markdown.schemas import (
-    EntityMarkdown,
     EntityFrontmatter,
+    EntityMarkdown,
     Observation,
     Relation,
 )
+from basic_memory.utils import parse_tags
 
 md = MarkdownIt().use(observation_plugin).use(relation_plugin)
 
@@ -56,11 +57,11 @@ def parse(content: str) -> EntityContent:
     )
 
 
-def parse_tags(tags: Any) -> list[str]:
-    """Parse tags into list of strings."""
-    if isinstance(tags, (list, tuple)):
-        return [str(t).strip() for t in tags if str(t).strip()]
-    return [t.strip() for t in tags.split(",") if t.strip()]
+# def parse_tags(tags: Any) -> list[str]:
+#     """Parse tags into list of strings."""
+#     if isinstance(tags, (list, tuple)):
+#         return [str(t).strip() for t in tags if str(t).strip()]
+#     return [t.strip() for t in tags.split(",") if t.strip()]
 
 
 class EntityParser:
@@ -88,28 +89,39 @@ class EntityParser:
                 return parsed
         return None
 
-    async def parse_file(self, file_path: Path) -> EntityMarkdown:
+    async def parse_file(self, path: Path | str) -> EntityMarkdown:
         """Parse markdown file into EntityMarkdown."""
 
-        absolute_path = self.base_path / file_path
-        # Parse frontmatter and content using python-frontmatter
-        post = frontmatter.load(str(absolute_path))
+        # TODO move to api endpoint to check if absolute path was requested
+        # Check if the path is already absolute
+        if (
+            isinstance(path, Path)
+            and path.is_absolute()
+            or (isinstance(path, str) and Path(path).is_absolute())
+        ):
+            absolute_path = Path(path)
+        else:
+            absolute_path = self.base_path / path
 
+        # Parse frontmatter and content using python-frontmatter
+        file_content = absolute_path.read_text(encoding="utf-8")
+        return await self.parse_file_content(absolute_path, file_content)
+
+    async def parse_file_content(self, absolute_path, file_content):
+        post = frontmatter.loads(file_content)
         # Extract file stat info
         file_stats = absolute_path.stat()
-
         metadata = post.metadata
-        metadata["title"] = post.metadata.get("title", file_path.name)
+        metadata["title"] = post.metadata.get("title", absolute_path.stem)
         metadata["type"] = post.metadata.get("type", "note")
-        metadata["tags"] = parse_tags(post.metadata.get("tags", []))
-
+        tags = parse_tags(post.metadata.get("tags", []))  # pyright: ignore
+        if tags:
+            metadata["tags"] = tags
         # frontmatter
         entity_frontmatter = EntityFrontmatter(
             metadata=post.metadata,
         )
-
         entity_content = parse(post.content)
-
         return EntityMarkdown(
             frontmatter=entity_frontmatter,
             content=post.content,

src/basic_memory/markdown/markdown_processor.py

@@ -83,7 +83,7 @@ class MarkdownProcessor:
         """
         # Dirty check if needed
         if expected_checksum is not None:
-            current_content = path.read_text()
+            current_content = path.read_text(encoding="utf-8")
             current_checksum = await file_utils.compute_checksum(current_content)
             if current_checksum != expected_checksum:
                 raise DirtyFileError(f"File {path} has been modified")

src/basic_memory/markdown/schemas.py

@@ -42,7 +42,7 @@ class EntityFrontmatter(BaseModel):
 
     @property
     def tags(self) -> List[str]:
-        return self.metadata.get("tags") if self.metadata else []  # pyright: ignore
+        return self.metadata.get("tags") if self.metadata else None  # pyright: ignore
 
     @property
     def title(self) -> str:

src/basic_memory/markdown/utils.py

@@ -1,13 +1,14 @@
 """Utilities for converting between markdown and entity models."""
 
 from pathlib import Path
-from typing import Optional, Any
+from typing import Any, Optional
 
 from frontmatter import Post
 
+from basic_memory.file_utils import has_frontmatter, remove_frontmatter, parse_frontmatter
 from basic_memory.markdown import EntityMarkdown
-from basic_memory.models import Entity, Observation as ObservationModel
-from basic_memory.utils import generate_permalink
+from basic_memory.models import Entity
+from basic_memory.models import Observation as ObservationModel
 
 
 def entity_model_from_markdown(
@@ -31,16 +32,13 @@ def entity_model_from_markdown(
     if not markdown.created or not markdown.modified:  # pragma: no cover
         raise ValueError("Both created and modified dates are required in markdown")
 
-    # Generate permalink if not provided
-    permalink = markdown.frontmatter.permalink or generate_permalink(file_path)
-
     # Create or update entity
     model = entity or Entity()
 
     # Update basic fields
     model.title = markdown.frontmatter.title
     model.entity_type = markdown.frontmatter.type
-    model.permalink = permalink
+    model.permalink = markdown.frontmatter.permalink
     model.file_path = str(file_path)
     model.content_type = "text/markdown"
     model.created_at = markdown.created
@@ -76,18 +74,33 @@ async def schema_to_markdown(schema: Any) -> Post:
     """
     # Extract content and metadata
     content = schema.content or ""
-    frontmatter_metadata = dict(schema.entity_metadata or {})
+    entity_metadata = dict(schema.entity_metadata or {})
+
+    # if the content contains frontmatter, remove it and merge
+    if has_frontmatter(content):
+        content_frontmatter = parse_frontmatter(content)
+        content = remove_frontmatter(content)
+
+        # Merge content frontmatter with entity metadata
+        # (entity_metadata takes precedence for conflicts)
+        content_frontmatter.update(entity_metadata)
+        entity_metadata = content_frontmatter
 
     # Remove special fields for ordered frontmatter
     for field in ["type", "title", "permalink"]:
-        frontmatter_metadata.pop(field, None)
+        entity_metadata.pop(field, None)
 
-    # Create Post with ordered fields
+    # Create Post with fields ordered by insert order
     post = Post(
         content,
         title=schema.title,
         type=schema.entity_type,
-        permalink=schema.permalink,
-        **frontmatter_metadata,
     )
+    # set the permalink if passed in
+    if schema.permalink:
+        post.metadata["permalink"] = schema.permalink
+
+    if entity_metadata:
+        post.metadata.update(entity_metadata)
+
     return post

src/basic_memory/mcp/main.py

@@ -0,0 +1,24 @@
+"""Main MCP entrypoint for Basic Memory.
+
+Creates and configures the shared MCP instance and handles server startup.
+"""
+
+from loguru import logger  # pragma: no cover
+
+from basic_memory.config import config  # pragma: no cover
+
+# Import shared mcp instance
+from basic_memory.mcp.server import mcp  # pragma: no cover
+
+# Import tools to register them
+import basic_memory.mcp.tools  # noqa: F401 # pragma: no cover
+
+# Import prompts to register them
+import basic_memory.mcp.prompts  # noqa: F401 # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    home_dir = config.home
+    logger.info("Starting Basic Memory MCP server")
+    logger.info(f"Home directory: {home_dir}")
+    mcp.run()

src/basic_memory/mcp/prompts/__init__.py

@@ -0,0 +1,19 @@
+"""Basic Memory MCP prompts.
+
+Prompts are a special type of tool that returns a string response
+formatted for a user to read, typically invoking one or more tools
+and transforming their results into user-friendly text.
+"""
+
+# Import individual prompt modules to register them with the MCP server
+from basic_memory.mcp.prompts import continue_conversation
+from basic_memory.mcp.prompts import recent_activity
+from basic_memory.mcp.prompts import search
+from basic_memory.mcp.prompts import ai_assistant_guide
+
+__all__ = [
+    "ai_assistant_guide",
+    "continue_conversation",
+    "recent_activity",
+    "search",
+]

src/basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from basic_memory.mcp.server import mcp
+from loguru import logger
+
+
+@mcp.resource(
+    uri="memory://ai_assistant_guide",
+    name="ai assistant guide",
+    description="Give an AI assistant guidance on how to use Basic Memory tools effectively",
+)
+def ai_assistant_guide() -> str:
+    """Return a concise guide on Basic Memory tools and how to use them.
+
+    Args:
+        focus: Optional area to focus on ("writing", "context", "search", etc.)
+
+    Returns:
+        A focused guide on Basic Memory usage.
+    """
+    logger.info("Loading AI assistant guide resource")
+    guide_doc = Path(__file__).parent.parent / "resources" / "ai_assistant_guide.md"
+    content = guide_doc.read_text(encoding="utf-8")
+    logger.info(f"Loaded AI assistant guide ({len(content)} chars)")
+    return content