NeuroAssembly Engine

一种基于联想记忆和汇编指令集的认知引擎：将大语言模型限定为 NL-KAL 编解码器，知识存储与核心推理由符号化系统完成。

---

项目概述

NeuroAssembly Engine 是一个本地优先的认知引擎原型，提出了一个区别于主流 RAG / Agent 范式的新架构思路：

将 LLM 的角色严格限定为"自然语言与汇编语言之间的编解码器"，知识存储和核心推理完全由符号化系统承担。

用户输入 ──→ [LLM 编码] ──→ KAL 汇编程序 ──→ [符号引擎执行] ──→ 结构化结果
   ↑                                                              │
   └──────────── [LLM 解码] ←─────────────────────────────────────┘

在这个架构下：

• LLM 仅做格式转换（NL → KAL → NL），不承载知识，不参与决策
• 知识存储在 SQLite 联想图谱中，以节点+关联的形式组织
• 推理由 KAL 汇编解释器执行，每一步都可序列化、可回放、可审计
• 极小模型（0.5B）即可驱动，核心链路离线可用

---

核心创新点

1. 知识与推理分离的架构范式

当前主流方案（RAG、Agent）中，LLM 同时承担"理解"和"推理"双重角色，知识直接编码在模型参数或 prompt 中。NeuroAssembly 将二者严格分离：

维度	传统 LLM	RAG	NeuroAssembly
知识存储	模型参数	向量数据库	联想图谱（SQLite）
推理主体	LLM	LLM	KAL 符号引擎
LLM 角色	全能	增强生成	仅编解码
可解释性	低	中	指令级可追溯
最小模型	7B+	7B+	0.5B

2. KAL — 知识汇编语言（Knowledge Assembly Language）

设计了一套 19 条指令的汇编语言，用于表示和执行知识操作：

类别	指令	说明
定义	.DEF .UNDEF	创建/删除记忆节点
关系	.LINK .UNLINK	建立/断开节点关联
读写	.FETCH .STORE .LOAD	读取/写入/加载记忆
逻辑	.CMP .AND .OR .NOT	条件判断与逻辑运算
控制	.JMP .JE .JNE .JL .JGE .CALL .RET	跳转与子程序调用
扫描	.SCAN	模糊检索记忆
系统	.START .END .HALT .NOP .TRACE	程序控制

KAL 程序具有完整的寄存器模型、标志位、调用栈和标签跳转，是一个可执行的汇编语言——推理过程本身就是结构化的、可序列化的执行轨迹。

3. 联想图谱 + 扩散激活检索

借鉴 Collins & Loftus (1975) 的扩散激活理论，记忆存储为图结构，检索沿关联边进行多层级扩散：

精确匹配 → 别名映射 → 关联扩散（BFS，按权重排序）→ 模糊匹配

节点同时具备 ACT-R 风格激活值：

activation = ln(access_count × exp(-d × elapsed/86400) + 1)

结合置信度评分、版本归档、Pin 固定和自动遗忘机制，构成完整的记忆生命周期管理。

4. 假设-验证推理引擎

推理不依赖单次 LLM 调用，而是：

1. 生成多个候选假设（如 direct / conservative / missing_memory）
2. 每个假设独立检索证据、执行 KAL 程序
3. 使用显式评分公式量化评估：

score = coverage × 0.5 + (1 - error) × 0.3 + intent_bonus

4. 选择最优结果输出，附带完整元数据（迭代次数、停止原因、所有候选评分）

5. 指令级推理轨迹回放

每次推理的每一步都记录为结构化事件（input → hypothesis → fetch → execute → stop → output），支持从 JSONL 持久化存储中反向快速检索和完整回放。

6. 双后端自动降级

通过 ModelAdapter Protocol 接口，支持 LLM 后端（LM Studio）和纯规则后端无缝切换：

• LLM 模式：调用本地模型编解码 KAL，自动回退到规则模式
• 规则模式：内置 5 领域关键词分类 + 候选生成，无需任何外部模型

---

研究价值

学术研究方向

方向	贡献
可解释 AI（XAI）	KAL 汇编指令级的推理过程完全符号化，每个步骤可人类阅读和验证，比注意力可视化更彻底
神经-符号融合	将 LLM 严格限制为编解码器的干净分离方案，区别于传统 pipeline 式融合
认知架构工程化	将扩散激活、假设-验证循环、ACT-R 衰减、遗忘曲线整合为可运行系统
AI 推理可复现性	KAL 程序 + 完整轨迹 = 可复现的推理过程，为 AI 安全/审计/合规提供基础设施
边缘 AI 部署	0.5B 模型 + SQLite 本地存储，总内存 < 2GB，适合隐私敏感和离线场景

