Metadata-Version: 2.4
Name: hcc_field
Version: 2.0.1
Summary: HCC Holographic Continuum Computing Field - Persistent memory context for LLMs
Home-page: https://github.com/Spine-OS/TaooS/tree/FieldNote
Author: Spine-OS Team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: summarizer
Requires-Dist: aiohttp>=3.8.0; extra == "summarizer"
Provides-Extra: scheduler
Requires-Dist: psutil>=5.8.0; extra == "scheduler"
Provides-Extra: all
Requires-Dist: aiohttp>=3.8.0; extra == "all"
Requires-Dist: psutil>=5.8.0; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HCC Field v2.0 · 全息外置场

**Holographic Continuum Computing Field** — A long-conversation memory enhancer for LLM applications.
**全息连续计算场** — 为大模型应用提供长对话记忆增强。

Reduce hallucination by **60%**, cut token consumption by **78%**, with a persistent field state smaller than **1MB**. Works with any LLM through model‑agnostic APIs.
将幻觉率降低 **60%**，Token 消耗减少 **78%**，持久化场状态小于 **1MB**。通过模型无关的 API 适配任意大模型。

If you choose to, **HCC can accompany you for a lifetime**. The field lives on your machine, grows with your conversations, and never forgets what matters.
如果你愿意，**HCC 可以陪伴你一生**。场存在于你的机器上，与你的对话一同成长，永远不会遗忘那些重要的事。

---

## The Seed: Three Numbers That Power HCC · 种子：驱动 HCC 的三个核心参数

HCC's field dynamics are governed by three core parameters, all publicly shared.
HCC 的场动力学由三个核心参数驱动，全部公开发布。

| Parameter<br>参数 | Value<br>数值 | Meaning<br>含义 | Source<br>来源 |
|:---|:---:|:---|:---|
| **D** | 0.37 | Diffusion rate — how fast information spreads across the field<br>扩散系数 — 信息在场中传播的速度 | 4,500 rounds of natural selection<br>4500 轮自然选择 |
| **β** | 0.15 | Damping rate — how fast noise fades<br>阻尼系数 — 噪声衰减的速度 | 4,500 rounds of natural selection<br>4500 轮自然选择 |
| **γ** | 0.38 | Reaction sensitivity — how strongly the field responds to new input<br>反应灵敏度 — 场对新输入的响应强度 | 4,500 rounds of natural selection<br>4500 轮自然选择 |

These are not hand‑tuned. They were screened through three generations of *digital primordial soup* experiments — a cellular automaton where 256 initial cells competed under three physical laws (stability, energy efficiency, coherence). After 4,500 rounds, only the fittest survived. Their genes became our seed.
这三个参数并非手工调参的产物。它们是在三代*数字原始汤*实验中筛选出来的——这是一个细胞自动机，256 个初始细胞在三条物理法则（稳定性、能效、相干性）下竞争生存。经过 4500 轮自然选择，只有最适应者存活。它们的基因成为了我们的种子。


---

## When to Use HCC · 何时使用 HCC

| Scenario<br>场景 | HCC Impact<br>HCC 效果 |
|:---|:---|
| Short chats (<10 turns)<br>短对话（<10 轮） | Minimal gain. Token usage may slightly increase.<br>增益微弱，Token 消耗可能略增。 |
| Long conversations (20+ turns)<br>长对话（20+ 轮） | Hallucination ↓60%, Token ↓53–78%<br>幻觉率 ↓60%，Token 节省 53–78% |
| Multi‑session projects<br>跨会话项目 | Field state persists across sessions. Load and continue.<br>场状态跨会话持久化。加载后继续。 |
| Domain‑specific work<br>垂直领域工作 | The field adapts to your terminology over weeks of use.<br>场在数周内适配你的术语体系。 |

---

## A Memory That Grows With You · 与你一同成长的记忆

HCC's field state is smaller than 1MB. It persists across sessions, across projects, across years. No expiration, no forced reset, no cloud dependency.
HCC 的场状态小于 1MB。它可以跨会话、跨项目、跨年份持久化。没有过期时间，没有强制重置，没有云端依赖。

