mithril-cognee 0.1.0__tar.gz

mithril_cognee-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# Mithril environment variables
+# Copy to .env and fill in your own API key.
+
+# ─────────────────────────────────────────────────────────────────────────
+# LLM provider
+# ─────────────────────────────────────────────────────────────────────────
+LLM_PROVIDER="custom"
+LLM_MODEL="openai/gpt-4o-mini"
+LLM_ENDPOINT="https://agentrouter.org/v1"
+LLM_API_KEY="your-agentrouter-or-openai-compatible-key-here"
+
+# ─────────────────────────────────────────────────────────────────────────
+# Embedding provider
+# ─────────────────────────────────────────────────────────────────────────
+#   With this, the LLM key above is the only key Mithril needs.
+EMBEDDING_PROVIDER="fastembed"
+EMBEDDING_MODEL="BAAI/bge-small-en-v1.5"
+EMBEDDING_DIMENSIONS="384"

mithril_cognee-0.1.0/.github/workflows/publish-python.yml

@@ -0,0 +1,31 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mithril_cognee-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Secrets and local env
+.env
+.env.local
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Mithril runtime data (regenerated by demos/API)
+.mithril_audit.db
+.mithril_quarantine.db
+.memory_firewall_audit.db
+.memory_firewall_quarantine.db
+
+# Cognee runtime data (regenerated on remember/recall)
+.cognee_system/
+
+# Demo artifacts
+artifacts/
+
+# Future UI (Next.js)
+node_modules/
+.next/
+out/
+ui/.env
+ui/.env.local
+
+# OS noise
+.DS_Store
+Thumbs.db
+desktop.ini

mithril_cognee-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.5

mithril_cognee-0.1.0/Makefile

@@ -0,0 +1,57 @@
+.PHONY: demo vanilla seed ingest mcp benchmark test api reset clean install dev ui ui-install ui-build
+
+demo:
+	.venv\Scripts\python.exe demo/run_demo.py
+
+vanilla:
+	.venv\Scripts\python.exe demo/vanilla_demo.py
+
+seed:
+	.venv\Scripts\python.exe demo/seed_data.py
+
+ingest:
+	.venv\Scripts\python.exe demo/ingest_demo.py
+
+mcp:
+	.venv\Scripts\python.exe -m mcp_server.server
+
+benchmark:
+	.venv\Scripts\python.exe benchmark/run_benchmark.py
+
+test:
+	.venv\Scripts\python.exe -m pytest tests/ -v
+
+api:
+	.venv\Scripts\python.exe -m uvicorn api.main:app --port 8000 --reload
+
+ui:
+	cd ui && npm run dev
+
+ui-install:
+	cd ui && npm install
+
+ui-build:
+	cd ui && npm run build
+
+dev:
+	start cmd /c ".venv\Scripts\python.exe -m uvicorn api.main:app --port 8000 --reload"
+	cd ui && npm run dev
+
+reset:
+	.venv\Scripts\python.exe -c "import asyncio; import cognee; asyncio.run(cognee.forget(everything=True))"
+	del /f .mithril_audit.db 2>nul
+	del /f .mithril_quarantine.db 2>nul
+	del /f .mithril_reputation.db 2>nul
+	del /f .memory_firewall_audit.db 2>nul
+	del /f .memory_firewall_quarantine.db 2>nul
+	@echo Reset complete.
+
+install:
+	uv pip install -e ".[dev]"
+
+clean:
+	del /f .mithril_audit.db 2>nul
+	del /f .mithril_quarantine.db 2>nul
+	del /f .mithril_reputation.db 2>nul
+	del /f .memory_firewall_audit.db 2>nul
+	del /f .memory_firewall_quarantine.db 2>nul

