hivememory 0.1.0__tar.gz

hivememory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hivememory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hivememory-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: hivememory
+Version: 0.1.0
+Summary: Shared reasoning memory layer for multi-agent systems
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faiss-cpu>=1.7.4
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7.0; extra == "dev"
+Requires-Dist: networkx>=3.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# hivememory
+
+Shared reasoning memory for multi-agent systems.
+
+When multiple AI agents research the same problem independently, they waste tokens re-deriving the same knowledge and produce contradictory conclusions no one catches. hivememory gives agents a shared memory layer where they store structured reasoning artifacts, reuse each other's work, and surface contradictions automatically.
+
+[Project page (coming soon)](#)
+
+## Results
+
+Benchmark: 3 agents research "Competitive Landscape of AI Code Editors in 2026" using gpt-4o-mini, with and without shared memory. Each agent researches 3 sub-topics. In the shared configuration, agents query hivememory before each LLM call — when prior findings exist, the agent receives a focused prompt that avoids redundant research.
+
+| Metric | Baseline (no shared memory) | hivememory |
+|---|---|---|
+| Total tokens consumed | 11,896 | 9,810 (-17.5%) |
+| Memory-augmented queries | 0 / 9 | 5 / 9 |
+| Output quality (LLM-as-judge, avg 3 runs) | 8.8 | 9.0 |
+| Contradiction-free score | 9.0 | 9.3 |
+| Reuse rate | 0% | 56% |
+| Wall clock time | 113.5s | 101.9s |
+
+Token savings come from agents 2 and 3 receiving memory context that produces shorter, non-redundant LLM responses. Quality is equal or slightly better because memory-augmented agents build on verified findings rather than re-deriving from scratch.
+
+![Token consumption per agent](screenshots/token_consumption_per_agent.png)
+*Agents 2 and 3 use fewer tokens when prior findings are available in memory.*
+
+![Total token consumption](screenshots/token_consumption_total.png)
+
+![Quality comparison](screenshots/quality_comparison.png)
+*LLM-as-judge scores across 4 dimensions, averaged over 3 evaluation runs.*
+
+## Architecture
+
+```
+  agent-1 ──┐                          ┌── conflict detection
+  agent-2 ──┼── hivememory API ────────┼── embedding search (FAISS)
+  agent-3 ──┘    write / query /       └── provenance DAG
+                 resolve / export
+                       │
+                 ┌─────┴─────┐
+                 │  sqlite   │
+                 │  + FAISS  │
+                 │   index   │
+                 └───────────┘
+```
+
+![Artifact reuse flow](screenshots/artifact_reuse_flow.png)
+*How artifacts flow between agents. Agent 1 writes findings; agents 2 and 3 query memory, reuse relevant work, and focus on gaps.*
+
+![Provenance DAG](screenshots/provenance_dag.png)
+*Dependency graph of artifacts. Colors indicate source agent. Edges show "built on" relationships.*
+
+## Quickstart
+
+```bash
+pip install hivememory
+```
+
+```python
+from hivememory import HiveMemory, Evidence
+
+hive = HiveMemory()
+
+# store a finding
+art = hive.write(
+    claim="Voice AI market projected to reach $50B by 2028",
+    evidence=[Evidence(source="industry report", content="35% CAGR", reliability=0.9)],
+    confidence=0.85,
+    agent_id="researcher-1",
+)
+
+# query shared memory before doing new research
+existing = hive.query("voice AI market size", top_k=3)
+
+# check for contradictions
+open_conflicts = hive.get_conflicts()
+
+# resolve
+if open_conflicts:
+    hive.resolve_conflict(open_conflicts[0].id, winner_id=art.id,
+                          reason="stronger evidence", resolved_by="supervisor")
+```
+
+## How it works
+
+### Reasoning artifacts
+
+Agents store structured claims with evidence, confidence scores, and provenance links — not raw text. Each artifact records who produced it, what evidence supports it, and which prior artifacts it builds on. This structure makes artifacts queryable, comparable, and auditable.
+
+### Conflict detection
+
+When a new artifact is stored, hivememory computes its embedding and searches FAISS for similar existing claims. If two artifacts are semantically close but have divergent confidence scores, a conflict is flagged. This first stage can be followed by an LLM contradiction check (OpenAI or Anthropic) for higher-precision detection.
+
+### Provenance tracking
+
+Every artifact records its dependencies as a list of artifact IDs, forming a directed acyclic graph. This DAG answers "which agent's work did this conclusion build on?" and enables cascading invalidation — if an upstream artifact is superseded, downstream consumers can be notified.
+
+## Repo structure
+
+```
+hivememory/
+  __init__.py          # public API exports
+  artifact.py          # ReasoningArtifact, Evidence, Conflict dataclasses
+  core.py              # HiveMemory main class (FAISS + sqlite)
+  store.py             # low-level persistence layer
+  conflicts.py         # ConflictDetector with LLM client support
+  provenance.py        # ProvenanceTracker DAG
+  wiki.py              # WikiExporter — markdown knowledge base export
+examples/
+  basic_usage.py       # store, query, conflict detect, resolve, export
+  research_task.py     # 3-agent research demo with full pipeline
+benchmarks/
+  real_benchmark.py    # real LLM benchmark (gpt-4o-mini)
+  generate_charts.py   # generate all charts from results.json
+  results.json         # raw benchmark data
+  results_summary.md   # human-readable summary
+tests/
+  test_artifact.py     # artifact serialization and ID generation
+  test_store.py        # persistence layer tests
+  test_conflicts.py    # conflict detection tests
+  test_provenance.py   # provenance DAG tests
+```
+
+## Examples
+
+- `python examples/basic_usage.py` — store artifacts, query memory, detect and resolve conflicts, export a wiki. Good first run to verify installation.
+- `python examples/research_task.py` — three agents research AI code editors, sharing findings through hivememory. Shows artifact reuse, conflict detection, provenance tracking, and wiki export end-to-end.
+
+![Token breakdown](screenshots/token_breakdown_pie.png)
+*Where tokens go: baseline is all original research. hivememory splits tokens between original research, focused (memory-augmented) queries, and extraction.*
+
+## Setup
+
+- Python 3.10+
+- `pip install hivememory`
+- Set `OPENAI_API_KEY` for LLM-based conflict detection (optional -- embedding-based detection works without it)
+- Run `python examples/basic_usage.py` to verify
+
+## Related work
+
+- Yu et al., "Multi-Agent Memory from a Computer Architecture Perspective: Visions and Challenges Ahead," Architecture 2.0 Workshop (UCSD/CMU), March 2026. Frames multi-agent memory as a systems problem and proposes structured memory hierarchies over flat context passing.
+- Karpathy, "LLM Knowledge Bases" (blog post, 2025). Demonstrates single-agent knowledge accumulation with structured retrieval. hivememory extends this pattern to multi-agent systems, adding conflict detection and provenance tracking across agents.
+
+Single-agent knowledge bases work. hivememory makes them multi-agent.
+
+---
+
+MIT License

hivememory-0.1.0/README.md

@@ -0,0 +1,148 @@
+# hivememory
+
+Shared reasoning memory for multi-agent systems.
+
+When multiple AI agents research the same problem independently, they waste tokens re-deriving the same knowledge and produce contradictory conclusions no one catches. hivememory gives agents a shared memory layer where they store structured reasoning artifacts, reuse each other's work, and surface contradictions automatically.
+
+[Project page (coming soon)](#)
+
+## Results
+
+Benchmark: 3 agents research "Competitive Landscape of AI Code Editors in 2026" using gpt-4o-mini, with and without shared memory. Each agent researches 3 sub-topics. In the shared configuration, agents query hivememory before each LLM call — when prior findings exist, the agent receives a focused prompt that avoids redundant research.
+
+| Metric | Baseline (no shared memory) | hivememory |
+|---|---|---|
+| Total tokens consumed | 11,896 | 9,810 (-17.5%) |
+| Memory-augmented queries | 0 / 9 | 5 / 9 |
+| Output quality (LLM-as-judge, avg 3 runs) | 8.8 | 9.0 |
+| Contradiction-free score | 9.0 | 9.3 |
+| Reuse rate | 0% | 56% |
+| Wall clock time | 113.5s | 101.9s |
+
+Token savings come from agents 2 and 3 receiving memory context that produces shorter, non-redundant LLM responses. Quality is equal or slightly better because memory-augmented agents build on verified findings rather than re-deriving from scratch.
+
+![Token consumption per agent](screenshots/token_consumption_per_agent.png)
+*Agents 2 and 3 use fewer tokens when prior findings are available in memory.*
+
+![Total token consumption](screenshots/token_consumption_total.png)
+
+![Quality comparison](screenshots/quality_comparison.png)
+*LLM-as-judge scores across 4 dimensions, averaged over 3 evaluation runs.*
+
+## Architecture
+
+```
+  agent-1 ──┐                          ┌── conflict detection
+  agent-2 ──┼── hivememory API ────────┼── embedding search (FAISS)
+  agent-3 ──┘    write / query /       └── provenance DAG
+                 resolve / export
+                       │
+                 ┌─────┴─────┐
+                 │  sqlite   │
+                 │  + FAISS  │
+                 │   index   │
+                 └───────────┘
+```
+
+![Artifact reuse flow](screenshots/artifact_reuse_flow.png)
+*How artifacts flow between agents. Agent 1 writes findings; agents 2 and 3 query memory, reuse relevant work, and focus on gaps.*
+
+![Provenance DAG](screenshots/provenance_dag.png)
+*Dependency graph of artifacts. Colors indicate source agent. Edges show "built on" relationships.*
+
+## Quickstart
+
+```bash
+pip install hivememory
+```
+
+```python
+from hivememory import HiveMemory, Evidence
+
+hive = HiveMemory()
+
+# store a finding
+art = hive.write(
+    claim="Voice AI market projected to reach $50B by 2028",
+    evidence=[Evidence(source="industry report", content="35% CAGR", reliability=0.9)],
+    confidence=0.85,
+    agent_id="researcher-1",
+)
+
+# query shared memory before doing new research
+existing = hive.query("voice AI market size", top_k=3)
+
+# check for contradictions
+open_conflicts = hive.get_conflicts()
+
+# resolve
+if open_conflicts:
+    hive.resolve_conflict(open_conflicts[0].id, winner_id=art.id,
+                          reason="stronger evidence", resolved_by="supervisor")
+```
+
+## How it works
+
+### Reasoning artifacts
+
+Agents store structured claims with evidence, confidence scores, and provenance links — not raw text. Each artifact records who produced it, what evidence supports it, and which prior artifacts it builds on. This structure makes artifacts queryable, comparable, and auditable.
+
+### Conflict detection
+
+When a new artifact is stored, hivememory computes its embedding and searches FAISS for similar existing claims. If two artifacts are semantically close but have divergent confidence scores, a conflict is flagged. This first stage can be followed by an LLM contradiction check (OpenAI or Anthropic) for higher-precision detection.
+
+### Provenance tracking
+
+Every artifact records its dependencies as a list of artifact IDs, forming a directed acyclic graph. This DAG answers "which agent's work did this conclusion build on?" and enables cascading invalidation — if an upstream artifact is superseded, downstream consumers can be notified.
+
+## Repo structure
+
+```
+hivememory/
+  __init__.py          # public API exports
+  artifact.py          # ReasoningArtifact, Evidence, Conflict dataclasses
+  core.py              # HiveMemory main class (FAISS + sqlite)
+  store.py             # low-level persistence layer
+  conflicts.py         # ConflictDetector with LLM client support
+  provenance.py        # ProvenanceTracker DAG
+  wiki.py              # WikiExporter — markdown knowledge base export
+examples/
+  basic_usage.py       # store, query, conflict detect, resolve, export
+  research_task.py     # 3-agent research demo with full pipeline
+benchmarks/
+  real_benchmark.py    # real LLM benchmark (gpt-4o-mini)
+  generate_charts.py   # generate all charts from results.json
+  results.json         # raw benchmark data
+  results_summary.md   # human-readable summary
+tests/
+  test_artifact.py     # artifact serialization and ID generation
+  test_store.py        # persistence layer tests
+  test_conflicts.py    # conflict detection tests
+  test_provenance.py   # provenance DAG tests
+```
+
+## Examples
+
+- `python examples/basic_usage.py` — store artifacts, query memory, detect and resolve conflicts, export a wiki. Good first run to verify installation.
+- `python examples/research_task.py` — three agents research AI code editors, sharing findings through hivememory. Shows artifact reuse, conflict detection, provenance tracking, and wiki export end-to-end.
+
+![Token breakdown](screenshots/token_breakdown_pie.png)
+*Where tokens go: baseline is all original research. hivememory splits tokens between original research, focused (memory-augmented) queries, and extraction.*
+
+## Setup
+
+- Python 3.10+
+- `pip install hivememory`
+- Set `OPENAI_API_KEY` for LLM-based conflict detection (optional -- embedding-based detection works without it)
+- Run `python examples/basic_usage.py` to verify
+
+## Related work
+
+- Yu et al., "Multi-Agent Memory from a Computer Architecture Perspective: Visions and Challenges Ahead," Architecture 2.0 Workshop (UCSD/CMU), March 2026. Frames multi-agent memory as a systems problem and proposes structured memory hierarchies over flat context passing.
+- Karpathy, "LLM Knowledge Bases" (blog post, 2025). Demonstrates single-agent knowledge accumulation with structured retrieval. hivememory extends this pattern to multi-agent systems, adding conflict detection and provenance tracking across agents.
+
+Single-agent knowledge bases work. hivememory makes them multi-agent.
+
+---
+
+MIT License

hivememory-0.1.0/hivememory/__init__.py

@@ -0,0 +1,13 @@
+from hivememory.artifact import ReasoningArtifact, Evidence, Conflict
+from hivememory.conflicts import ConflictDetector
+from hivememory.core import HiveMemory
+from hivememory.provenance import ProvenanceTracker
+
+__all__ = [
+    "HiveMemory",
+    "ReasoningArtifact",
+    "Evidence",
+    "Conflict",
+    "ConflictDetector",
+    "ProvenanceTracker",
+]

hivememory-0.1.0/hivememory/artifact.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+
+@dataclass
+class Evidence:
+    source: str
+    content: str
+    reliability: float = 1.0
+
+    def to_dict(self) -> dict:
+        return {
+            "source": self.source,
+            "content": self.content,
+            "reliability": self.reliability,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Evidence:
+        return cls(
+            source=data["source"],
+            content=data["content"],
+            reliability=data.get("reliability", 1.0),
+        )
+
+
+@dataclass
+class ReasoningArtifact:
+    claim: str
+    agent_id: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    evidence: list[Evidence] = field(default_factory=list)
+    confidence: float = 1.0
+    dependencies: list[str] = field(default_factory=list)
+    topic_embedding: list[float] = field(default_factory=list)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    status: str = "active"
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "claim": self.claim,
+            "evidence": [e.to_dict() for e in self.evidence],
+            "confidence": self.confidence,
+            "agent_id": self.agent_id,
+            "dependencies": self.dependencies,
+            "topic_embedding": self.topic_embedding,
+            "created_at": self.created_at.isoformat(),
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ReasoningArtifact:
+        return cls(
+            id=data["id"],
+            claim=data["claim"],
+            evidence=[Evidence.from_dict(e) for e in data.get("evidence", [])],
+            confidence=data.get("confidence", 1.0),
+            agent_id=data["agent_id"],
+            dependencies=data.get("dependencies", []),
+            topic_embedding=data.get("topic_embedding", []),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            status=data.get("status", "active"),
+        )
+
+
+@dataclass
+class Conflict:
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    artifact_ids: list[str] = field(default_factory=list)
+    description: str = ""
+    resolved: bool = False
+    winner_id: Optional[str] = None
+    resolution_reason: Optional[str] = None
+    resolved_by: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "artifact_ids": self.artifact_ids,
+            "description": self.description,
+            "resolved": self.resolved,
+            "winner_id": self.winner_id,
+            "resolution_reason": self.resolution_reason,
+            "resolved_by": self.resolved_by,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Conflict:
+        return cls(
+            id=data["id"],
+            artifact_ids=data.get("artifact_ids", []),
+            description=data.get("description", ""),
+            resolved=data.get("resolved", False),
+            winner_id=data.get("winner_id"),
+            resolution_reason=data.get("resolution_reason"),
+            resolved_by=data.get("resolved_by"),
+        )

hivememory-0.1.0/hivememory/conflicts.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import Optional, Protocol
+
+import numpy as np
+
+from hivememory.artifact import Conflict, ReasoningArtifact
+
+
+class LLMClient(Protocol):
+    def check_contradiction(self, a: ReasoningArtifact, b: ReasoningArtifact) -> str:
+        ...
+
+
+class OpenAIConflictClient:
+    def __init__(self, model: str = "gpt-4o-mini"):
+        import openai
+
+        self.client = openai.OpenAI()
+        self.model = model
+
+    def check_contradiction(self, a: ReasoningArtifact, b: ReasoningArtifact) -> str:
+        a_sources = ", ".join(e.source for e in a.evidence)
+        b_sources = ", ".join(e.source for e in b.evidence)
+        prompt = (
+            "Two research agents produced these findings. "
+            "Do they contradict each other?\n\n"
+            f"Agent {a.agent_id} claims: {a.claim}\n"
+            f"Based on: {a_sources}\n\n"
+            f"Agent {b.agent_id} claims: {b.claim}\n"
+            f"Based on: {b_sources}\n\n"
+            "Respond with exactly one word: "
+            "CONTRADICTS, SUPPORTS, UNRELATED, or REFINES"
+        )
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=10,
+        )
+        return response.choices[0].message.content.strip().upper()
+
+
+class AnthropicConflictClient:
+    def __init__(self, model: str = "claude-haiku-4-5-20251001"):
+        import anthropic
+
+        self.client = anthropic.Anthropic()
+        self.model = model
+
+    def check_contradiction(self, a: ReasoningArtifact, b: ReasoningArtifact) -> str:
+        a_sources = ", ".join(e.source for e in a.evidence)
+        b_sources = ", ".join(e.source for e in b.evidence)
+        prompt = (
+            "Two research agents produced these findings. "
+            "Do they contradict each other?\n\n"
+            f"Agent {a.agent_id} claims: {a.claim}\n"
+            f"Based on: {a_sources}\n\n"
+            f"Agent {b.agent_id} claims: {b.claim}\n"
+            f"Based on: {b_sources}\n\n"
+            "Respond with exactly one word: "
+            "CONTRADICTS, SUPPORTS, UNRELATED, or REFINES"
+        )
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=10,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return response.content[0].text.strip().upper()
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    va = np.array(a, dtype=np.float32)
+    vb = np.array(b, dtype=np.float32)
+    norm_a = np.linalg.norm(va)
+    norm_b = np.linalg.norm(vb)
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return float(np.dot(va, vb) / (norm_a * norm_b))
+
+
+class ConflictDetector:
+    def __init__(
+        self,
+        store,
+        llm_client: Optional[LLMClient] = None,
+    ):
+        self.store = store
+        self.llm_client = llm_client or OpenAIConflictClient()
+
+    def detect(
+        self,
+        new_artifact: ReasoningArtifact,
+        existing_artifacts: list[ReasoningArtifact],
+    ) -> list[Conflict]:
+        if not new_artifact.topic_embedding:
+            return []
+
+        # stage 1: cosine similarity filter
+        candidates = []
+        for existing in existing_artifacts:
+            if not existing.topic_embedding:
+                continue
+            if existing.id == new_artifact.id:
+                continue
+            sim = _cosine_similarity(
+                new_artifact.topic_embedding, existing.topic_embedding
+            )
+            if sim > 0.75:
+                candidates.append(existing)
+
+        # stage 2: LLM verification
+        conflicts = []
+        for candidate in candidates:
+            verdict = self.llm_client.check_contradiction(new_artifact, candidate)
+
+            if verdict == "CONTRADICTS":
+                conflict = Conflict(
+                    artifact_ids=[new_artifact.id, candidate.id],
+                    description=(
+                        f"LLM detected contradiction between "
+                        f"agent {new_artifact.agent_id} and "
+                        f"agent {candidate.agent_id}"
+                    ),
+                )
+                new_artifact.status = "contested"
+                candidate.status = "contested"
+                self.store._save_artifact(new_artifact)
+                self.store._save_artifact(candidate)
+                self.store._save_conflict(conflict)
+                conflicts.append(conflict)
+
+            elif verdict == "REFINES":
+                if candidate.id not in new_artifact.dependencies:
+                    new_artifact.dependencies.append(candidate.id)
+                    self.store._save_artifact(new_artifact)
+
+        return conflicts