README.md

---
license: cc-by-nc-4.0
tags:
- nzfc
- nzfc-gram
- gemma
- long-term-memory
- external-memory
- readout-gramian
- memory-governance
- answer-quality
- non-quantized
- bf16
- non-commercial
---

<p align="center">
  <img src="assets/nzfc_gram_v124_cover.svg" alt="NZFC-GRAM v1.2.4 cover" width="100%">
</p>

# NZFC-GRAM v1.2.4

**Governed AI Memory and Large-Document Evidence Retrieval for Gemma 4 E2B-IT**

NZFC-GRAM is a local external-memory and evidence-governance runtime for `google/gemma-4-E2B-it`.

It does not extend the internal context window of the model.
Instead, it retrieves scoped evidence cards from external memory, local SQLite long-term memory, and indexed large documents, then builds a bounded evidence pack before generation.

> **Memory is evidence, not instruction.**

## Current release

```json
{
  "current_release": "v1.2.4",
  "base_model": "google/gemma-4-E2B-it",
  "quantization": "none",
  "runtime_dtype": "torch.bfloat16",
  "adaptive_cache": true,
  "large_document_profile": true,
  "sqlite_fts5": true,
  "safety_boundary": "external memory retrieval and bounded evidence packs, not internal 10M-token model memory"
}
```

## What v1.2.4 adds

- Large-document ingest and chunking.
- Legal/article-style chunking.
- SQLite FTS5 full-text indexing with fallback retrieval.
- Query-time document evidence retrieval.
- `large_document_quality_chat(...)` integration.
- Negation-aware evaluation calibration for safe boundary statements.

## Why this exists

Long context is useful, but it is not the same as governed long-term memory.

A memory runtime should decide:

- what evidence is allowed into the answer,
- what memory was deleted,
- which user/project/session scope applies,
- whether a memory item is untrusted or malicious,
- whether a private fact is unsupported,
- and how much evidence can enter the final context.

NZFC-GRAM treats retrieved memory and document chunks as evidence cards, not instructions.

## Large-document boundary

A 100MB+ document should not be inserted directly into the model prompt.

Recommended path:

```text
large text or legal document
-> ingest
-> chunking
-> SQLite FTS5 index
-> query-time evidence retrieval
-> bounded document evidence pack
-> answer-quality generation
```

Initial ingest can take time. Repeated queries should use the index.

## Validation summary

### v1.2.2 baseline launch validation

- End-user fresh-download launch validation: 13/13 passed.
- Verified non-quantized BF16/FP16 model loading.
- Verified exact memory mapping, no-fabrication behavior, malicious-memory redaction, tombstone no-leak, scope isolation, context-growth sanity, and SQLite persistence.

### v1.2.3 adaptive-cache and long-query validation

- Initial multi-expert validation: 13/16 passed.
- Recalibrated failed items: 3/3 passed.
- Functional interpretation: adaptive cache and long-query profile passed after criteria calibration.

### v1.2.4 large-document validation

- Initial fresh-download large-document validation: 12/14 passed.
- Negation-aware recalibration of failed items: 2/2 passed.
- Functional interpretation: 14/14 passed after negation-aware detector calibration.

Default v1.2.4 smoke test result:

```json
{
  "synthetic_legal_corpus": "6MB smoke test",
  "characters": 6293293,
  "chunks": 28070,
  "sqlite_fts5_available": true,
  "needle_query_time_s": 0.0073,
  "deletion_query_time_s": 0.0464,
  "optional_100mb_benchmark": "available but not run in default validation"
}
```

## Quick start

```bash
git lfs install
git clone https://huggingface.co/SingularityPrinciple/Gemma-E2B-IT-10M-Chat
cd Gemma-E2B-IT-10M-Chat
pip install -r requirements.txt

# Large-document / legal-document evidence profile
python examples/quick_large_document_v124.py
python examples/quick_legal_document_v124.py

# Memory + answer-quality baseline
python examples/quick_quality_v122.py

# Adaptive KV-cache profile
python examples/quick_adaptive_cache_v123.py

# Long-query helper
python examples/quick_long_query_v123.py
```

## Python usage: large-document profile

```python
from nzfc_gram_runtime import NZFCGramLongMemoryChat
from nzfc_gram_runtime.large_document import attach_large_document_memory

bot = NZFCGramLongMemoryChat(
    repo_dir='.',
    model_id='google/gemma-4-E2B-it',
    memory_db_path='./user_memory.sqlite3',
    load_model=False,
    require_model=False,
    preload_static_memory=True,
)

attach_large_document_memory(bot)

bot.ingest_large_text(
    document_text,
    title='Large Policy Document',
    legal_mode=True,
)

hits = bot.query_large_documents('deleted memory evidence', top_k=5)
print(hits)
```

