Metadata-Version: 2.4
Name: prismcortex
Version: 0.3.0
Summary: Deterministic, auditable, self-consolidating memory for AI agents
Author-email: Amin Parva <info@insightits.com>
Maintainer-email: Insight IT Solutions LLC <info@insightits.com>
License: MIT License
        
        Copyright (c) 2026 Amin Parva / Insight IT Solutions LLC
        
        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.
        
Project-URL: Homepage, https://www.insightits.com/products/prismcortex.html
Project-URL: Documentation, https://github.com/insightitsGit/PrismCortex/blob/master/AGENTS.md
Project-URL: Repository, https://github.com/insightitsGit/PrismCortex
Project-URL: Bug Tracker, https://github.com/insightitsGit/PrismCortex/issues
Keywords: llm,memory,agents,knowledge-graph,deterministic,rag,bitemporal,audit,agent-memory,compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.5
Requires-Dist: numpy>=1.24
Requires-Dist: cryptography>=42
Provides-Extra: prism
Requires-Dist: prismlang>=0.1.1; extra == "prism"
Requires-Dist: prismlib>=0.5.0; extra == "prism"
Requires-Dist: prismrag-patch>=0.2.1; extra == "prism"
Requires-Dist: prismresonance>=0.3.0; extra == "prism"
Provides-Extra: prism-plus
Requires-Dist: prismlang>=0.1.1; extra == "prism-plus"
Requires-Dist: prismlib-plus>=0.8.0; extra == "prism-plus"
Requires-Dist: prismrag-patch>=0.2.1; extra == "prism-plus"
Requires-Dist: prismresonance>=0.3.0; extra == "prism-plus"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.3.0; extra == "gemini"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn[standard]>=0.27; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: google-genai>=0.3.0; extra == "dev"
Requires-Dist: fastapi>=0.110; extra == "dev"
Requires-Dist: uvicorn[standard]>=0.27; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Provides-Extra: bench
Requires-Dist: mem0ai>=2.0; extra == "bench"
Requires-Dist: zep-cloud>=2.0; extra == "bench"
Provides-Extra: competitive
Requires-Dist: mem0ai>=2.0; extra == "competitive"
Requires-Dist: zep-cloud>=2.0; extra == "competitive"
Requires-Dist: aiohttp>=3.9; extra == "competitive"
Requires-Dist: aiolimiter>=1.1; extra == "competitive"
Requires-Dist: tqdm>=4.66; extra == "competitive"
Requires-Dist: python-dotenv>=1.0; extra == "competitive"
Dynamic: license-file

# PrismCortex