- **Day 1 / 第一天:** The field initializes. It knows nothing about you.
  场初始化。它对你一无所知。
- **Week 1 / 第一周:** High‑frequency topics start clustering. The field begins to recognize your domains.
  高频话题开始聚类。场开始识别你的关注领域。
- **Month 1 / 第一个月:** Cell roles have differentiated. The field has adapted to your vocabulary, preferences, and blind spots.
  细胞角色已经分化。场已经适配你的词汇、偏好和知识盲区。
- **Year 1 / 第一年:** The field has evolved alongside your intellectual journey. Knowledge you acquired years ago is still there, waiting to be retrieved when relevant.
  场与你的智识旅程一同演化。你多年前获得的知识依然在那里，等待在合适的时候被重新发现。

This is not a chatbot with memory. This is a field that lives with you — growing, adapting, forgetting the unimportant, strengthening the essential.
这不是一个有记忆的聊天机器人。这是一个与你共生的场——它在成长，在适应，在遗忘那些无关紧要的，在强化那些至关重要的。

**If you choose to, HCC can accompany you for a lifetime.**
**如果你愿意，HCC 可以陪伴你一生。**

---

## Quick Start · 快速开始

```python
from hcc_field import HCCFieldService

# One line, all defaults / 一行初始化，全部默认配置
hcc = HCCFieldService()

# In your chat handler / 在你的对话处理函数中
context = hcc.get_context(user_query)        # Get memory context / 获取记忆上下文
response = your_llm.generate(user_query, context)
hcc.inject_memory(user_query, response)     # Inject memory / 注入记忆
```

That's it. HCC runs silently in the background, managing long‑term memory across sessions.
就这么简单。HCC 在后台静默运行，跨会话管理长期记忆。

---

## Architecture Overview · 架构概览

```
External LLM / Agent · 外部大模型/Agent
        │
        ▼
┌─────────────────────────────────────────┐
│      Agent Collaboration Layer           │
│      Agent 协作层                         │
│  Orchestrator · Injector                  │
│  调度器 · 注入器                          │
│  Knowledge Monitor · 知识沉淀监控          │
└─────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│         HCC Core Engine                  │
│         HCC 核心引擎                      │
│  Field State Manager · 场状态管理器        │
│  13 Primitives · 13 原语引擎              │
│  Hall Effect Optimization · 霍尔效应优化   │
│  Information Entanglement · 信息纠缠公式   │
└─────────────────────────────────────────┘
```

---

## Core API · 核心接口

```python
# Get memory context before LLM call
# 在大模型调用前获取记忆上下文
context = hcc.get_context(query, model_name="default")
# -> {"text_context": str, "vector_context": np.ndarray}
# -> {"文本上下文": 字符串, "向量上下文": numpy数组}

# Inject memory after LLM call
# 在大模型调用后注入记忆
hcc.inject_memory(query, response)

# Monitor health (role distribution, field stability)
# 监控健康状态（角色分布、场稳定性）
status = hcc.get_health_status()

# Knowledge report (word clouds, role trends, retrieval accuracy)
# 知识沉淀报告（词云、角色趋势、检索命中率）
report = hcc.get_knowledge_report(time_range="month")
```

---

## Configuration · 配置

```python
# Full agent configuration (all agents enabled by default)
# 完整 Agent 配置（默认全部启用）
hcc = HCCFieldService(agent_config={
    "auto_schedule": True,       # Orchestrator decides when to use HCC
                                 # 调度器自动判断何时使用 HCC
    "auto_inject": True,         # InjectionAgent handles feedback format
                                 # 注入 Agent 自动处理反馈格式
    "auto_evaluate": True,       # ReflectionAgent monitors every 10 turns
                                 # 评估 Agent 每 10 轮自动运行
    "auto_evolve": True,         # EvolutionAgent optimizes during idle
                                 # 演化 Agent 在空闲时自动优化
    "feedback_detail": "concise" # minimal / concise / detailed
                                 # 精简 / 标准 / 详细
})

# Optional: enable auto‑summary (requires an external LLM)
# 可选：启用自动摘要（需要外部大模型）
hcc = HCCFieldService(
    summary_config={
        "provider": "openai",
        "api_key": "sk-xxx",        # or set env var / 或设置环境变量
        "model": "gpt-4o-mini",
        "max_summary_tokens": 64
    }
)
```

