zettelforge 2.6.2__tar.gz → 2.8.0__tar.gz

{zettelforge-2.6.2 → zettelforge-2.8.0}/.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
     - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: '3.12'
 
@@ -35,13 +35,13 @@ jobs:
   pip-audit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
     - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: '3.12'
     - name: Install pip-audit
-      run: pip install pip-audit
+      run: pip install pip-audit==2.9.0
     - name: Audit dependencies (any reported vuln blocks)
       run: |
         pip install -e ".[dev]" || pip install -e "."
@@ -49,7 +49,7 @@ jobs:
         # --ignore-vuln=CVE-... with a citation when the finding is
         # explicitly accepted per GOV-009 §"Vulnerability Response".
         #
-        # CVE-2026-3219: vulnerability in `pip` itself (the package
+        # CVE-2026-3219 / PYSEC-2026-196: vulnerability in `pip` itself (the package
         # manager), not a project dependency. The runner's pip is
         # supplied by GitHub's setup-python image and is not something
         # ZettelForge's pyproject can pin or upgrade. Risk-accepted
@@ -57,25 +57,59 @@ jobs:
         # install, not at runtime; CI builds in ephemeral runners with
         # no persistent state. Re-evaluate when GitHub's images ship a
         # patched pip.
-        pip-audit --strict --vulnerability-service=osv \
-          --ignore-vuln=CVE-2026-3219
+        #
+        # CVE-2023-36464 / GHSA-4vvm-4w3v-6mr8: medium-severity
+        # infinite-loop DoS in PyPDF2 3.0.1, introduced transitively by
+        # Maigret. PyPDF2 has no patched release under that package name
+        # (upstream recommends migrating to pypdf>=3.9.0), and ZettelForge's
+        # AGE-120 username collector does not parse attacker-supplied PDFs or
+        # invoke Maigret report generation. Accepted for AGE-120 because the
+        # GOV-009 blocking threshold is HIGH/CRITICAL and the collector
+        # lazy-imports/fails closed.
+        #
+        # --skip-editable: do not audit the editable local zettelforge
+        # install. It is the project itself, not a third-party dependency,
+        # and on a release-prep PR its version is bumped ahead of PyPI
+        # (e.g. 2.8.0 before publish), so pip-audit cannot resolve it.
+        #
+        # --strict is intentionally NOT used: it fails the run whenever a
+        # distribution can't be audited, which includes the editable
+        # package we deliberately skip ("distribution marked as editable").
+        # pip-audit still exits non-zero on any real reported vulnerability,
+        # so the "any reported vuln blocks" gate is preserved; every
+        # third-party dependency (and the runner's pip) is still audited.
+        pip-audit --skip-editable \
+          --ignore-vuln=CVE-2026-3219 \
+          --ignore-vuln=PYSEC-2026-196 \
+          --ignore-vuln=CVE-2023-36464
 
   test:
     runs-on: ubuntu-latest
     needs: lint
     strategy:
       fail-fast: false
+      # The fastembed model download is shared across Python versions. Running
+      # these jobs in parallel can double-hit HuggingFace and trigger 429s.
+      max-parallel: 1
       matrix:
         python-version: ['3.12', '3.13']
 
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: ${{ matrix.python-version }}
 
+    - name: Cache fastembed model
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
+      with:
+        path: |
+          ~/.cache/fastembed
+          ~/.cache/huggingface
+        key: fastembed-nomic-embed-text-v1.5-Q-${{ runner.os }}
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -102,19 +136,21 @@ jobs:
 
     - name: Upload coverage
       if: matrix.python-version == '3.12'
-      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2
-      with:
-        file: ./coverage.xml
-        fail_ci_if_error: false
+      continue-on-error: true
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      run: |
+        python -m pip install codecov-cli
+        codecovcli upload-process -f ./coverage.xml
 
   governance:
     runs-on: ubuntu-latest
     needs: lint
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
     - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: '3.12'
 
@@ -139,10 +175,10 @@ jobs:
     needs: [test, governance]
 
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
     - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: '3.12'
 

{zettelforge-2.6.2 → zettelforge-2.8.0}/.github/workflows/docs.yml

@@ -14,8 +14,8 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
         with:
           python-version: '3.12'
       - run: pip install mkdocs-material

{zettelforge-2.6.2 → zettelforge-2.8.0}/.github/workflows/publish.yml

@@ -6,15 +6,19 @@ on:
 
 jobs:
   publish:
+    # Package-only releases (for example packages-v0.1.0) are not
+    # Python package releases and must not attempt a PyPI upload.
+    if: startsWith(github.event.release.tag_name, 'v')
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       id-token: write  # trusted publishing
 
     steps:
-    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
     - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
       with:
         python-version: '3.12'
 

{zettelforge-2.6.2 → zettelforge-2.8.0}/.github/workflows/snyk-security.yml

@@ -17,10 +17,10 @@ jobs:
       actions: read
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
         with:
           python-version: '3.12'
 
