Merge origin/main into feat-project-display-name

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

Author: phernandez

.github/workflows/test.yml

@@ -1,26 +1,70 @@
 name: Tests
 
+concurrency:
+  group: bm-ci-${{ github.workflow }}-${{ github.repository }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     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-sqlite:
-    name: Test SQLite (${{ matrix.os }}, Python ${{ matrix.python-version }})
+  static-checks:
+    name: Static Checks (Python 3.12)
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - uses: extractions/setup-just@v3
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev]"
+
+      - name: Run type checks
+        run: |
+          just typecheck
+
+      - name: Run linting
+        run: |
+          just lint
+
+  test-sqlite-unit:
+    name: Test SQLite Unit (${{ matrix.os }}, Python ${{ matrix.python-version }})
     timeout-minutes: 30
+    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12", "3.13", "3.14" ]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.12"
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -46,24 +90,63 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv pip install -e ".[dev,semantic]"
+          uv pip install -e ".[dev]"
 
-      - name: Run type checks
+      - name: Run tests (SQLite Unit)
         run: |
-          just typecheck
+          just test-unit-sqlite
 
-      - name: Run linting
+  test-sqlite-integration:
+    name: Test SQLite Integration (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    timeout-minutes: 45
+    needs: [static-checks]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install uv
         run: |
-          just lint
+          pip install uv
 
-      - name: Run tests (SQLite)
+      - uses: extractions/setup-just@v3
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
         run: |
-          uv pip install pytest pytest-cov
-          just test-sqlite
+          uv pip install -e ".[dev]"
 
-  test-postgres:
-    name: Test Postgres (Python ${{ matrix.python-version }})
+      - name: Run tests (SQLite Integration)
+        run: |
+          just test-int-sqlite
+
+  test-postgres-unit:
+    name: Test Postgres Unit (Python ${{ matrix.python-version }})
     timeout-minutes: 30
+    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
@@ -95,16 +178,57 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv pip install -e ".[dev,semantic]"
+          uv pip install -e ".[dev]"
 
-      - name: Run tests (Postgres via testcontainers)
+      - name: Run tests (Postgres Unit)
         run: |
-          uv pip install pytest pytest-cov
-          just test-postgres
+          just test-unit-postgres
+
+  test-postgres-integration:
+    name: Test Postgres Integration (Python ${{ matrix.python-version }})
+    timeout-minutes: 45
+    needs: [static-checks]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12", "3.13", "3.14" ]
+    runs-on: ubuntu-latest
+
+    # Note: No services section needed - testcontainers handles Postgres in Docker
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - uses: extractions/setup-just@v3
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev]"
+
+      - name: Run tests (Postgres Integration)
+        run: |
+          just test-int-postgres
 
   test-semantic:
     name: Test Semantic (Python 3.12)
     timeout-minutes: 45
+    needs: [static-checks]
     runs-on: ubuntu-latest
 
     steps:
@@ -134,12 +258,19 @@ jobs:
 
       - name: Run tests (Semantic)
         run: |
-          uv pip install pytest pytest-cov
           just test-semantic
 
   coverage:
     name: Coverage Summary (combined, Python 3.12)
-    timeout-minutes: 30
+    timeout-minutes: 60
+    needs:
+      - static-checks
+      - test-sqlite-unit
+      - test-sqlite-integration
+      - test-postgres-unit
+      - test-postgres-integration
+      - test-semantic
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
 
     steps:
@@ -169,7 +300,6 @@ jobs:
 
       - name: Run combined coverage (SQLite + Postgres)
         run: |
-          uv pip install pytest pytest-cov
           just coverage
 
       - name: Add coverage report to job summary

README.md

@@ -418,19 +418,19 @@ basic-memory tool edit-note docs/setup --operation append --content $'\n- Added
 
 **Content Management:**
 ```
-write_note(title, content, folder, tags) - Create or update notes
-read_note(identifier, page, page_size) - Read notes by title or permalink
+write_note(title, content, folder, tags, output_format="text"|"json") - Create or update notes
+read_note(identifier, page, page_size, output_format="text"|"json") - Read notes by title or permalink
 read_content(path) - Read raw file content (text, images, binaries)
 view_note(identifier) - View notes as formatted artifacts
-edit_note(identifier, operation, content) - Edit notes incrementally
-move_note(identifier, destination_path) - Move notes with database consistency
-delete_note(identifier) - Delete notes from knowledge base
+edit_note(identifier, operation, content, output_format="text"|"json") - Edit notes incrementally
+move_note(identifier, destination_path, output_format="text"|"json") - Move notes with database consistency
+delete_note(identifier, output_format="text"|"json") - Delete notes from knowledge base
 ```
 
 **Knowledge Graph Navigation:**
 ```
-build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-recent_activity(type, depth, timeframe) - Find recently updated information
+build_context(url, depth, timeframe, output_format="json"|"text") - Navigate knowledge graph via memory:// URLs
+recent_activity(type, depth, timeframe, output_format="text"|"json") - Find recently updated information
 list_directory(dir_name, depth) - Browse directory contents with filtering
 ```
 
