basic-memory 0.14.2__tar.gz → 0.14.4__tar.gz

{basic_memory-0.14.2 → basic_memory-0.14.4}/.github/workflows/test.yml

@@ -14,11 +14,12 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest]
         python-version: [ "3.12" ]
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4
@@ -35,10 +36,18 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just
+      - name: Install just (Linux/macOS)
+        if: runner.os != 'Windows'
         run: |
           curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
 
+      - name: Install just (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # Install just using Chocolatey (pre-installed on GitHub Actions Windows runners)
+          choco install just --yes
+        shell: pwsh
+
       - name: Create virtual env
         run: |
           uv venv
@@ -54,4 +63,4 @@ jobs:
       - name: Run tests
         run: |
           uv pip install pytest pytest-cov
-          just test
+          just test

basic_memory-0.14.4/CLA.md

@@ -0,0 +1,71 @@
+# Contributor License Agreement
+
+## Copyright Assignment and License Grant
+
+By signing this Contributor License Agreement ("Agreement"), you accept and agree to the following terms and conditions
+for your present and future Contributions submitted
+to Basic Machines LLC. Except for the license granted herein to Basic Machines LLC and recipients of software
+distributed by Basic Machines LLC, you reserve all right,
+title, and interest in and to your Contributions.
+
+### 1. Definitions
+
+"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this
+Agreement with Basic Machines LLC.
+
+"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work,
+that is intentionally submitted by You to Basic
+Machines LLC for inclusion in, or documentation of, any of the products owned or managed by Basic Machines LLC (the "
+Work").
+
+### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the
+Work, and to permit persons to whom the Work is furnished to do so.
+
+### 3. Assignment of Copyright
+
+You hereby assign to Basic Machines LLC all right, title, and interest worldwide in all Copyright covering your
+Contributions. Basic Machines LLC may license the
+Contributions under any license terms, including copyleft, permissive, commercial, or proprietary licenses.
+
+### 4. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to
+make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Work.
+
+### 5. Developer Certificate of Origin
+
+By making a Contribution to this project, You certify that:
+
+(a) The Contribution was created in whole or in part by You and You have the right to submit it under this Agreement; or
+
+(b) The Contribution is based upon previous work that, to the best of Your knowledge, is covered under an appropriate
+open source license and You have the right under that
+license to submit that work with modifications, whether created in whole or in part by You, under this Agreement; or
+
+(c) The Contribution was provided directly to You by some other person who certified (a), (b) or (c) and You have not
+modified it.
+
+(d) You understand and agree that this project and the Contribution are public and that a record of the Contribution (
+including all personal information You submit with
+it, including Your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the
+open source license(s) involved.
+
+### 6. Representations
+
+You represent that you are legally entitled to grant the above license and assignment. If your employer(s) has rights to
+intellectual property that you create that
+includes your Contributions, you represent that you have received permission to make Contributions on behalf of that
+employer, or that your employer has waived such rights
+for your Contributions to Basic Machines LLC.
+
+---
+
+This Agreement is effective as of the date you first submit a Contribution to Basic Machines LLC.

basic_memory-0.14.4/CLAUDE.md

@@ -0,0 +1,171 @@
+# 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 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(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.
+
+## GitHub Integration
+
+Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
+
+### GitHub MCP Tools
+
+Using the GitHub Model Context Protocol server, Claude can now:
+
+- **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
+
+This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

{basic_memory-0.14.2 → basic_memory-0.14.4}/CONTRIBUTING.md

@@ -27,7 +27,12 @@ project and how to get started as a developer.
 
    > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
 
-3. **Run the Tests**:
+3. **Activate the Virtual Environment**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+4. **Run the Tests**:
    ```bash
    # Run all tests
    just test

{basic_memory-0.14.2 → basic_memory-0.14.4}/Dockerfile

@@ -1,5 +1,9 @@
 FROM python:3.12-slim-bookworm
 
+# Build arguments for user ID and group ID (defaults to 1000)
+ARG UID=1000
+ARG GID=1000
+
 # Copy uv from official image
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
@@ -7,6 +11,11 @@ COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 ENV PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1
 
+# Create a group and user with the provided UID/GID
+# Check if the GID already exists, if not create appgroup
+RUN (getent group ${GID} || groupadd --gid ${GID} appgroup) && \
+    useradd --uid ${UID} --gid ${GID} --create-home --shell /bin/bash appuser
+
 # Copy the project into the image
 ADD . /app
 
@@ -14,13 +23,17 @@ ADD . /app
 WORKDIR /app
 RUN uv sync --locked
 
-# Create data directory
-RUN mkdir -p /app/data
+# Create necessary directories and set ownership
+RUN mkdir -p /app/data /app/.basic-memory && \
+    chown -R appuser:${GID} /app
 
 # Set default data directory and add venv to PATH
 ENV BASIC_MEMORY_HOME=/app/data \
     PATH="/app/.venv/bin:$PATH"
 
+# Switch to the non-root user
+USER appuser
+
 # Expose port
 EXPOSE 8000
 

basic_memory-0.14.4/LEGAL_INVENTORY_GUIDE.md

@@ -0,0 +1,250 @@
+# Legal File Inventory Guide
+
+## Overview
+
+This guide documents the comprehensive file inventory script created for Basic Memory's legal documentation needs, including copyright assignments and company agreement exhibits.
+
+## Repository Analysis Summary
+
+### Repository Structure
+- **Primary Language**: Python (3,958 files)
+- **License**: GNU Affero General Public License v3.0
+- **Total Contributors**: 12 identified contributors
+- **Main Contributors**:
+  - `phernandez@basicmachines.co` / `paul@basicmachines.co` (Paul Hernandez) - 700+ commits
+  - `groksrc@gmail.com` / `groksrc@users.noreply.github.com` (Drew Cain) - 18+ commits
+  - Various AI bots and automated systems
+
+### File Type Distribution
+Based on the analysis, the repository contains:
+
+| Extension | Count | Purpose |
+|-----------|-------|---------|
+| `.py` | 3,958 | Python source code |
+| `.pyi` | 4,536 | Python type stubs (dependencies) |
+| `.pyc` | 1,435 | Compiled Python (excluded from inventory) |
+| `.md` | 34 | Documentation files |
+| `.toml` | 179 | Configuration files |
+| `.html` | 119 | Coverage reports and documentation |
+| `.txt` | 127 | Various text files |
+
+### Contributors by Email Domain
+
+**Basic Machines Contributors:**
+- `phernandez@basicmachines.co` - 547 commits (Primary maintainer)
+- `paul@basicmachines.co` / `paulmh@gmail.com` - 170 commits (Paul Hernandez)
+- `claude@basicmachines.co` - 3 commits (AI assistant)
+
+**External Contributors:**
+- `groksrc@gmail.com` / `groksrc@users.noreply.github.com` - 18 commits (Drew Cain)
+- Various one-time contributors (1-2 commits each)
+
+**Automated Systems:**
+- GitHub Actions, semantic-release, and other bots
+
+## Legal Inventory Script Features
+
+### What It Includes
+
+**Source Files:**
+- All Python source code (`.py` files)
+- Configuration files (`.toml`, `.yaml`, `.json`, etc.)
+- Documentation (`.md`, `.rst`, `.txt`)
+- Build and deployment scripts
+- Database migrations and SQL files
+- Legal and license files
+
+**Metadata for Each File:**
+- File path, size, and creation/modification dates
+- Git history (creation date, last modified, commit count)
+- Contributors and their line contributions
+- Primary author identification
+- File categorization
+- SHA-256 hash for integrity verification
+
+### What It Excludes
+
+**Generated/Build Artifacts:**
+- `__pycache__/` and `.pyc` files
+- Build directories (`build/`, `dist/`, `htmlcov/`)
+- Coverage reports and cache files
+
+**Dependencies:**
+- Virtual environment files (`.venv/`, `venv/`)
+- Third-party packages (`site-packages/`, `*.dist-info/`)
+- Lock files (`uv.lock`, `package-lock.json`)
+
+**IDE/Editor Files:**
+- `.idea/`, `.vscode/`, `.DS_Store`
+- Temporary and swap files
+
+**Version Control:**
+- `.git/` directory contents
+- Git configuration files
+
+## Usage Instructions
+
+### Basic Usage
+
+```bash
+# Generate CSV inventory (default)
+python3 legal_file_inventory.py
+
+# Generate Markdown report
+python3 legal_file_inventory.py --format markdown --output legal_report.md
+
+# Generate JSON with full metadata
+python3 legal_file_inventory.py --format json --output legal_data.json
+
+# Specify different repository path
+python3 legal_file_inventory.py --repo-path /path/to/repo --output inventory.csv
+```
+
+### Command Line Options
+
+- `--output`, `-o`: Output file path (default: `basic_memory_legal_inventory.csv`)
+- `--format`, `-f`: Output format - `csv`, `json`, or `markdown` (default: `csv`)
+- `--repo-path`, `-r`: Repository path (default: current directory)
+
+### Output Formats
+
+**CSV Format:**
+- Suitable for spreadsheet applications
+- Contains all metadata fields
+- Contributors stored as JSON string in separate column
+
+**JSON Format:**
+- Complete structured data
+- Includes summary statistics and detailed file information
+- Best for programmatic processing
+
+**Markdown Format:**
+- Human-readable report
+- Summary statistics and contributor rankings
+- Detailed table of all files
+
+## Legal Documentation Applications
+
+### Copyright Assignment Use Cases
+
+1. **Contributor Identification**: The script identifies all contributors to each file based on git blame analysis
+2. **Primary Author Recognition**: Determines the primary author of each file (contributor with most lines)
+3. **Contribution Metrics**: Provides line counts and commit counts per contributor
+4. **File Categorization**: Groups files by purpose (source code, documentation, configuration, etc.)
+
+### Company Agreement Exhibits
+
+The inventory provides comprehensive documentation of:
+
+1. **Intellectual Property Scope**: All source code files and their origins
+2. **Contributor Tracking**: Complete list of all individuals who have contributed code
+3. **File Integrity**: SHA-256 hashes for verification of file contents
+4. **Historical Documentation**: Git creation dates and modification history
+
+### Due Diligence Documentation
+
+The script generates data suitable for:
+
+1. **Legal Review**: Comprehensive file listing with contributor information
+2. **IP Audit**: Identification of all copyright holders
+3. **License Compliance**: Verification of file ownership and licensing
+4. **Asset Documentation**: Complete inventory of company code assets
+
+## Integration with Legal Processes
+
+### Recommended Workflow
+
+1. **Generate Inventory**: Run the script to create current file inventory
+2. **Legal Review**: Have legal counsel review the contributor list and file categorization
+3. **Copyright Assignment**: Use contributor data to ensure proper copyright assignments
+4. **Document Attachment**: Include inventory as exhibit in company agreements
+5. **Regular Updates**: Re-run inventory for significant releases or legal milestones
+
+### Key Legal Considerations
+
+**AGPL-3.0 License:**
+- All files are under AGPL-3.0 unless otherwise specified
+- Contributors retain copyright but license under AGPL-3.0 terms
+- Company needs proper copyright assignments for proprietary licensing
+
+**Contributor Rights:**
+- External contributors may retain rights to their contributions
+- Proper contributor license agreements (CLAs) should be in place
+- AI-generated content may have different legal status
+
+**File Categories for Legal Review:**
+- **Source Code**: Core IP, requires copyright assignment
+- **Configuration**: May contain proprietary deployment information
+- **Documentation**: Usually less sensitive but may contain trade secrets
+- **Legal/License**: Critical for compliance verification
+
+## Maintenance and Updates
+
+### When to Regenerate Inventory
+
+- Before major releases
+- During legal document preparation
+- After significant contributor additions
+- For annual compliance reviews
+- During acquisition or investment processes
+
+### Validation Steps
+
+1. Verify contributor email mapping is accurate
+2. Check that file categorization makes sense
+3. Ensure excluded files are appropriate
+4. Review contributor counts against expectations
+5. Validate file hashes for integrity
+
+## Technical Implementation Notes
+
+### Git Integration
+- Uses `git blame --line-porcelain` for detailed contributor analysis
+- Tracks file history with `git log --follow`
+- Handles renamed files and complex git histories
+
+### Performance Considerations
+- Scans repository incrementally to handle large codebases
+- Excludes binary dependencies to reduce processing time
+- Caches git operations where possible
+
+### Error Handling
+- Gracefully handles files not in git
+- Continues processing if individual files fail
+- Provides detailed error reporting
+
+## Security and Privacy
+
+### Data Sensitivity
+- Contains contributor names and email addresses
+- May reveal internal file structure and organization
+- Should be treated as confidential legal documentation
+
+### Recommended Handling
+- Limit access to legal and executive team
+- Store in secure, access-controlled systems
+- Consider redacting contributor emails for external sharing
+- Regular cleanup of generated inventory files
+
+## Troubleshooting
+
+### Common Issues
+
+**Git Not Available:**
+- Ensure git is installed and repository is initialized
+- Check that the script is run from within the repository
+
+**Permission Errors:**
+- Ensure read access to all repository files
+- Check write permissions for output directory
+
+**Large Repository Performance:**
+- Consider running on subsets of files for very large repositories
+- Use `--repo-path` to target specific subdirectories
+
+**Contributor Mapping Issues:**
+- Git usernames may not match real identities
+- Consider post-processing to normalize contributor names
+- Review .mailmap files for git identity consolidation
+
+This comprehensive legal file inventory system provides the foundation for proper intellectual property documentation and legal compliance for the Basic Memory project.