clawdiney 0.2.1__tar.gz

clawdiney-0.2.1/.env.example

@@ -0,0 +1,38 @@
+# --- Clawdiney Multi-Vault Configuration ---
+
+# Lista de vaults (separados por vírgula)
+VAULTS=general,projects,personal
+
+# Paths para cada vault
+VAULT_GENERAL_PATH=~/clawdiney-vaults/general
+VAULT_PROJECTS_PATH=~/clawdiney-vaults/projects
+VAULT_PERSONAL_PATH=~/clawdiney-vaults/personal
+
+# Vault padrão usado pelo MCP server
+MCP_DEFAULT_VAULT=general
+
+# OU: Descobrir vaults automaticamente de um diretório
+# VAULTS_DIR=~/clawdiney-vaults
+#
+# Cada subpasta com clawdiney.toml vira um vault automaticamente.
+# Exemplo de estrutura:
+# ~/clawdiney-vaults/
+# ├── general/clawdiney.toml
+# ├── cliente-alfa/clawdiney.toml
+# └── cliente-beta/clawdiney.toml
+
+# Embedded storage (SQLite) — no external services required
+BRAIN_DB_PATH=~/.clawdiney/brain.db
+
+# Embedding model to use via Ollama
+MODEL_NAME=bge-m3:latest
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_DIMENSION=1024
+
+# Optional reranker (cross-encoder, BAAI/bge-reranker-v2-m3)
+ENABLE_RERANK=true
+
+# Chunking
+CHUNKING_STRATEGY=headers
+CHUNK_SIZE=500
+CHUNK_OVERLAP=50

clawdiney-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v
+
+      - name: Run tests with coverage (only on Python 3.12)
+        if: matrix.python-version == '3.12'
+        run: |
+          python -m pytest tests/ -v --cov=clawdiney --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff linter
+        run: ruff check src/clawdiney/ tests/
+
+      - name: Run ruff formatter
+        run: ruff format --check src/clawdiney/ tests/
+
+  type-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run mypy
+        run: |
+          pip install types-requests
+          mypy src/clawdiney/ --ignore-missing-imports --no-strict-optional

clawdiney-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history + tags, required by setuptools_scm
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/clawdiney
+    permissions:
+      id-token: write # required for Trusted Publishing (OIDC), no API token needed
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

clawdiney-0.2.1/.gitignore

@@ -0,0 +1,57 @@
+# Python
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environment Variables (SENSITIVE)
+.env
+
+# Database Files (regenerated on index)
+chroma_db/
+neo4j_data/
+chroma_data/
+
+# Generated by setuptools_scm
+src/clawdiney/_version.py
+
+# State files
+.clawdiney_state.json
+
+# OS Files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Agent artifacts (planning, evidence, drafts)
+.sisyphus/
+
+# Backups
+.env.backup*
+
+# IDE
+.vscode/
+.idea/
+redis_data/
+src/clawdiney.egg-info/
+dist/
+build/
+
+# Antigravity CLI
+.antigravitycli/
+
+# Local AI agent tool configs
+.agent/
+.claude/
+.gemini/
+.omc/
+.opencode/

clawdiney-0.2.1/AGENTS.md