@@ -443,12 +443,15 @@ search_by_metadata(filters, limit, offset, project) - Structured frontmatter sea
 
 **Project Management:**
 ```
-list_memory_projects() - List all available projects
-create_memory_project(project_name, project_path) - Create new projects
+list_memory_projects(output_format="text"|"json") - List all available projects
+create_memory_project(project_name, project_path, output_format="text"|"json") - Create new projects
 get_current_project() - Show current project stats
 sync_status() - Check synchronization status
 ```
 
+`output_format` defaults to `"text"` for these tools, preserving current human-readable responses.
+`build_context` defaults to `"json"` and can be switched to `"text"` when compact markdown output is preferred.
+
 **Cloud Discovery (opt-in):**
 ```
 cloud_info() - Show optional Cloud overview and setup guidance

docs/mcp-ui-bakeoff-instructions.md

@@ -83,18 +83,26 @@ Manual check:
 
 ---
 
-### 2) ASCII / ANSI TUI Output
+### 2) Text / JSON Output Modes
 
 Tools:
-- `search_notes(output_format="ascii" | "ansi")`
-- `read_note(output_format="ascii" | "ansi")`
+- `search_notes(output_format="text" | "json")`
+- `read_note(output_format="text" | "json")`
+- `write_note(output_format="text" | "json")`
+- `edit_note(output_format="text" | "json")`
+- `recent_activity(output_format="text" | "json")`
+- `list_memory_projects(output_format="text" | "json")`
+- `create_memory_project(output_format="text" | "json")`
+- `delete_note(output_format="text" | "json")`
+- `move_note(output_format="text" | "json")`
+- `build_context(output_format="json" | "text")`
 
 Expect:
-- ASCII table for search, header + content preview for note.
-- ANSI variants include color escape codes.
+- `text` mode preserves existing human-readable responses.
+- `json` mode returns structured dict/list payloads for machine-readable clients.
 
 Automated:
-- `uv run pytest test-int/mcp/test_output_format_ascii_integration.py`
+- `uv run pytest test-int/mcp/test_output_format_json_integration.py`
 
 ---
 
@@ -125,6 +133,6 @@ Fill in after running:
 
 - Tool‑UI (React): __
 - MCP‑UI SDK (embedded): __
-- ASCII/ANSI: __
+- Text/JSON modes: __
 
 Decision + rationale: __

docs/post-v0.18.0-test-plan.md

@@ -180,7 +180,7 @@ Key finding: **FastEmbed (384-d local ONNX) matches or exceeds OpenAI (1536-d) q
 ### Existing coverage anchor points
 
 - `tests/mcp/test_tool_contracts.py`
-- `test-int/mcp/test_output_format_ascii_integration.py`
+- `test-int/mcp/test_output_format_json_integration.py`
 - `test-int/mcp/test_ui_sdk_integration.py`
 
 ### Gaps to close — DONE
@@ -288,7 +288,7 @@ Run after automated tests pass.
 - Routing: verify success/failure paths with and without API key.
 - Permalink routing: read/write/search notes across projects with colliding titles.
 - Permalink routing: verify memory URL routing correctness.
-- UI/TUI: call `search_notes` and `read_note` with UI variants and `output_format=ascii|ansi`.
+- UI/TUI: call `search_notes` and `read_note` with UI variants and `output_format=text|json`.
 - UI/TUI: verify payload/resource format and metadata completeness.
 
 ## Implementation Backlog (Ordered)

src/basic_memory/cli/commands/tool.py

@@ -160,11 +160,14 @@ async def _read_note_json(
                 search_type="title",
                 project=project_name,
                 workspace=workspace,
+                output_format="json",
             )
-            if title_results and hasattr(title_results, "results") and title_results.results:
-                result = title_results.results[0]
-                if result.permalink:
-                    entity_id = await knowledge_client.resolve_entity(result.permalink)
+            results = title_results.get("results", []) if isinstance(title_results, dict) else []
+            if results:
+                result = results[0]
+                permalink = result.get("permalink")
+                if permalink:
+                    entity_id = await knowledge_client.resolve_entity(permalink)
 
         if entity_id is None:
             raise ValueError(f"Could not find note matching: {identifier}")
@@ -635,10 +638,13 @@ def build_context(
                     page=page,
                     page_size=page_size,
                     max_related=max_related,
+                    output_format="text" if format == "text" else "json",
                 )
             )
-        # build_context now returns a slimmed dict (already serializable)
-        print(json.dumps(result, indent=2, ensure_ascii=True, default=str))
+        if format == "json":
+            print(json.dumps(result, indent=2, ensure_ascii=True, default=str))
+        else:
+            print(result)
     except ValueError as e:
         typer.echo(f"Error: {e}", err=True)
         raise typer.Exit(1)