@@ -65,7 +65,7 @@ jobs:
 
       - name: Upload SARIF to GitHub
         if: steps.check_token.outputs.has_token == 'true'
-        uses: github/codeql-action/upload-sarif@b25d0ebf40e5b63ee81e1bd6e5d2a12b7c2aeb61
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e
         with:
           sarif_file: snyk-code.sarif
         continue-on-error: true

{zettelforge-2.6.2 → zettelforge-2.8.0}/.github/workflows/stale.yml

@@ -12,7 +12,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@v10
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 

{zettelforge-2.6.2 → zettelforge-2.8.0}/ARCHITECTURE.md

@@ -3,6 +3,19 @@
 Visual diagram: [`docs/architecture-diagram.mmd`](docs/architecture-diagram.mmd)
 Deep explanation: [`docs/explanation/architecture.md`](docs/explanation/architecture.md)
 
+## Foundational Model: Two Hemispheres
+
+ZettelForge is modeled on the brain. A symbolic left hemisphere (the typed,
+STIX-aligned knowledge graph with schema enforcement and rule-based inference) is
+the precise, explainable authority of record. An associative right hemisphere
+(blended vector and graph retrieval with GraphRAG and agentic synthesis) explores
+and proposes. Underneath both, knowledge is atomic facts connected by directed,
+time-stamped, pairwise associations, with time and provenance as first-class
+primitives (Cognitive Data Model, Pieris 2025). The components below implement
+this model. See [design philosophy](docs/explanation/design-philosophy-dual-hemisphere.md)
+for the rationale and research basis, and [GOVERNANCE.md](GOVERNANCE.md) for the
+binding design commitment.
+
 ## Storage
 
 ZettelForge uses a `StorageBackend` ABC (33 methods) with pluggable

{zettelforge-2.6.2 → zettelforge-2.8.0}/CHANGELOG.md