与现有工作的区别

• vs PBAsm（已停产）：最接近的先驱，但使用自然语言编译执行，KAL 具有精确的寄存器+控制流模型
• vs Mem0：向量+图谱混合面向云端，NeuroAssembly 本地优先，且具备符号推理能力
• vs LangSmith/LangFuse：面向 LLM 调用的可观测性工具，NeuroAssembly 记录的是指令级推理状态
• vs CoT/ToT：由 LLM 内部完成不可审计的推理，NeuroAssembly 的推理过程完全外部化、可量化

单项来看，各个组件都有先驱，但自定义汇编指令集 + 联想图谱存储 + 假设-验证推理 + 指令级轨迹回放的完整组合在现有文献和开源项目中没有直接对标。

---

快速开始

环境要求

• Python >= 3.11
• LM Studio（用于加载 qwen3-0.6b 等小模型，可选）
• Windows / macOS / Linux

安装

cd NeuroAssembly
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS/Linux
pip install -e .[dev]

配置

cp .env.example .env

# LM Studio 配置（默认端口 1234）
LLM_BASE_URL=http://localhost:1234/v1
LLM_API_KEY=lm-studio
LLM_MODEL=qwen3-0.6b

# 模型后端：llm = LM Studio / rule = 纯规则（不需要模型）
MODEL_BACKEND=llm

# 推理参数
MAX_ITER=4
FETCH_TOP_K=5
TURN_TIMEOUT_MS=5000
SESSION_TTL_SECONDS=1800

启动

方式一：LM Studio 本地模型（推荐）

1. 下载安装 LM Studio
2. 搜索下载 qwen3-0.6b 模型（约 500MB），加载后启动 Local Server（端口 1234）
3. 启动引擎：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. 打开浏览器访问 http://localhost:8000

方式二：纯规则模式（无需模型）

$env:MODEL_BACKEND="rule"    # PowerShell
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

加载种子数据

python scripts/seed_memory.py

写入 21 个记忆节点、46 个别名、31 条关联，覆盖个人信息、日程、健康、知识库、兴趣等类别。

---

Web 可视化界面

浏览器访问 **http://localhost:8000**，包含三个核心视图：

• 左侧 — 记忆节点列表：显示所有记忆节点，支持搜索过滤
• 中间 — 对话区域：输入问题，查看回答及 KAL 程序、推理元数据
• 右侧 — 推理轨迹：每次回答的 KAL 执行过程实时展示
• 右侧 — 记忆图谱：节点网络的力导向可视化

---

API 接口

问答推理

curl -X POST http://localhost:8000/v1/query \
  -H "Content-Type: application/json" \
  -d '{"text": "我喜欢喝什么饮品？", "session_id": "my-session"}'

{
  "answer": "根据记忆，您喜欢美式咖啡，无糖。",
  "turn_id": "550e8400-...",
  "kal": ".START\n.FETCH USER_PROFILE, R1\n.STORE R1, RESULT.TEXT\n.RET\n.END",
  "meta": {
    "winner_score": 0.85,
    "iter_count": 2,
    "elapsed_ms": 1234,
    "stop_reason": "converged"
  }
}

轨迹回放

curl http://localhost:8000/v1/trace/{turn_id}

记忆管理

# 写入记忆
curl -X POST http://localhost:8000/v1/memory \
  -H "Content-Type: application/json" \
  -d '{"key": "MY_NOTES", "payload": {"topic": "项目进展"}, "confidence": 0.9, "source": "manual", "aliases": ["我的笔记"]}'

# 查询 / 搜索 / 关联 / 固定 / 删除 / 恢复
curl http://localhost:8000/v1/memory/MY_NOTES
curl -X POST "http://localhost:8000/v1/memory/scan?q=项目&top_k=10"
curl http://localhost:8000/v1/memory/MY_NOTES/related?depth=1&top_k=5
curl -X POST http://localhost:8000/v1/memory/MY_NOTES/pin
curl -X DELETE http://localhost:8000/v1/memory/MY_NOTES
curl -X POST http://localhost:8000/v1/memory/MY_NOTES/recover