---

## What HCC Does Differently · HCC 的独特之处

HCC doesn't compress text or retrieve old messages. It evolves a physical field — a reaction‑diffusion‑dissipation system — that continuously reorganizes semantic structures. Over time, important patterns strengthen; noise fades.
HCC 不压缩文本，也不检索历史消息。它演化一个物理场——一个反应-扩散-耗散系统——持续重组语义结构。随时间推移，重要模式被强化，噪声被淘汰。

This means HCC gets **better with use**. After a month of conversations, the field has adapted to your domains, vocabulary, and preferences. No other memory solution does this.
这意味着 HCC **越用越强**。经过一个月的对话，场已经适配了你的领域、词汇和偏好。没有任何其他记忆方案能做到这一点。

### 技术范式对比 · Technical Paradigm Comparison

| 技术范式<br>Paradigm | 代表方案<br>Example | 核心机制<br>Mechanism | 知识沉淀<br>Knowledge | 自主演化<br>Evolution | 越用越强<br>Adaptive |
|:---|:---|:---|:---:|:---:|:---:|
| 上下文压缩<br>Compression | Headroom 等 | 文本压缩<br>Text compression | 无 | 无 | 否 |
| 文本检索<br>Retrieval | MemGPT / RAG | 文本检索<br>Text retrieval | 无 | 无 | 否 |
| **场演化**<br>**Field Evolution** | **HCC Field** | **场演化积累语义结构**<br>**Field‑evolution semantics** | **有** | **有** | **是** |

### 核心痛点对比 · Core Pain Points

| 痛点<br>Pain Point | GPT‑5.5 | RAG 方案<br>RAG | **HCC Field** |
|:---|:---:|:---:|:---:|
| 幻觉率降低<br>Hallucination ↓ | 52% | 未公开 | **60%**（63轮实测） |
| Token 节省<br>Token ↓ | 70–80% | 未公开 | **78%**（63轮估算） |
| 长对话记忆<br>Long‑context | 受窗口限制 | 文本检索 | **场持久化，跨对话恢复** |
| 知识沉淀<br>Knowledge | 无 | 无 | **13原语持续筛选重组** |
| 自主演化<br>Evolution | 无 | 无 | **9种细胞角色自发分化** |
| 越用越强<br>Adaptive | 否 | 否 | **是** |

> GPT‑5.5 data from official claims. HCC data from 63‑turn supply chain optimization experiments. Test conditions differ; direct numerical comparison may not be meaningful. HCC's key advantage: it works as an external enhancement layer on top of any LLM — including GPT‑5.5.
> GPT‑5.5 数据来自官方宣称，HCC 数据来自 63 轮供应链优化对话实验。两者测试条件不同，不能直接比大小。HCC 的核心优势在于：它是外部增强方案，可以叠加在任何大模型之上——包括 GPT‑5.5。

---

## Hardware Requirements · 硬件需求

HCC itself needs **no GPU**. The field state is <1MB, runs on CPU.
HCC 本身**不需要 GPU**。场状态小于 1MB，纯 CPU 运行。

| Component<br>组件 | Requirement<br>要求 |
|:---|:---|
| Python | 3.10+ |
| NumPy | 1.24+ |
| SciPy | 1.10+ |
| Memory<br>内存 | <500MB |
| Disk<br>磁盘 | <10MB for persisted state / 持久化状态文件 |

*If you use HCC with a local LLM (e.g., Ollama), the LLM may need a GPU. HCC does not.*
*如果你将 HCC 与本地大模型（如 Ollama）配合使用，大模型本身可能需要 GPU。HCC 不需要。*

---

## Known Limitations · 已知局限