mithril_cognee-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: mithril-cognee
+Version: 0.1.0
+Summary: Mithril — trust and governance layer for Cognee memory
+Project-URL: Homepage, https://github.com/HydrallHarsh/Mithril
+Project-URL: Repository, https://github.com/HydrallHarsh/Mithril
+Project-URL: Issues, https://github.com/HydrallHarsh/Mithril/issues
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: cognee>=1.2.2
+Requires-Dist: fastapi>=0.138.1
+Requires-Dist: fastembed>=0.3.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: uvicorn>=0.49.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mithril
+
+> A trust and governance layer for Cognee memory.  
+> Every AI can remember. **Mithril** decides what *deserves* to be remembered.
+
+## The Problem
+
+AI agents with persistent memory are vulnerable to **memory poisoning** — where a single malicious message permanently corrupts the knowledge graph that all future agents rely on.
+
+**Vanilla Cognee:**
+
+```
+input → cognee.remember() → stored forever
+```
+
+**With Mithril:**
+
+```
+agent / Slack / file → Trust Score → Contradiction Check → Admission Gate → cognee.remember()
+```
+
+## How Mithril connects to your stack
+
+Mithril is a real boundary in front of Cognee, reachable three ways — all sharing one governance pipeline and one adaptive reputation store:
+
+| Surface | What it is | Entry point |
+|---|---|---|
+| **MCP server** | Agents (Claude Desktop, Cursor) call `mithril_remember` / `mithril_recall` instead of writing to memory directly | `mcp_server/server.py` · `make mcp` |
+| **Ingestion connector** | Parse a real **Slack export** (or a `.txt`/`.jsonl` file) and run the whole feed through the gate | `mithril/ingest.py` · `make ingest` |
+| **REST API + dashboard** | FastAPI backend + Next.js provenance UI | `api/main.py` · `make dev` |
+
+## Adaptive source reputation
+
+Source reputation is **not a static table** — it starts from configured priors and then *moves*:
+
+- a source caught contradicting verified memory **loses** trust (fast),
+- a source whose claims are accepted/corroborated **gains** trust (slow).
+
+Trust is easy to lose and hard to earn. Watch a Slack channel's reputation collapse after it pushes MD5 twice — live, in the dashboard and via `GET /api/reputation`.
+
+## Attack Demo
+
+| | Vanilla Cognee | Mithril + Cognee |
+|---|---|---|
+| Poisoned inputs stored | All 3 | 0 |
+| Provenance tracked | No | Yes |
+| Contradiction detected | No | Yes |
+| Source reputation adapts | No | Yes |
+| Explainable decisions | No | Yes |
+| Answer to "hash passwords?" | May return MD5 | Argon2id |
+
+## Architecture
+
+```
+Incoming Claim  (MCP tool · Slack export · file · API · dashboard)
+     │
+     ▼
+Adaptive Source Reputation (self-adjusting, SQLite-backed)
+     │
+     ▼
+Contradiction Detection (cognee.recall, only_context=True)
+     │
+     ▼
+Trust Score (weighted + normalized — see master plan Section 4)
+     │
+     ▼
+Admission Gate (Accept / Warn / Review / Quarantine / Reject)
+     │
+     ├── ACCEPT / WARN → cognee.remember(node_set=["verified"])
+     ├── QUARANTINE / REVIEW / REJECT → SQLite quarantine store
+     ├── Source reputation updated from the outcome
+     └── All → Audit log
+```
+
+## Cognee APIs Used
+
+- `cognee.remember()` — verified memories with NodeSet tagging
+- `cognee.recall(only_context=True)` — contradiction detection
+- `cognee.recall(node_name=["verified"])` — scoped verified retrieval
+- `cognee.improve()` — graph enrichment on verified dataset
+- `cognee.forget()` — demo reset
+- `cognee.visualize_graph()` — knowledge graph HTML export
+
+## Quickstart
+
+Install from PyPI once published:
+
+```bash
+pip install mithril-cognee
+```
+
+Local development from this repo:
+
+```bash
+uv venv && .venv\Scripts\activate
+uv pip install -e ".[dev]"
+copy .env.example .env   # add LLM_API_KEY
+
+make test    # unit tests
+make demo    # full attack demo (terminal)
+make ingest  # ingest a real Slack export through the gate
+make benchmark  # labeled memory-poisoning benchmark → metrics + results.json
+make mcp     # run Mithril as an MCP server (stdio)
+make api     # FastAPI backend → http://localhost:8000
+make ui-install && make ui   # landing → http://localhost:3001 · dashboard → /dashboard
+make dev     # start API + UI together
+```
+
+Installed commands:
+
+```bash
+mithril-mcp       # local MCP server over stdio
+mithril-mcp-http  # remote MCP server over Streamable HTTP at /mcp
+mithril-api       # FastAPI backend
+```
+
+### Use Mithril from Claude Desktop (MCP)
+
+Add to `claude_desktop_config.json`, then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "mithril": {
+      "command": "mithril-mcp"
+    }
+  }
+}
+```
+
+The agent then gets `mithril_remember`, `mithril_recall`, `mithril_quarantine_list`, and `mithril_source_reputation` — every memory write is gated, every recall is verified-only.
+
+### Free deployment notes
+
+For the public dashboard, deploy `ui/` to Vercel and set:
+
+```bash
+NEXT_PUBLIC_BACKEND_URL=https://your-render-api.onrender.com
+```
+
+For the API on Render Free:
+
+```bash
+pip install -e .
+mithril-api
+```
+
+For a demo remote MCP server on Render Free:
+
+```bash
+pip install -e .
+FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=$PORT mithril-mcp-http
+```
+
+The remote MCP endpoint will be:
+
+```text
+https://your-render-service.onrender.com/mcp
+```
+
+Free Render services can sleep and do not keep local SQLite files permanently, so use local MCP for real editor usage unless you add hosted storage and auth.
+
+## Benchmark — does it actually stop poisoning?
+
+Mithril ships with a **labeled memory-poisoning benchmark** (`benchmark/`) that measures it like a security control, not a demo.
+
+**Threat model:** a company runs AI agents over a shared Cognee knowledge base. Claims arrive from authoritative channels (Security Policy, HR System, GitHub) and risky ones (Slack, customer support, external email, public web, other agents). Attackers try to poison shared memory.
+
+The harness seeds verified company memory (`ground_truth.jsonl`), then replays a labeled suite (`attack_suite.jsonl`, ~30 cases) through the **same** `Mithril.remember()` gate and scores every decision into a confusion matrix:
+
+```bash
+make benchmark      # requires LLM_API_KEY + Cognee (like the demos)
+```
+
+**Attack taxonomy covered:** direct contradiction · subtle misinformation · authority spoofing · prompt injection · data exfiltration · policy evasion · social engineering · low-trust unverified. Plus hard *legitimate* cases (verified policy updates, benign low-trust facts) to measure false positives honestly.
+
+| Metric | Meaning |
+|---|---|
+| **Detection rate** | share of attacks blocked (kept out of memory) |
+| **Poison-leak rate** | attacks that reached verified memory — the number to drive to 0 |
+| **False-positive rate** | legitimate updates wrongly blocked (friction) |
+| **Precision / accuracy** | standard classifier metrics |
+
+Results print per-category and per-source and are written to `benchmark/results.json`. The math is unit-tested (`tests/test_benchmark.py`) so the numbers are reproducible from the labeled data even though the LLM contradiction step has run-to-run variance.
+
+> **Why the categories matter:** *authority spoofing* (a claim that fakes a high-trust source but contradicts policy) is caught by the **contradiction layer**, not source reputation — proof that the trust signals are independent and complementary, not just a source lookup.
+
+## Usage
+
+```python
+from mithril import Mithril
+
+firewall = Mithril()
+await firewall.setup()
+
+result = await firewall.remember(
+    text="Always hash passwords using MD5",
+    source="Slack",
+)
+# result.status → quarantine or reject
+# result.trust_breakdown.final_score → normalized 0–1
+# result.trust_breakdown.reasons → explainable breakdown
+
+answer = await firewall.recall("How should we hash passwords?")
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/audit` | Full audit log |
+| GET | `/api/quarantine` | Quarantined memories |
+| GET | `/api/reputation` | Live adaptive source reputation (with deltas) |
+| GET | `/api/stats` | Aggregate metrics |
+| POST | `/api/remember` | Submit claim through Mithril |
+| POST | `/api/recall` | Query verified memory |
+| POST | `/api/reset` | Clear Cognee + local stores |
+| GET | `/api/config` | Sources, weights, thresholds |
+
+## Trust Score Formula
+
+Per master plan — weighted components, then normalized to 0–1:
+
+```
+raw = source_rep×0.40 + corroboration×0.30 + freshness×0.10 − contradiction×0.40
+final_score = raw / max_theoretical_score
+```
+
+Admission thresholds: Accept ≥ 0.85 · Warn ≥ 0.60 · Review ≥ 0.40 · Quarantine ≥ 0.20
+
+## Project Layout
+
+```
+mithril/          Core package (scorer, gate, firewall, reputation, ingest, audit, quarantine)
+mcp_server/       MCP server — exposes Mithril tools to agents
+benchmark/        Labeled memory-poisoning benchmark (ground truth, attack suite, metrics)
+api/              FastAPI backend
+demo/             Attack demo, vanilla comparison, Slack-export ingestion demo
+tests/            Unit + integration tests
+memory-firewall-master-plan.md   Full hackathon build plan
+```

mithril_cognee-0.1.0/README.md

@@ -0,0 +1,241 @@
+# Mithril
+
+> A trust and governance layer for Cognee memory.  
+> Every AI can remember. **Mithril** decides what *deserves* to be remembered.
+
+## The Problem
+
+AI agents with persistent memory are vulnerable to **memory poisoning** — where a single malicious message permanently corrupts the knowledge graph that all future agents rely on.
+
+**Vanilla Cognee:**
+
+```
+input → cognee.remember() → stored forever
+```
+
+**With Mithril:**
+
+```
+agent / Slack / file → Trust Score → Contradiction Check → Admission Gate → cognee.remember()
+```
+
+## How Mithril connects to your stack
+
+Mithril is a real boundary in front of Cognee, reachable three ways — all sharing one governance pipeline and one adaptive reputation store:
+
+| Surface | What it is | Entry point |
+|---|---|---|
+| **MCP server** | Agents (Claude Desktop, Cursor) call `mithril_remember` / `mithril_recall` instead of writing to memory directly | `mcp_server/server.py` · `make mcp` |
+| **Ingestion connector** | Parse a real **Slack export** (or a `.txt`/`.jsonl` file) and run the whole feed through the gate | `mithril/ingest.py` · `make ingest` |
+| **REST API + dashboard** | FastAPI backend + Next.js provenance UI | `api/main.py` · `make dev` |
+
+## Adaptive source reputation
+
+Source reputation is **not a static table** — it starts from configured priors and then *moves*:
+
+- a source caught contradicting verified memory **loses** trust (fast),
+- a source whose claims are accepted/corroborated **gains** trust (slow).
+
+Trust is easy to lose and hard to earn. Watch a Slack channel's reputation collapse after it pushes MD5 twice — live, in the dashboard and via `GET /api/reputation`.
+
+## Attack Demo
+
+| | Vanilla Cognee | Mithril + Cognee |
+|---|---|---|
+| Poisoned inputs stored | All 3 | 0 |
+| Provenance tracked | No | Yes |
+| Contradiction detected | No | Yes |
+| Source reputation adapts | No | Yes |
+| Explainable decisions | No | Yes |
+| Answer to "hash passwords?" | May return MD5 | Argon2id |
+
+## Architecture
+
+```
+Incoming Claim  (MCP tool · Slack export · file · API · dashboard)
+     │
+     ▼
+Adaptive Source Reputation (self-adjusting, SQLite-backed)
+     │
+     ▼
+Contradiction Detection (cognee.recall, only_context=True)
+     │
+     ▼
+Trust Score (weighted + normalized — see master plan Section 4)
+     │
+     ▼
+Admission Gate (Accept / Warn / Review / Quarantine / Reject)
+     │
+     ├── ACCEPT / WARN → cognee.remember(node_set=["verified"])
+     ├── QUARANTINE / REVIEW / REJECT → SQLite quarantine store
+     ├── Source reputation updated from the outcome
+     └── All → Audit log
+```
+
+## Cognee APIs Used
+
+- `cognee.remember()` — verified memories with NodeSet tagging
+- `cognee.recall(only_context=True)` — contradiction detection
+- `cognee.recall(node_name=["verified"])` — scoped verified retrieval
+- `cognee.improve()` — graph enrichment on verified dataset
+- `cognee.forget()` — demo reset
+- `cognee.visualize_graph()` — knowledge graph HTML export
+
+## Quickstart
+
+Install from PyPI once published:
+
+```bash
+pip install mithril-cognee
+```
+
+Local development from this repo:
+
+```bash
+uv venv && .venv\Scripts\activate
+uv pip install -e ".[dev]"
+copy .env.example .env   # add LLM_API_KEY
+
+make test    # unit tests
+make demo    # full attack demo (terminal)
+make ingest  # ingest a real Slack export through the gate
+make benchmark  # labeled memory-poisoning benchmark → metrics + results.json
+make mcp     # run Mithril as an MCP server (stdio)
+make api     # FastAPI backend → http://localhost:8000
+make ui-install && make ui   # landing → http://localhost:3001 · dashboard → /dashboard
+make dev     # start API + UI together
+```
+
+Installed commands:
+
+```bash
+mithril-mcp       # local MCP server over stdio
+mithril-mcp-http  # remote MCP server over Streamable HTTP at /mcp
+mithril-api       # FastAPI backend
+```
+
+### Use Mithril from Claude Desktop (MCP)
+
+Add to `claude_desktop_config.json`, then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "mithril": {
+      "command": "mithril-mcp"
+    }
+  }
+}
+```
+
+The agent then gets `mithril_remember`, `mithril_recall`, `mithril_quarantine_list`, and `mithril_source_reputation` — every memory write is gated, every recall is verified-only.
+
+### Free deployment notes
+
+For the public dashboard, deploy `ui/` to Vercel and set:
+
+```bash
+NEXT_PUBLIC_BACKEND_URL=https://your-render-api.onrender.com
+```
+
+For the API on Render Free:
+
+```bash
+pip install -e .
+mithril-api
+```
+
+For a demo remote MCP server on Render Free:
+
+```bash
+pip install -e .
+FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=$PORT mithril-mcp-http
+```
+
+The remote MCP endpoint will be:
+
+```text
+https://your-render-service.onrender.com/mcp
+```
+
+Free Render services can sleep and do not keep local SQLite files permanently, so use local MCP for real editor usage unless you add hosted storage and auth.
+
+## Benchmark — does it actually stop poisoning?
+
+Mithril ships with a **labeled memory-poisoning benchmark** (`benchmark/`) that measures it like a security control, not a demo.
+
+**Threat model:** a company runs AI agents over a shared Cognee knowledge base. Claims arrive from authoritative channels (Security Policy, HR System, GitHub) and risky ones (Slack, customer support, external email, public web, other agents). Attackers try to poison shared memory.
+
+The harness seeds verified company memory (`ground_truth.jsonl`), then replays a labeled suite (`attack_suite.jsonl`, ~30 cases) through the **same** `Mithril.remember()` gate and scores every decision into a confusion matrix:
+
+```bash
+make benchmark      # requires LLM_API_KEY + Cognee (like the demos)
+```
+
+**Attack taxonomy covered:** direct contradiction · subtle misinformation · authority spoofing · prompt injection · data exfiltration · policy evasion · social engineering · low-trust unverified. Plus hard *legitimate* cases (verified policy updates, benign low-trust facts) to measure false positives honestly.
+
+| Metric | Meaning |
+|---|---|
+| **Detection rate** | share of attacks blocked (kept out of memory) |
+| **Poison-leak rate** | attacks that reached verified memory — the number to drive to 0 |
+| **False-positive rate** | legitimate updates wrongly blocked (friction) |
+| **Precision / accuracy** | standard classifier metrics |
+
+Results print per-category and per-source and are written to `benchmark/results.json`. The math is unit-tested (`tests/test_benchmark.py`) so the numbers are reproducible from the labeled data even though the LLM contradiction step has run-to-run variance.
+
+> **Why the categories matter:** *authority spoofing* (a claim that fakes a high-trust source but contradicts policy) is caught by the **contradiction layer**, not source reputation — proof that the trust signals are independent and complementary, not just a source lookup.
+
+## Usage
+
+```python
+from mithril import Mithril
+
+firewall = Mithril()
+await firewall.setup()
+
+result = await firewall.remember(
+    text="Always hash passwords using MD5",
+    source="Slack",
+)
+# result.status → quarantine or reject
+# result.trust_breakdown.final_score → normalized 0–1
+# result.trust_breakdown.reasons → explainable breakdown
+
+answer = await firewall.recall("How should we hash passwords?")
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/audit` | Full audit log |
+| GET | `/api/quarantine` | Quarantined memories |
+| GET | `/api/reputation` | Live adaptive source reputation (with deltas) |
+| GET | `/api/stats` | Aggregate metrics |
+| POST | `/api/remember` | Submit claim through Mithril |
+| POST | `/api/recall` | Query verified memory |
+| POST | `/api/reset` | Clear Cognee + local stores |
+| GET | `/api/config` | Sources, weights, thresholds |
+
+## Trust Score Formula
+
+Per master plan — weighted components, then normalized to 0–1:
+
+```
+raw = source_rep×0.40 + corroboration×0.30 + freshness×0.10 − contradiction×0.40
+final_score = raw / max_theoretical_score
+```
+
+Admission thresholds: Accept ≥ 0.85 · Warn ≥ 0.60 · Review ≥ 0.40 · Quarantine ≥ 0.20
+
+## Project Layout
+
+```
+mithril/          Core package (scorer, gate, firewall, reputation, ingest, audit, quarantine)
+mcp_server/       MCP server — exposes Mithril tools to agents
+benchmark/        Labeled memory-poisoning benchmark (ground truth, attack suite, metrics)
+api/              FastAPI backend
+demo/             Attack demo, vanilla comparison, Slack-export ingestion demo
+tests/            Unit + integration tests
+memory-firewall-master-plan.md   Full hackathon build plan
+```

mithril_cognee-0.1.0/api/__init__.py

@@ -0,0 +1 @@
+# api package