@@ -0,0 +1,150 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+Clawdiney is a hybrid Vector + Graph system that transforms an Obsidian Vault into a living knowledge source for AI coding agents. The system enables semantic search and knowledge graph navigation of SOPs, design systems, architectural patterns, and documentation.
+
+## Architecture
+
+The system is fully embedded (v0.2.0) — a single SQLite database (`brain.db`) holds everything:
+
+1. **sqlite-vec** - Vector KNN search (embeddings via Ollama `bge-m3`)
+2. **FTS5** - BM25 full-text search (exact terms, acronyms, identifiers)
+3. **Graph tables** (`entities`, `relations`) - Note relationships via WikiLinks and shared tags
+4. **MCP Server** - Provides integration with Codex via Model Context Protocol
+
+Data flow:
+Obsidian Vault → `src/clawdiney/indexer.py` → `brain.db` (via `storage.py`) → `src/clawdiney/mcp_server.py` → Codex
+
+**No Docker services required.** Only Ollama must be running (embeddings). The database lives at `BRAIN_DB_PATH` (default `~/.clawdiney/brain.db`).
+
+## Common Development Commands
+
+### Running the System
+
+No infrastructure to start — storage is an embedded SQLite file. Ensure Ollama is running with the `bge-m3` model pulled.
+
+Index/re-index the Obsidian vault:
+```bash
+./venv/bin/python3 -m clawdiney.indexer
+```
+
+Start the MCP server for Codex integration:
+```bash
+./venv/bin/python3 -m clawdiney.mcp_server
+```
+
+Test queries from command line:
+```bash
+./scripts/ask_brain.sh "your query here"
+```
+
+Or directly with Python:
+```bash
+./venv/bin/python3 -m clawdiney.query_engine "your query here"
+```
+
+### Development Environment Setup
+
+Initial setup (installs dependencies, indexes vault):
+```bash
+chmod +x scripts/setup_brain.sh
+./scripts/setup_brain.sh
+```
+
+Manual dependency installation:
+```bash
+python3 -m venv venv
+./venv/bin/pip install -e .
+```
+
+### Testing
+
+Run a test query to verify the system is working:
+```bash
+./venv/bin/python3 -m clawdiney.query_engine "test query"
+```
+
+Run unit tests:
+```bash
+./scripts/run_tests.sh
+```
+
+Or run tests directly with pytest:
+```bash
+./venv/bin/python3 -m pytest tests/ -v
+```
+
+Use the MCP `health_check` tool (or open `brain.db` with any SQLite client) for troubleshooting.
+
+## Key Files and Components
+
+- `src/clawdiney/mcp_server.py` - Main MCP server that integrates with Codex
+- `src/clawdiney/query_engine.py` - Hybrid retrieval (BM25 + vector + RRF) + rerank + graph expansion
+- `src/clawdiney/storage.py` - Single gateway to `brain.db` (schema, hybrid search SQL, graph queries)
+- `src/clawdiney/indexer.py` - Full indexing of Obsidian vault into `brain.db`
+- `src/clawdiney/config.py` - Centralized configuration management
+- `scripts/setup_brain.sh` - Automated setup script for new installations
+- `.env` - Configuration file for paths and settings
+
+## Integration with MCP Clients
+
+The system integrates via the Model Context Protocol (MCP). When properly configured, the agent has access to **read and write** tools:
+
+### Read Tools (Discovery)
+
+1. `search_brain(query)` - Search for architectural patterns, SOPs, and design system components
+2. `explore_graph(note_name)` - Find notes related to a specific topic via WikiLinks and shared tags
+3. `resolve_note(name)` - Resolve ambiguous note names to canonical vault-relative paths
+4. `get_note_chunks(path)` - List chunk headers for a note (structured preview)
+5. `get_project_card(name)` - Full project card (Purpose, Stack, Architecture, Interfaces)
+6. `how_do_projects_relate(a, b)` - Graph paths between two projects
+7. `health_check()` - Check health status of `brain.db` and Ollama
+
+### Write Tools (Knowledge Capture)
+
+8. `write_note(path, content, mode)` - Create or update a note at any vault location
+   - `mode`: "create" (fail if exists), "overwrite" (replace), "append" (add to end)
+9. `append_to_daily(content)` - Append content to today's daily note (50_Daily/YYYY-MM-DD.md)
+10. `add_learning(topic, content, area)` - Save learnings to appropriate folder
+   - `area`: "SOPs", "Architecture", "DesignSystem", "Projects", "Areas", "Learnings"
+11. `delete_note(path)` - Delete a note and remove from index
+
+### Example Workflow
+
+```python
+# 1. Search for existing patterns
+search_brain("backend API deployment")
+
+# 2. If found, update the SOP
+write_note("30_Resources/SOPs/SOP_Deploy.md", updated_content, mode="append")
+
+# 3. If not found, create new learning
+add_learning("Backend_API_Deploy", "# SOP\\n\\nDeployment pattern...", area="SOPs")
+
+# 4. Document daily learnings
+append_to_daily("## Learnings\\n- Discovered X about the architecture")
+```
+
+### Configuration Example
+
+```json
+{
+  "projects": {
+    "/path/to/projects": {
+      "mcpServers": {
+        "clawdiney": {
+          "command": "/path/to/clawdiney/venv/bin/python3",
+          "args": ["-m", "clawdiney.mcp_server"]
+        }
+      }
+    }
+  }
+}
+```
+
+## Recent Improvements
+
+See [CLAUDE.md](CLAUDE.md) "Recent Improvements" for the full history of the embedded storage migration (v0.2.0) and project knowledge graph features.

clawdiney-0.2.1/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## [1.2.0] - 2026-04-20
+
+### Added
+- `resolve_note(name)` and `get_note_chunks(path)` as the canonical MCP drill-down workflow
+- explicit `main()` and pure indexing helpers in `brain_indexer.py`
+- reranker fallback to preserve vector results when reranking fails
+
+### Changed
+- standardized on `BrainQueryEngine` as the active engine abstraction
+- moved note identity toward canonical vault-relative `path`
+- updated tests and examples to match the retrieval-first contract
+- kept full-file reading outside the MCP surface
+
+### Removed
+- broken `read_full_note` MCP flow
+- stale `BrainEngine` references from active code paths
+
+## [1.1.0] - 2026-04-19
+
+### Added
+- Centralized configuration management with `config.py`
+- Support for both HTTP and Persistent ChromaDB clients via `CHROMA_CLIENT_TYPE` environment variable
+- Proper connection closing for BrainEngine to prevent connection leaks
+- Enhanced error handling in BrainEngine initialization
+- Improved file resolution in `read_note` method to handle duplicate filenames
+- Unit tests for configuration and engine classes
+- Test runner script (`run_tests.sh`)
+
+### Changed
+- Fixed hardcoded path in `CHROMA_PATH` configuration
+- Standardized ChromaDB client usage across all modules
+- Improved error messages and handling throughout the codebase
+- Updated `.env` file with new configuration options
+- Updated documentation in `CLAUDE.md`
+
+### Fixed
+- Inconsistent ChromaDB client usage between modules
+- Missing `close()` method in BrainEngine
+- Fragile file lookup in `read_note` method
+- Lack of error handling in BrainEngine initialization
+- Missing unit tests
+
+### Security
+- Removed personal path information from default configuration