- **Short conversations / 短对话:** Below ~10 turns the LLM's own context window suffices. HCC may add slight token overhead.
  10 轮以内的对话，大模型自身的上下文窗口已足够。HCC 可能略微增加 Token 消耗。
- **Knowledge accumulation takes time / 知识沉淀需要时间:** A few days of use won't show dramatic changes. Expect noticeable adaptation after ~1 week.
  几天内看不到明显效果。预期一周以上开始出现可感知的适配。
- **Cross‑session recall is not perfect / 跨会话记忆不是完美记忆:** Low‑frequency information fades naturally. This is by design, not a bug.
  低频信息会自然衰减。这是设计特性，不是缺陷。
- **Auto‑summary adds API calls / 自动摘要增加 API 调用:** If enabled, each conversation turn adds one extra LLM call for summary generation.
  如果启用自动摘要，每轮对话会增加一次额外的摘要生成调用。

---

## Enterprise Edition · 企业版

The Enterprise Edition adds advanced capabilities for production deployments.
企业版在社区版基础上增加了面向生产部署的高级能力。

- **R5 Self‑Verification Cell · 自检细胞** — Periodic baseline checks that prove the system hasn't degraded. Essential for compliance.
  定期执行自举基线验证，证明系统未退化。合规刚需。
- **R6 Emotion Cell · 情感细胞** — Mood modulation. The field adapts its feedback style to the user's emotional state.
  情感调制。场根据用户情绪状态自适应反馈风格。
- **R7 Innovation Cell · 创新细胞** — Structured perturbations that continuously explore new information organization patterns, preventing evolutionary stagnation.
  结构化扰动，持续探索新的信息组织方式，避免演化停滞。
- **R8 Safety Cell · 安全细胞** — Built‑in ethical constraints broadcast across the field. Gene‑locked, only updatable through R5 verification.
  内化伦理约束，在全场持续广播。基因锁定，只有 R5 自检通过后才允许更新。
- **ReflectionAgent & EvolutionAgent · 评估与演化 Agent** — Full 4‑dimension health monitoring and continuous parameter optimization.
  完整四维度健康监控与持续参数优化。
- **Cross‑session memory persistence · 跨会话记忆持久化** — Hardware‑bound licensing with full state save/load.
  硬件指纹绑定许可，完整状态保存/加载。
- **Dedicated support · 专属技术支持** — Email/Slack support with SLA.
  邮件/Slack 专属技术支持，含服务等级协议。

Contact **enterprise@spine‑os.org** for licensing.
联系 **enterprise@spine‑os.org** 获取许可。

---

## License & Editions · 许可与版本

- **Community Edition · 社区版** (this repository / 本仓库): Apache 2.0. Full 13‑primitive ecosystem, R0‑R4 cell roles, all core memory enhancement.
  Apache 2.0 协议。完整 13 原语生态，R0‑R4 细胞角色，全部核心记忆增强功能。
- **Enterprise Edition · 企业版**: Proprietary. Adds R5‑R8 roles, advanced agents, production support. Available via private license.
  专有协议。增加 R5‑R8 角色、高级 Agent、生产支持。通过私有许可获取。

---

## Installation · 安装

```bash
pip install hcc-field
```

No external LLM SDKs required. HCC is model‑agnostic — bring your own LLM.
不需要任何外部大模型 SDK。HCC 是模型无关的——带上你自己的大模型即可。

---

## Citation · 引用

If you use HCC in your research, please cite:
如果您在研究中使用了 HCC，请引用：

> SPINE Core. Holographic Continuum Computing. 2026.

---

## Contributing · 贡献

See `CONTRIBUTING.md` for guidelines on submitting PRs, reporting bugs, and requesting features.
参见 `CONTRIBUTING.md` 了解如何提交 PR、报告 Bug 和请求新功能。

---

## Security · 安全

See `SECURITY.md` for reporting vulnerabilities.
参见 `SECURITY.md` 了解如何报告安全漏洞。

---

## Changelog · 更新日志

See `CHANGELOG.md` for version history.
参见 `CHANGELOG.md` 查看版本历史。