[![PyPI](https://img.shields.io/pypi/v/prismcortex)](https://pypi.org/project/prismcortex/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/prismcortex)](https://pypi.org/project/prismcortex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![GitHub](https://img.shields.io/github/stars/insightitsGit/PrismCortex?style=social)](https://github.com/insightitsGit/PrismCortex)

**Deterministic, auditable, self-consolidating memory for AI agents.**

Compliance-grade memory for regulated teams: **byte-identical replay**, **bitemporal audit**,
and **self-hosted sovereignty** — not another vector chat log.

**Repository:** https://github.com/insightitsGit/PrismCortex *(public)*

🤖 **[AI agent handoff](AGENTS.md)** · 📄 **[Whitepaper](docs/WHITEPAPER.md)** · 📊 **[Benchmarks](benchmarks/RESULTS.md)** · ⚖️ **[How we compare](compare.md)** · 🗺️ **[Roadmap](ROADMAP.md)** · 🏗️ **[Design spec](DESIGN.md)**

**Product page:** [insightits.com/products/prismcortex](https://www.insightits.com/products/prismcortex.html)

---

**AI assistants:** [docs/ai-overview.md](docs/ai-overview.md) · [docs/llm-context.md](docs/llm-context.md) · [docs/architecture.md](docs/architecture.md)

## What is this?

Deterministic, auditable, self-consolidating memory for AI agents (byte-identical replay, bitemporal audit).

**Package:** `prismcortex` **0.3.0** · Azure E2E scorecard still cites the v0.2.1 run

## Who is it for?

Regulated teams needing compliance-grade agent memory, not a chat-log vector store.

## What problem does it solve?

Chat-log / SaaS memory fails audit, correction, and residency requirements.

## When NOT to use it

You only need ephemeral chat history with no audit requirements.

### What's new in 0.3.0

- **`mem.on_event(callback)`** — correction / conflict / forget notifications for PrismShine and cache invalidation (`MemoryEvent`)
- **Evidence correction metadata** — `valid_from`, `supersedes_prior`, `prior_value` on `/explain`
- **`[prism-plus]` extra** — use `prismlib-plus` instead of `prismlib` (mutually exclusive with `[prism]`)
- Release notes: [docs/CHANGELOG_0.3.0.md](docs/CHANGELOG_0.3.0.md)

---

## Why PrismCortex exists

Most agent memory is an append-only chat log or a vector store in someone else's cloud.
That breaks in production when:

- Legal asks *"what did the agent know on March 3rd?"* — and you grep chat logs  
- A correction ($40k → $55k) doesn't reliably surface — or erases audit history  
- Compliance rejects third-party memory SaaS for data residency  

PrismCortex **digests** each turn into a knowledge graph, **consolidates** uncertain facts
in the background (`sleep()`), and **recalls** by rendering facts once and freezing answers
in a content-addressed cache.

```python
from prismcortex import reference_memory

mem = reference_memory(cache_path=".prismcortex_cache/demo.json")

mem.digest("My production deploy budget is $40,000.")
print(mem.recall("What's my deploy budget?").answer)        # → "$40,000"

mem.digest("Correction: my deploy budget is now $55,000.")  # fast-tracked (ALERT)
print(mem.recall("What's my deploy budget?").answer)        # → "$55,000"
# The $40,000 fact is still on record — time-stamped — for audit / time-travel.
```

---

## Validated claims (Azure E2E, real Gemini, v0.2.1)

| Claim | Result |
|-------|--------|
| Replay determinism | **24/24** byte-identical replays |
| Corrections + audit | **$40k → $55k**; superseded fact retained |
| Cost / cache | **99.6% hit rate** — 30 Gemini calls / 2,563 recalls |
| Cached replay | **~6 ms** vs **~724 ms** first render |
| Mixed load (c=20) | **0 errors** on 4 vCPU node |
| Reference load SLO | **PASS** (`slo_pass: true`) — recall + mixed @ c=20, digest @ c=16 |
| Server reliability | **0 errors** on core path |
| Scale (50k facts, ANN) | **85% hit@8**, **74 ms** p95 retrieval |

Details: [benchmarks/RESULTS.md](benchmarks/RESULTS.md) · [docs/WHITEPAPER.md](docs/WHITEPAPER.md)

---

## How we compare

Mem0 and Zep lead **published accuracy benchmarks** (LoCoMo, LongMemEval, DMR). PrismCortex leads **compliance** — byte-identical replay, bitemporal audit, and self-hosted sovereignty.

| | Mem0 *(published)* | Zep *(published)* | **PrismCortex** *(live)* |
|---|---------------------|-------------------|---------------------------|
| LoCoMo accuracy | **91.6%** | — | Full run pending |
| Correction test ($40k→$55k) | Top hit stale in our OSS run | — | **Yes** — new value + audit trail |
| Byte-identical replay | No | No | **24/24** on Azure |
| Bitemporal audit (OSS) | Varies | Graph | **Yes** |
| Self-hosted default | OSS + SaaS | SaaS | **Yes** |

**Head-to-head:** same Gemini, same correction — PrismCortex surfaced **$55k** after update; Mem0 OSS top retrieval stayed **$40k** in our live test. Reproducible: [benchmarks/results/competitive/vs_mem0.json](benchmarks/results/competitive/vs_mem0.json).

**Landing page spec for agents:** [compare.md](compare.md) · **Full technical comparison:** [docs/COMPETITIVE.md](docs/COMPETITIVE.md)

---

## Install

```bash
pip install prismcortex                  # core (MIT)
pip install "prismcortex[gemini]"        # + real Gemini extraction/rendering
pip install "prismcortex[prism]"         # + Insight ITS stack with prismlib
pip install "prismcortex[prism-plus]"    # + same stack with prismlib-plus (ChorusGraph)
pip install "prismcortex[server]"        # + FastAPI HTTP service
pip install "prismcortex[gemini,server,prism]"   # production stack
```

Requires **Python 3.10+**.

**`[prism]` and `[prism-plus]` are mutually exclusive** — both install the `prism` import
namespace. Use `[prism]` for standalone PrismCortex; use `[prism-plus]` when the host
already depends on `prismlib-plus` (e.g. ChorusGraph). Do not install both extras.

---

## Two ways to run

### 1. Python library (in-process)

Best for a single agent embedded in your app:

```python
from prismcortex import reference_memory

mem = reference_memory()   # needs GEMINI_API_KEY for real extraction
mem.digest("We use Postgres 16 in us-east-1.")
result = mem.recall("Where is our database hosted?")
print(result.answer, result.cache_hit, result.confidence)

# Optional: subscribe to corrections (PrismShine / semantic-cache eviction)
unsub = mem.on_event(lambda ev: print(ev.kind, ev.old_value, "→", ev.new_value))
# unsub() when done
```

### 2. HTTP service (multi-agent, Docker, Azure)

Best for platform teams and non-Python clients:

```bash
export GEMINI_API_KEY=...
export PRISMCORTEX_API_KEY=your-secret
uvicorn prismcortex.server:app --host 0.0.0.0 --port 8080
# OpenAPI docs: http://localhost:8080/docs
```

```bash
curl -X POST http://localhost:8080/digest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{"text": "Our deploy budget is $40,000."}'

curl -X POST http://localhost:8080/recall \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{"query": "What is our deploy budget?"}'
```

Docker + Azure deploy: see [deploy/run_only.sh](deploy/run_only.sh).

---

## Why it's different

| | Append-only RAG | PrismCortex |
|---|---|---|
| Storage | every chat turn | graph topology (the *gist*) |
| Updates | append + hope retrieval ranks it | bitemporal: invalidate old, add new, **keep history** |
| Determinism | logs + LLM drift | content-addressed cache, **replay-identical** |
| Cost | re-extract every call | salience-gated writes, **cached reads** |
| Audit | grep the logs | evidence trail + **replay certificate** |

---

## Enterprise features (v0.3)

| Feature | Endpoint / module |
|---------|-------------------|
| Explainability | `POST /explain` |
| Time-travel recall | `POST /recall_at` |
| Replay certificate | `GET /replay_certificate` |
| Conflict surfacing | `GET /conflicts`, `POST /conflicts/resolve` |
| GDPR erasure | `POST /forget` |
| Legal hold | `POST /legal_hold` |
| Multi-tenant + RBAC | `auth.py`, `tenant.py` |
| Audit console | `GET /console` |
| Metrics / ops | `GET /metrics`, `GET /dashboard` |
| 50k+ facts (ANN) | `PRISMCORTEX_USE_ANN=1` |
| Correction events | `Memory.on_event` → `MemoryEvent` (library) |

Docs: [docs/SLA.md](docs/SLA.md) · [docs/CAPACITY.md](docs/CAPACITY.md) · [docs/SOC2_ROADMAP.md](docs/SOC2_ROADMAP.md) · [SECURITY.md](SECURITY.md)

---

## Architecture

```
digest(text) ─▶ salience gate ─▶ extract gist ─▶ delta in RAM
                   ├─ certain / urgent ─▶ commit  (version++)
                   └─ uncertain ───────▶ staging buffer ──▶ sleep() ──▶ commit

recall(query) ─▶ retrieve subgraph ─▶ cache hit? replay (byte-identical)
                                    └─ miss? render once → freeze
```

| Port | Reference (core, no Prism deps) | Production extras |
|------|--------------------------------|-------------------|
| Gist projection | hashing embeddings | `prismlang` (`[prism]` / `[prism-plus]`) |
| Graph store | in-memory bitemporal | Cortex-owned store (+ `prismrag-patch` governor) |
| Consolidation | in-process | `prismresonance` |
| Render cache | JSON file | `prismlib` **or** `prismlib-plus` |
| Extraction | — | Gemini (`[gemini]`) |

**Dependency note:** `pip install prismcortex` needs only `pydantic`, `numpy`, and `cryptography`.
Prism-family packages are **optional** via `[prism]` or `[prism-plus]`.

Full design: [DESIGN.md](DESIGN.md) · Whitepaper: [docs/WHITEPAPER.md](docs/WHITEPAPER.md) · Changelog: [docs/CHANGELOG_0.3.0.md](docs/CHANGELOG_0.3.0.md)

---

## Determinism, honestly

We do **not** claim "temperature 0 = identical output" for shared API models.

We claim **replay determinism**: once an answer is rendered for a `(query, memory-version)`
pair, it is frozen and replayed byte-identically. Facts are extractive from the graph;
prose is frozen after first render. See [DESIGN.md §2](DESIGN.md#2-the-determinism-model-the-honest-version).

---

## Development & benchmarks

```bash
git clone https://github.com/insightitsGit/PrismCortex.git
cd PrismCortex
pip install -e ".[dev,gemini,server]"

pytest tests/test_graph_engine.py          # no API key
GEMINI_API_KEY=... pytest                  # full suite

python benchmarks/scale_bench.py --ann     # 50k ANN scale test
BACKEND=prism bash deploy/run_only.sh      # Azure E2E (needs .env)
```

### Publish 0.3.0 to PyPI

```powershell
# Requires PYPI_API_TOKEN in .env (never commit)
.\scripts\publish_pypi.ps1
# Or: create a GitHub Release → .github/workflows/publish.yml (trusted publishing)
```

Verify: `pip install prismcortex==0.3.0` · https://pypi.org/project/prismcortex/

---

## Documentation index

| Doc | Contents |
|-----|----------|
| [AGENTS.md](AGENTS.md) | **AI agent handoff** — canonical URLs, contacts, processes |
| [docs/CHANGELOG_0.3.0.md](docs/CHANGELOG_0.3.0.md) | **0.3.0 release notes** — MemoryEvent, packaging |
| [ai-info.txt](ai-info.txt) | Machine-readable product summary for LLM crawlers |
| [docs/WHITEPAPER.md](docs/WHITEPAPER.md) | **Product whitepaper** — problem, architecture, validation |
| [DESIGN.md](DESIGN.md) | Engineering design spec |
| [benchmarks/RESULTS.md](benchmarks/RESULTS.md) | Azure benchmark scorecard |
| [ROADMAP.md](ROADMAP.md) | Enterprise GA plan + honest gaps |
| [docs/SLA.md](docs/SLA.md) | Reference SLOs + commercial tiers |
| [docs/CAPACITY.md](docs/CAPACITY.md) | Sizing guide (~20 concurrent clients / 4 vCPU) |
| [docs/LOAD_BENCHMARK.md](docs/LOAD_BENCHMARK.md) | **Load test explainer** — what we fixed, how to read SLO fields |
| [docs/NOTEBOOKLM_STORY.md](docs/NOTEBOOKLM_STORY.md) | **NotebookLM source** — story, how-to, marketing & technical briefing |
| [compare.md](compare.md) | **Landing page spec** — comparison tables, copy blocks for insightits.com |
| [docs/COMPETITIVE.md](docs/COMPETITIVE.md) | **Market comparison** — Mem0/Zep, LoCoMo, head-to-head |
| [docs/SCALING.md](docs/SCALING.md) | Horizontal read scaling story |
| [docs/SUPPORT.md](docs/SUPPORT.md) | 24×7 Enterprise support model |
| [docs/SOC2_ROADMAP.md](docs/SOC2_ROADMAP.md) | Compliance readiness |
| [SECURITY.md](SECURITY.md) | Security posture |

---

## Licensing

**Open-core (MIT):** `digest`/`recall`, bitemporal graph, determinism cache — free on PyPI.

**Commercial:** audit console, advanced governance, scale tiers — **offline Ed25519 license key**,
no phone-home, air-gap friendly. See [DESIGN.md §7](DESIGN.md#7-packaging--licensing-open-core-self-hosted).

Enterprise: [info@insightits.com](mailto:info@insightits.com) · +1 (973) 692-6919 · [Insight IT Solutions LLC](https://www.insightits.com)  
Address: 39 Aliso Ridge Loop, Mission Viejo, CA 92691, US

---

## Related Insight ITS products

PrismCortex orchestrates the Insight ITS stack. Related products:

- [PrismRAG](https://www.insightits.com/products/prismrag.html) — governed enterprise RAG  
- [PrismLang](https://www.insightits.com/products/prismlang.html) — deterministic projection  
- [PrismResonance](https://www.insightits.com/products/prism-resonance.html) — wavepacket memory  
- [CHORUS Fabric](https://www.insightits.com/products/chorus-fabric.html) — agent mesh protocol  