@@ -6,6 +6,107 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.8.0] - 2026-06-26
+
+Feature release. Extends the RFC-016 OSINT layer with passive ingest and
+live AGE-120 enrichers, adds AGE-127 prompt-injection /
+retrieval-poisoning guardrails across the memory pipeline, and lays the
+RFC-018 Phase 0 enrichment job ledger foundation, alongside configurable
+LLM generation budgets and bulk detection-ingest hardening. No data
+migration is required.
+
+### Added
+
+- **Prompt-injection and retrieval-poisoning guardrails** (AGE-127). A
+  deterministic guard for untrusted memory and CTI text, wired into the
+  remember, recall, synthesis, fact-extraction, entity-indexing,
+  note-construction, intent-classification, memory-update, and evolution
+  boundaries. LLM prompts are hardened to treat query and context text as
+  untrusted evidence. (#166)
+- **Passive OSINT executor** (RFC-016 Phase 1.5). Validates collector
+  tuples and persists knowledge-graph writes; scopes OSINT alias caching to
+  each `KnowledgeGraph` instance; canonicalizes Organization values to
+  avoid WHOIS/RDAP duplicates; treats an explicit empty collector
+  allow-list as empty; adds user-facing passive OSINT docs and mkdocs
+  navigation. (#163)
+- **Live OSINT enrichers** (AGE-120). Native RFC-016 collectors that feed
+  the graph backend: WHOIS/DNS, maigret/sherlock username discovery, HIBP
+  breach lookup, and blockchain wallet transactions, with OSINT
+  ontology / executor / entity-resolution / graph-persistence extensions.
+  The network collectors are an opt-in `[osint]` extra, key-gated and
+  fail-closed, and are never auto-triggered by `remember()`. Known
+  fast-follow robustness items are tracked in #176. (#167)
+- **RFC-018 Phase 0 enrichment job ledger.** Durable SQLite job-metadata
+  foundation with `MemoryManager` queue-state recording and regression
+  tests, plus the RFC-018 spec for the next ingestion, enrichment,
+  parser-safety, metadata-policy, operator-health, and release-train
+  improvements. (#178)
+- Configurable LLM generation budgets for causal extraction, synthesis,
+  fact extraction, NER, and memory evolution, plus `reasoning_model` scaling
+  floors and `<think>` / `<thinking>` JSON parse stripping. (#153)
+- Bulk Sigma/YARA ingest can defer enrichment and drain once via
+  `MemoryManager.flush()`. (#153)
+
+### Fixed
+
+- Hardened CCCS YARA metadata validation against multiline regex injection
+  and overly permissive author values. (#153)
+- `MemoryManager.flush()` now waits for in-flight enrichment work, not only
+  queued work; cached `Plyara` parsing is serialized for concurrent callers. (#153)
+
+## [2.7.0] - 2026-05-26
+
+Security and OSINT release. Adds the RFC-016 OSINT layer and the first
+SEC-011 / MemSAD-inspired write-time memory-poisoning defense. No data
+migration is required. The new memory defense ships in audit mode by default.
+
+### Added
+
+- **OSINT layer scaffold and Phase 1 collectors** (RFC-016). Adds
+  `zettelforge.osint` with infrastructure, breach, people, social, and
+  technology collector packages; OSINT ontology and relation extensions;
+  entity canonicalization helpers; collector registry; and tests covering
+  DNS, WHOIS, certificates, BGP, ports, breach, people, social, and tech
+  collector contracts. Optional runtime dependencies are available with
+  `pip install zettelforge[osint]`.
+- **Write-time memory anomaly defense** (SEC-011 / MemSAD). New
+  `MemoryAnomalyGate` scores candidate notes before persistence using
+  MemSAD-style max/mean embedding similarity against recent domain
+  calibration notes plus character n-gram Jensen-Shannon divergence to
+  reduce synonym/paraphrase evasion. Config lives under
+  `governance.memory_defense`; default mode is `audit`, with `block` and
+  `quarantine` available once a deployment has a clean calibration corpus.
+- **Quarantine path for rejected memory writes.** In `quarantine` mode,
+  flagged notes are written to JSONL forensic quarantine and are not exposed
+  to recall, entity lookup, LanceDB, or graph traversal.
+- **CrewAI integration** (issue #40). New optional extra
+  `pip install zettelforge[crewai]` exposes `ZettelForgeRecallTool`,
+  `ZettelForgeRememberTool`, and `ZettelForgeSynthesizeTool` as CrewAI
+  `BaseTool` subclasses. CTI-focused crews can now use ZettelForge as a
+  drop-in alternative to CrewAI's existing Mem0 memory tools, with
+  per-tool description copy aimed at routing the LLM to the right tool
+  (recall for lookups, remember for findings, synthesize for final answers).
+  See `examples/crewai_cti_crew.py` for a runnable two-agent demo.
+  Tests gated on `pytest.importorskip("crewai")`; 11 pass against
+  crewai 1.14.x.
+
+### Changed
+
+- **Telemetry attribution compatibility.** `caller` is now supported in
+  telemetry events while the previous `actor` field and method arguments
+  remain backward-compatible for existing dashboards and tests.
+- **Real LLM integration and performance tests are explicit opt-in.**
+  Set `ZETTELFORGE_RUN_LLM_INTEGRATION=1` or
+  `ZETTELFORGE_RUN_PERFORMANCE_TESTS=1` to run environment-sensitive suites.
+  The default regression suite is now deterministic on machines without
+  local LLM credentials or dedicated benchmark hardware.
+
+### Tests
+
+- Added focused memory-defense tests for insufficient calibration, audit-mode
+  anomaly detection, and quarantine writes.
+- Default regression gate: `742 passed, 13 skipped`.
+
 ## [2.6.2] - 2026-04-27
 
 UI/UX release. Fixes the `/config` page so the Apply button actually works

zettelforge-2.8.0/GOVERNANCE.md

@@ -0,0 +1,49 @@
+# Governance
+
+## Maintainer
+
+ZettelForge is maintained by Patrick Roland (@rolandpg).
+
+## Licensing Commitment
+
+ZettelForge is MIT licensed. This will not change.
+
+## Design Commitment: Brain-Inspired Memory Architecture
+
+ZettelForge is modeled on the brain by deliberate decision, not metaphor. This
+commitment is binding on the architecture and will not be quietly abandoned.
+
+The memory engine is dual-hemisphere. A symbolic left hemisphere (a typed,
+STIX/ATT&CK-aligned knowledge graph with schema enforcement and rule-based
+inference) is the authority of record: precise, constraint-checked, and
+explainable. An associative right hemisphere (blended vector and graph retrieval,
+GraphRAG, and agentic synthesis) explores and proposes, and writes back into the
+symbolic layer only through validated paths. The two layers stay distinct.
+
+Underneath both, knowledge is represented as atomic facts connected by directed,
+time-stamped, pairwise associations (the Cognitive Data Model, Pieris 2025). Time
+and provenance are first-class primitives: every note and claim carries its
+source, markings (TLP), confidence, and time validity, and every retrieval result
+carries provenance. Ingested content is untrusted and is sanitized or isolated
+before any model call. Quantitative quality or performance claims are reproduced
+on the project's own CTI benchmark suite before being stated as fact.
+
+Changes to storage, retrieval, the knowledge graph, or ingestion MUST preserve
+this model, and design decisions SHOULD cite the relevant hemisphere or layer.
+The full rationale and research basis are in
+[docs/explanation/design-philosophy-dual-hemisphere.md](docs/explanation/design-philosophy-dual-hemisphere.md).
+
+## Extension Boundary
+
+The extension package (`zettelforge-enterprise`) provides features
+that require external infrastructure (TypeDB, OpenCTI, multi-tenant
+OAuth). The open source project will never be degraded to create
+commercial incentive.
+
+Rule: if a feature works with JSONL + local embeddings, it belongs
+in this repo.
+
+## Contributions
+
+Community contributions are reviewed on their technical merits.
+All contributions to this repository remain MIT licensed.