# ACT-R 激活值 / 遗忘清理
curl -X POST http://localhost:8000/v1/memory/MY_NOTES/refresh
curl -X POST "http://localhost:8000/v1/memory/forgetting?confidence_threshold=0.3&inactive_days=30"

# 图谱数据
curl http://localhost:8000/v1/memory/graph?top_k=50

完整端点一览

端点	方法	说明
/	GET	Web 可视化界面
/health	GET	健康检查
/v1/query	POST	问答推理
/v1/trace/{turn_id}	GET	轨迹回放
/v1/session/{session_id}	GET/DELETE	会话管理
/v1/memory	POST	写入/更新记忆
/v1/memory/scan	POST	模糊搜索
/v1/memory/forgetting	POST	遗忘清理
/v1/memory/graph	GET	图谱数据
/v1/memory/{key}	GET/DELETE	查询/删除记忆
/v1/memory/{key}/pin	POST	固定记忆
/v1/memory/{key}/unpin	POST	取消固定
/v1/memory/{key}/recover	POST	恢复记忆
/v1/memory/{key}/related	GET	关联扩散检索
/v1/memory/{key}/refresh	POST	激活值查询

Swagger UI: http://localhost:8000/docs

---

项目结构

NeuroAssembly/
├── app/
│   ├── adapters/                # 模型适配器
│   │   ├── llm_model_adapter.py    # LM Studio OpenAI 兼容适配器
│   │   └── rule_model_adapter.py   # 纯规则适配器（无需模型）
│   ├── api/
│   │   └── routes.py            # FastAPI 路由定义
│   ├── cognition/
│   │   └── reasoning_engine.py  # 假设-验证推理引擎
│   ├── core/
│   │   └── config.py            # 配置管理
│   ├── kal/
│   │   └── engine.py            # KAL 汇编解释器（19 条指令）
│   ├── memory/
│   │   └── store.py             # 联想记忆存储（SQLite + ACT-R）
│   ├── observability/
│   │   └── trace_recorder.py    # 推理轨迹记录器（JSONL）
│   ├── schemas/
│   │   └── models.py            # Pydantic 数据模型
│   ├── session/
│   │   └── manager.py           # 多轮会话管理
│   ├── static/
│   │   └── index.html           # Web 可视化前端
│   └── main.py                  # FastAPI 应用入口
├── scripts/
│   ├── seed_memory.py           # 种子数据生成
│   ├── run_eval.py              # 评测脚本
│   └── benchmark.py             # 性能基准
├── tests/                       # 55 个测试用例
├── data/samples/                # 评测数据集
├── .env.example                 # 配置模板
├── design.md                    # 设计文档
├── pyproject.toml               # 项目配置
└── README.md

---

测试

# 运行全部测试（55 个）
pytest -q

# 运行指定模块
pytest tests/test_kal_engine.py -v
pytest tests/test_memory_store.py -v
pytest tests/test_api.py -v
pytest tests/test_reasoning_engine.py -v
pytest tests/test_session.py -v

---

配置参考

环境变量	默认值	说明
MODEL_BACKEND	llm	rule 纯规则 / llm LM Studio
LLM_BASE_URL	http://localhost:1234/v1	LM Studio API 地址
LLM_MODEL	qwen3-0.6b	LM Studio 中加载的模型名
LLM_API_KEY	lm-studio	API Key
LLM_TIMEOUT_S	30	LLM 请求超时秒数
MAX_ITER	4	推理引擎最大迭代轮次
FETCH_TOP_K	5	单次检索最大返回节点数
TURN_TIMEOUT_MS	5000	单轮推理超时毫秒数
MEMORY_DB_PATH	memory.db	SQLite 数据库文件路径
TRACE_PATH	trace_logs	轨迹日志存储目录
SESSION_TTL_SECONDS	1800	会话过期时间（秒）
CORS_ORIGINS	*	允许的跨域来源

---

常见问题

Q: LM Studio 连接失败？ 系统自动回退到规则模式，服务不中断。检查 LM Studio Local Server 是否启动、端口是否为 1234。

Q: 如何换模型？ 在 LM Studio 加载新模型，修改 .env 中 LLM_MODEL，重启服务。

Q: 数据存在哪？ 记忆：memory.db（SQLite），轨迹：trace_logs/（JSONL），会话：内存（30 分钟过期）。

Q: 如何查看 API 文档？ 启动后访问 http://localhost:8000/docs

---

License

MIT