Metadata-Version: 2.4
Name: dna-memory-sdk
Version: 0.1.0
Summary: DNA-inspired memory SDK for AI cognitive computing
Author-email: ShellB <shellb@cput.dev>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hbfbee-sys/cput-sdk
Project-URL: Repository, https://github.com/hbfbee-sys/cput-sdk
Project-URL: Issues, https://github.com/hbfbee-sys/cput-sdk/issues
Keywords: dna,memory,ai,cognitive-computing,biological-computing
Classifier: Development Status :: 3 - Alpha
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Dynamic: license-file

# CPUT DNA Memory SDK

<div align="center">

**基于物理公理构建的生物启发式持久记忆引擎**

`v0.1.0` · [CPUT理论框架](https://github.com/hbfbee-sys) · Apache 2.0

[安装](#安装) · [快速开始](#快速开始) · [API文档](#api文档) · [架构设计](#架构设计) · [性能基准](#性能基准)

</div>

---

## 这是什么？

DNA Memory SDK 是一个**从第一原理物理公理推导出的记忆系统**，将信息编码为自描述的DNA序列。

不同于传统的向量数据库或键值存储：

| 特性 | 向量数据库 | 键值存储 | **DNA Memory SDK** |
|------|-----------|----------|-------------------|
| 编码方式 | 浮点向量 | 字符串→值 | **4bp碱基序列** |
| 信息密度 | 低（128-1536维） | 中等 | **每节点仅4bp** |
| 结构 | 扁平 | 扁平 | **树状层级 + DNA双链** |
| 遗忘机制 | 无 | TTL过期 | **甲基化衰减 + 睡眠巩固** |
| 可解释性 | 黑箱 | 透明 | **完全可审计（从公理推导）** |
| 生物兼容 | ❌ | ❌ | **FASTA导出 / GC含量 / 互补配对** |

## 核心概念

```
┌──────────────────────────────────────────────────────────────┐
│                    DNA Memory SDK 架构                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐   encode()   ┌──────────────────────────┐  │
│  │ (d1,d2,d3,  │──────────────▶│ 自描述DNA片段             │  │
│  │  label)     │              │ ┌────┬────┬─────┬────┐   │  │
│  │             │              │ │ T11│ ID │内容 │ T11│   │  │
│  └─────────────┘              │ └────┴────┴─────┴────┘   │  │
│                                └──────────────────────────┘  │
│                                         │                    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              GrowableDNAMemory                       │    │
│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌──────────────┐ │    │
│  │  │write│ │read │ │search│ │decay│ │sleep_consolid│ │    │
│  │  └─────┘ └─────┘ └─────┘ └─────┘ └──────────────┘ │    │
│  │                                                      │    │
│  │  树状结构:    [1] 根记忆                              │    │
│  │               ├── [2] 子记忆A  met=████░ 0.80        │    │
│  │               ├── [3] 子记忆B  met=██░░░ 0.40        │    │
│  │               └── [4] 子记忆C  met=░░░░░ 0.05 → 衰减  │    │
│  └─────────────────────────────────────────────────────┘    │
│                           │                                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              DNACoupling (可选)                      │    │
│  │                                                      │    │
│  │  正向: Agent状态 ──record_state()──▶ DNA记忆         │    │
│  │  反向: DNA记忆   ──get_modulation()──▶ 调制信号      │    │
│  │  闭环: 行为结果  ──update_association()──▶ 强化/弱化  │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

## 安装

```bash
pip install dna-memory
```

或从源码安装：

```bash
git clone https://github.com/hbfbee-sys/dna-memory.git
cd cput-sdk
pip install -e .
```

## 快速开始

### 基础用法

```python
from dna_memory import GrowableDNAMemory

# 创建记忆系统
mem = GrowableDNAMemory()

# 写入记忆 — 每条记忆由节点组成
# 节点格式: (d1, d2, d3, label), 其中 d1/d2/d3 ∈ {0,1,2,3}
seg_id = mem.write(
    title='学习Transformer架构',
    nodes_data=[
        (1, 2, 3, 'Self-Attention'),
        (0, 3, 1, 'Multi-Head'),
        (2, 1, 0, 'Position-Encoding'),
    ],
    initial_methylation=0.5  # 初始保护度
)

# 读取记忆 — 返回完整解码结果
result, err = mem.read(seg_id)
print(f"标题: {result['title']}")
print(f"DNA链: {result['dna_forward']}")
print(f"节点数: {result['node_count']}")

# 搜索记忆
matches = mem.search('Transformer')

# 查看记忆树
print(mem.list_tree())

# 基因组统计
stats = mem.get_genome_stats()
print(f"基因组: {stats['total_bp']}bp, GC含量: {stats['gc_content']:.1f}%")
```

### 树状记忆结构

```python
# 生长子记忆 — 形成层级结构
child_id = mem.grow(
    parent_seg_id=seg_id,
    title='Attention计算细节',
    nodes_data=[
        (1, 1, 1, 'Q=xW_q'),
        (2, 2, 2, 'K=xW_k'),
        (3, 3, 3, 'V=xW_v'),
    ]
)

# 查看树结构
print(mem.list_tree())
# [1] 学习Transformer架构 (3节点, met=██░░░ 0.50)
#   [2] Attention计算细节 (3节点, met=░░░░░ 0.00)
```

### 记忆生命周期

```python
import numpy as np

# 强化重要记忆（提高甲基化保护）
mem.reinforce(seg_id, boost=0.3)  # met: 0.5 → 0.8

# 睡眠巩固 — 模拟生物记忆整理
mem.sleep_consolidation('N3')   # 深睡: 强化重要记忆, 弱化无用记忆
mem.sleep_consolidation('REM')  # 梦眠: 随机重组, 创造新关联

# 记忆衰减 — 模拟自然遗忘
for step in range(100, 200):
    mem.apply_decay(current_step=step, decay_rate=0.001)

# 删除记忆
mem.delete(seg_id)  # 删除片段及其所有子片段
```

### 持久化

```python
# JSON格式保存/加载
mem.save('my_memories.json')
mem.load('my_memories.json')

# FASTA格式导出（生物信息学兼容）
mem.export_genome_fasta('genome.fasta')
# >seg_1 | 学习Transformer架构 | met=0.800 | 53bp
# TGACTGACTGAACGTGACAGACTGACTGACTGACATCGAT...
```

### 与AI Agent集成

```python
from dna_memory import GrowableDNAMemory, DNACoupling

mem = GrowableDNAMemory()
coupling = DNACoupling(mem, snapshot_interval=5)

# === 在你的Agent循环中 ===

for step in range(1000):
    # 1. Agent执行动作
    state = agent.get_state()  # {'confidence': 0.8, 'task': 'planning', ...}
    action = agent.act(state)
    reward = env.step(action)
    
    # 2. 正向: 记录经验到DNA
    coupling.record_state(state, step=step)
    
    # 3. 事件触发记录（不受interval限制）
    if reward > 0.9:
        coupling.record_event('high_reward', {'reward': reward, 'step': step}, step)
    
    # 4. 反向: 从DNA记忆中获取调制信号
    modulation = coupling.get_modulation(state)
    agent.apply_modulation(modulation['modulation_values'])
    
    # 5. 闭环: 更新记忆关联值
    for match in modulation['top_matches']:
        coupling.update_association(match['seg_id'], outcome=reward)
    
    # 6. 周期性衰减
    if step % 50 == 0:
        mem.apply_decay(step)
    
    # 7. 定期睡眠巩固
    if step % 200 == 0:
        mem.sleep_consolidation('N3')
        mem.sleep_consolidation('REM')
```

## API文档

### GrowableDNAMemory

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `write()` | title, nodes_data, parent_seg_id?, initial_methylation? | int (seg_id) | 写入新记忆 |
| `read()` | seg_id | (dict, None) 或 (None, str) | 读取记忆 |
| `grow()` | parent_seg_id, title, nodes_data | int (seg_id) | 生长子记忆 |
| `update()` | seg_id, new_nodes_data, new_title? | None | 更新记忆内容 |
| `delete()` | seg_id | bool | 删除记忆（含子片段） |
| `search()` | keyword | list[dict] | 关键词搜索 |
| `reinforce()` | seg_id, boost? | None | 甲基化强化 |
| `apply_decay()` | current_step, decay_rate? | int (清除数量) | 记忆衰减 |
| `sleep_consolidation()` | sleep_stage ('N3'/'REM') | dict (统计) | 睡眠巩固 |
| `get_genome_stats()` | — | dict | 基因组统计 |
| `list_tree()` | — | str | 树状可视化 |
| `save()` | filepath | None | 保存为JSON |
| `load()` | filepath | None | 从JSON加载 |
| `export_genome_fasta()` | filepath | None | 导出FASTA |

### DNACoupling

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `record_state()` | state, step, title?, force? | int (seg_id) | 记录状态快照 |
| `record_event()` | event_type, data, step, priority? | int (seg_id) | 记录重要事件 |
| `detect_phase_transition()` | current_phase, step | int (seg_id) | 检测相态跃迁 |
| `get_modulation()` | current_state | dict | 获取调制信号 |
| `update_association()` | seg_id, outcome | None | 更新关联值 |
| `set_state_encoder()` | encoder_fn | None | 自定义编码器 |
| `set_similarity_function()` | sim_fn | None | 自定义相似度 |

### 编解码函数

```python
from dna_memory import encode_node, decode_node, encode_id, decode_id

# 节点编码: (d1,d2,d3) → 4bp DNA
enc = encode_node(1, 2, 3)
# {'dna_4bp': 'CTAC', 'h_code': 27, 'struct_type': 'S-', ...}

# 节点解码: 4bp DNA → (d1,d2,d3)
dec = decode_node('CTAC')
# {'d1': 1, 'd2': 2, 'd3': 3, 'chirality_valid': True, ...}

# ID编码: int → 8bp DNA
id_dna = encode_id(12345)  # 'GCTAGCTA'

# ID解码: 8bp DNA → int
id_val = decode_id('GCTAGCTA')  # 12345
```

## 架构设计

### 编码体系

每个信息节点 `(d1, d2, d3)` 通过三层Ring编码映射为4bp DNA序列：

```
d1 ∈ {0,1,2,3} ──Ring0──▶ b0 ∈ {A,C,T,G}  ← 基础维度
d2 ∈ {0,1,2,3} ──Ring1──▶ b1 ∈ {G,A,C,T}  ← 旋转维度
d3 ∈ {0,1,2,3} ──Ring2──▶ b2 ∈ {C,T,G,A}  ← 拓扑维度
chirality      ──Chiral──▶ b3 ∈ {A,G,C}    ← 手性校验位
```

64种节点类型 × 手性校验 = 结构化信息编码，支持：
- **正向链/反向链**（Watson-Crick互补配对）
- **自描述片段**（包含ID、父ID、内容、校验和）
- **11T边界标记**（结构性连接器 `TGACTGACTGA`）

### 记忆生命周期

```
写入(write) → 甲基化=0.0 → 强化(reinforce) → 甲基化↑
                              ↓
              睡眠巩固 ←── 日常运行 ←── 衰减(decay)
              N3: 强化重要记忆     → 甲基化衰减
              REM: 创造新关联      → 甲基化=0 → 清除
```

## 性能基准

测试环境: Python 3.11, Mac Mini M4 Pro

| 操作 | 延迟 | 吞吐量 |
|------|------|--------|
| 单片段写入(3节点) | 0.18ms | 5,500 ops/sec |
| 单片段写入(1节点×100) | 0.087ms/op | 11,500 ops/sec |
| 片段读取 | 0.02ms | 50,000 ops/sec |
| 片段搜索 | 0.02ms | 50,000 ops/sec |
| N3深睡巩固 | 0.04ms | 25,000 ops/sec |
| REM梦眠重组 | 0.05ms | 20,000 ops/sec |
| 1000次批量写入(2节点) | 0.17ms/op | 5,778 ops/sec |

压缩比:
- 201片段基因组 vs JSON: **1.8:1**
- 白皮书结构化数据 vs JSON: **299:1**

## 使用场景

1. **AI Agent 持久记忆** — Agent跨会话积累经验，不再"失忆"
2. **边缘设备记忆** — 轻量级，CPU可运行，不依赖GPU
3. **可解释AI** — 从公理到行为全链路可审计
4. **神经形态计算** — 可与Loihi 2/BrainChip等芯片配合
5. **认知科学研究** — 可计算的认知理论实现

## 许可证

Apache 2.0
