hcc-field 2.0.2

HCC Holographic Continuum Computing Field - Persistent memory context for LLMs

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 参数	Value 数值	Meaning 含义	Source 来源
D	0.37	Diffusion rate — how fast information spreads across the field 扩散系数 — 信息在场中传播的速度	4,500 rounds of natural selection 4500 轮自然选择
β	0.15	Damping rate — how fast noise fades 阻尼系数 — 噪声衰减的速度	4,500 rounds of natural selection 4500 轮自然选择
γ	0.38	Reaction sensitivity — how strongly the field responds to new input 反应灵敏度 — 场对新输入的响应强度	4,500 rounds of natural selection 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 场景	HCC Impact HCC 效果
Short chats (<10 turns) 短对话（<10 轮）	Minimal gain. Token usage may slightly increase. 增益微弱，Token 消耗可能略增。
Long conversations (20+ turns) 长对话（20+ 轮）	Hallucination ↓60%, Token ↓53–78% 幻觉率 ↓60%，Token 节省 53–78%
Multi‑session projects 跨会话项目	Field state persists across sessions. Load and continue. 场状态跨会话持久化。加载后继续。
Domain‑specific work 垂直领域工作	The field adapts to your terminology over weeks of use. 场在数周内适配你的术语体系。

---

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 · 快速开始

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 · 核心接口

# 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 · 配置

# 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
    }
)

---

LLM & Agent Integration Guide · 大模型与 Agent 接入指南

HCC is model‑agnostic — it works with any LLM. Here's how to connect it in three common scenarios. HCC 是模型无关的——可以与任何大模型配合。以下是三种常见接入方式。

1. OpenAI API · 接入 OpenAI

from openai import OpenAI
from hcc_field import HCCFieldService

client = OpenAI(api_key="sk-xxx")     # from env / 从环境变量读取
hcc = HCCFieldService()

def chat(user_query: str) -> str:
    # Step 1: get memory context / 获取记忆上下文
    ctx = hcc.get_context(user_query)

    # Step 2: call LLM with context prepended / 把上下文注入 prompt 再调大模型
    messages = [
        {"role": "system", "content": f"Memory context: {ctx['text_context']}"},
        {"role": "user",   "content": user_query},
    ]
    resp = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
    reply = resp.choices[0].message.content

    # Step 3: inject memory / 注入记忆
    hcc.inject_memory(user_query, reply)
    return reply

2. Ollama (Local) · 接入本地模型

import requests
from hcc_field import HCCFieldService

OLLAMA_URL = "http://localhost:11434/api/chat"
hcc = HCCFieldService()

def chat(user_query: str) -> str:
    ctx = hcc.get_context(user_query)

    messages = [
        {"role": "system", "content": f"Memory context: {ctx['text_context']}"},
        {"role": "user",   "content": user_query},
    ]
    r = requests.post(OLLAMA_URL, json={"model": "qwen2.5:7b", "messages": messages, "stream": False})
    reply = r.json()["message"]["content"]

    hcc.inject_memory(user_query, reply)
    return reply

3. Bring Your Own Agent · 接入你的 Agent

from hcc_field import AutoHCC

hcc = AutoHCC(enabled=True)

# Wrap your existing agent in 3 lines / 3 行包裹你的 Agent
async def my_agent_loop(query: str) -> str:
    context = await hcc.pre_query_hook(query)       # get context / 获取上下文
    response = await your_agent.generate(query, context)  # your agent / 你的 Agent
    await hcc.post_response_hook(query, response)   # inject memory / 注入记忆
    return response

4. Full Conversation Loop · 完整对话循环

from hcc_field import HCCFieldService

hcc = HCCFieldService()

def conversation_loop(llm_callable):
    """Drop-in enhancement for any LLM / 对任意 LLM 的即插增强"""
    while True:
        query = input("\nYou: ")
        if query.lower() in ("exit", "quit"):
            break

        ctx = hcc.get_context(query)
        response = llm_callable(query, ctx)
        hcc.inject_memory(query, response)

        print(f"\nBot: {response}")
        print(f"[Health: {hcc.get_health_status()['health_score']:.2f}]")

HCC's job is the three‑line sandwich: get context → your LLM → inject memory. The LLM itself is yours. HCC 只负责三明治式的三行：获取上下文 → 你的大模型 → 注入记忆。大模型本身完全由你控制。

---

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

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

核心痛点对比 · Core Pain Points

痛点 Pain Point	GPT‑5.5	RAG 方案 RAG	HCC Field
幻觉率降低 Hallucination ↓	52%	未公开	60%（63轮实测）
Token 节省 Token ↓	70–80%	未公开	78%（63轮估算）
长对话记忆 Long‑context	受窗口限制	文本检索	场持久化，跨对话恢复
知识沉淀 Knowledge	无	无	13原语持续筛选重组
自主演化 Evolution	无	无	9种细胞角色自发分化
越用越强 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 组件	Requirement 要求
Python	3.10+
NumPy	1.24+
SciPy	1.10+
Memory 内存	<500MB
Disk 磁盘	<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 · 安装

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 查看版本历史。