basic-memory 0.7.0__tar.gz → 0.9.0__tar.gz

basic_memory-0.9.0/.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.

basic_memory-0.9.0/.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

basic_memory-0.9.0/.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.

basic_memory-0.9.0/.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?

{basic_memory-0.7.0 → basic_memory-0.9.0}/CHANGELOG.md

@@ -1,6 +1,107 @@
 # CHANGELOG
 
 
+## 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

basic_memory-0.9.0/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.

basic_memory-0.9.0/CLAUDE.md

@@ -0,0 +1,133 @@
+# 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)
+
+### 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 enviroment 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(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(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.

basic_memory-0.9.0/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing to Basic Memory
+
+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.
+
+## Getting Started
+
+### Development Environment
+
+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
+
+You can sign your commits in one of two ways:
+
+1. **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.
+
+2. **Configuring Git to automatically sign off**:
+   ```bash
+   git config --global alias.cs 'commit -s'
+   ```
+   Then use `git cs -m "Your commit message"` to commit with sign-off.
+
+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
+- **Edge Cases**: Test both normal operation and edge cases
+- **Database Testing**: Use in-memory SQLite for testing database operations
+- **Fixtures**: Use 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 for everyone. We appreciate your time and effort!

basic_memory-0.9.0/Makefile

@@ -0,0 +1,67 @@
+.PHONY: install test test-module lint clean format type-check installer-mac installer-win check
+
+install:
+	pip install -e ".[dev]"
+
+test:
+	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
+
+type-check:
+	uv run pyright
+
+clean:
+	find . -type f -name '*.pyc' -delete
+	find . -type d -name '__pycache__' -exec rm -r {} +
+	rm -rf installer/build/
+	rm -rf installer/dist/
+	rm -f rw.*.dmg
+	rm -rf dist
+	rm -rf installer/build
+	rm -rf installer/dist
+	rm -f .coverage.*
+
+format:
+	uv run ruff format .
+
+# run inspector tool
+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:
+	cd installer && uv run python setup.py bdist_win32
+
+
+update-deps:
+	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)"