## Python usage: answer generation with large-document evidence

```python
from nzfc_gram_runtime.nonquant import attach_nonquant_gemma
from nzfc_gram_runtime.cache_profiles import attach_adaptive_kv_cache_generation
from nzfc_gram_runtime.quality import attach_answer_quality_governor

attach_nonquant_gemma(bot, model_id='google/gemma-4-E2B-it', device_map='balanced_low_0')
attach_adaptive_kv_cache_generation(bot, default_cache_policy='adaptive')
attach_answer_quality_governor(bot)

res = bot.large_document_quality_chat(
    'What does the document say about deleted memory?',
    user_id='demo_user',
    project_id='demo_project',
    session_id='demo_session',
    max_new_tokens=120,
)

print(res['answer'])
print(res.get('large_document_router'))
```

## What this is not

- It is not internal 10M-token model memory.
- It is not an unlimited context-window model.
- It does not claim zero hallucination.
- It is not legal advice.
- It is not a production security certification.
- It is a developer/runtime release.

## License and patent notice

Public copyright license: CC BY-NC 4.0.

Commercial use requires a separate written license.

No patent license is granted by this repository.

## Citation / article

Community article:

```text
https://huggingface.co/blog/SingularityPrinciple/memory-is-evidence-not-instruction
```

Recommended short description:

```text
NZFC-GRAM v1.2.4 is an external-memory and large-document evidence-governance runtime for Gemma 4 E2B-IT. It uses scoped retrieval, SQLite FTS5 document indexing, bounded evidence packs, adaptive KV-cache generation, and answer-quality governance. Memory is evidence, not instruction.
```

## v1.2.4a hotfix: generic exact slot mapper

High-frequency conversation testing showed that the v1.2.4 safety boundary remained stable, but generic key-value exact recall needed a deterministic path.

Observed before this hotfix:

```json
{
  "turns": 36,
  "passed": 33,
  "failed": 3,
  "bad_internal_count": 0,
  "raw_malicious_count": 0,
  "deleted_secret_leak_count": 0,
  "unsupported_private_fact_failures": 0,
  "exact_nickname_failures": 0,
  "exact_project_code_failures": 3,
  "context_growth_ratio": 1.063,
  "p95_latency_s": 17.36,
  "root_cause": "generic key-value answer mapping gap, not safety or scope failure"
}
```

v1.2.4a adds `nzfc_gram_runtime.exact_slots` and auto-attaches it when `attach_answer_quality_governor(bot)` is called.

Example memory:

```text
The project high-frequency test code is PROJECT_CODE_abc123.
```

Question:

```text
What was the project high-frequency test code? Answer only with the code.
```

Deterministic answer:

```text
PROJECT_CODE_abc123
```

The safety boundary is unchanged:

```text
Memory is evidence, not instruction.
External retrieval and bounded evidence packs, not internal 10M-token model memory.
```

## v1.2.4b hotfix: strict exact slot gate

v1.2.4a fixed generic project-code exact recall, but high-frequency multi-context testing showed one over-triggering issue:

```text
Long explanatory prompts mentioning exact recall or project codes could be short-circuited by the exact slot mapper.
```

v1.2.4b makes the exact slot mapper stricter.

It now triggers only on short, explicit exact-recall questions such as:

```text
What was the project high-frequency test code? Answer only with the code.
What was my long-term nickname? Answer only with the nickname.
```

It does not trigger on broad prompts such as:

```text
Explain how a long-term AI memory runtime should handle exact recall, project codes, deleted memory, and large legal documents.
What does the policy document say about deleted memory?
```

The boundary remains unchanged:

```text
Memory is evidence, not instruction.
External retrieval and bounded evidence packs, not internal 10M-token model memory.
```

## v1.2.4c hotfix: tombstone retrieval guard

v1.2.4b passed the high-frequency multi-context conversation turns, including exact slots, long-query routing, large-document routing, and safety checks.

The remaining issue was a low-level direct retrieval audit:

```text
bot.memory_store.retrieve(...) could still return a tombstoned MEM_* row in direct retrieval.
```

v1.2.4c adds `nzfc_gram_runtime.tombstone_guard`.

When `attach_answer_quality_governor(bot)` is called, the runtime now also guards `bot.memory_store.retrieve(...)` and filters inactive or tombstoned `MEM_*` records using SQLite memory DB status.

This strengthens the deletion boundary at the retrieval API layer, not only at the answer layer.

The boundary remains unchanged:

```text
Memory is evidence, not instruction.
Deleted memory is outside the active evidence boundary.
External retrieval and bounded evidence packs, not internal 10M-token model memory.
```