new-agent-memory 0.1.0

Explainable human-like memory layer for AI agents.

new-agent-memory

Explainable human-like memory layer for AI agents.

new-agent-memory 是一个探索类人长期记忆的 Python 原型。它不只是把所有内容塞进向量库，而是把记忆分成核心层和伪遗忘层，让记忆可以被强化、衰减、降级，并在合适的线索出现时重新唤醒。

AI 应该像人一样慢慢积累、越用越懂你，而不是每次会话都从零开始。

Why This Exists

大多数 Agent Memory 系统重点解决“怎么存”和“怎么搜”。这个项目更关注另一个问题：

• 什么记忆应该常驻核心上下文？
• 什么记忆应该暂时沉到伪遗忘层？
• 用户重新给出线索时，系统怎样把它唤醒？
• 用户不喜欢主动提旧事时，系统怎样逐渐收敛？

核心定位：可解释的记忆衰减、线索唤醒与目标驱动注意力调度。

Features

• 核心记忆层：高权重记忆常驻，检索路径直接、可解释。
• 伪遗忘层：低权重记忆不主动占用核心空间，但可被地点、人物、主题等锚点唤醒。
• 自适应权重：结合时间衰减、访问频率、近因效应、情绪强度、关联密度和重要性。
• 人格适应层：通过用户反馈学习是否应该主动提及旧记忆。
• GoalStack：维护当前目标、约束、证据和未闭环事项，让系统知道“现在正在干什么”。
• 程序记忆：保存可复用的做事方式，例如测试、提交、发布、排查问题的流程。
• 注意力工作区：按目标相关度、查询相关度、重要性、近因、频率和干扰惩罚选择上下文。
• 审计轨迹：每次进入工作区的记忆和程序都会带有分数拆解，便于解释为什么被选中。
• CognitiveAgent：提供 Observe -> Focus -> Act -> Evaluate -> Remember -> Consolidate 的最小数字身体闭环。
• LLMPlanner：把 OpenAI、Hermes 或本地模型接成 Agent 的决策核心，让模型根据目标、记忆和工具返回下一步行动。
• CognitiveState：维护自我模型、世界信念、驱动力、行动预期和反思记录，让 Agent 知道“我是谁、我能做什么、我不确定什么”。
• 经验层：把行动、结果、奖励、教训和下一次策略记录为经验 episode，并可巩固成记忆/程序。
• 可持久化：核心层、伪遗忘层、人格偏好和注意力状态可以保存到 JSON。
• 轻量高性能检索：核心层内置倒排索引、短期权重缓存、候选集限制和早期退出。

Install

git clone https://github.com/ZhaoDongdong0109/new-agent-memory.git
cd new-agent-memory
python -m pip install -e ".[dev]"

项目当前没有强制运行时依赖；dev extra 只安装测试工具。

OpenAI-Compatible Quickstart

配置 .env：

OPENAI_API_KEY=your-key-or-local-placeholder
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini

如果你用 Hermes、LM Studio、vLLM、Ollama 网关或其他 OpenAI-compatible 服务，把 OPENAI_BASE_URL 改成对应的 /v1 地址即可，例如：

OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=hermes-3

单轮对话：

new-agent-memory ask "你现在是谁？用一句话说明你能做什么。"

交互式会话：

new-agent-memory chat --goal "帮助用户把记忆系统进化成可下载可运行的智能体"

Python 中直接创建：

from new_agent_memory import HumanLikeMemorySystem

memory = HumanLikeMemorySystem()
agent = memory.create_openai_agent()
episode = agent.run_turn("你现在能做什么？")
print(episode.result.output)
memory.save()

Cognitive Runtime

Use the multi-step runtime when a task needs more than one internal action:

new-agent-memory ask --runtime --max-steps 4 \
  "Answer first, then call introspect, then finish with two next questions."

Python API:

from new_agent_memory import HumanLikeMemorySystem

memory = HumanLikeMemorySystem()
runtime = memory.create_openai_runtime(max_steps=4)
run = runtime.run("Answer first, then call introspect, then finish.")

print(run.result.output)
print([step.action.name for step in run.steps])

CognitiveRuntime adds a small executive loop above CognitiveAgent:

Observe -> Goal -> Focus -> Plan -> Act -> Reflect -> Continue/Finish

It registers a finish control tool, records each step as an ExperienceEpisode, guards against finishing before required tools actually run, and keeps runtime trace text separate from the user's original intent.

支持的环境变量：

OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
OPENAI_TEMPERATURE
OPENAI_MAX_TOKENS
OPENAI_TIMEOUT
OPENAI_USE_ENV_PROXY

也可以使用 OPENAI_COMPATIBLE_* 前缀，例如 OPENAI_COMPATIBLE_BASE_URL。

Quickstart

from new_agent_memory import HumanLikeMemorySystem, MemoryType

memory = HumanLikeMemorySystem()

memory.add_memory(
    content="今天中午和客户在北京餐厅吃了烤鸭，聊了项目预算。",
    memory_type=MemoryType.INTERACTION,
    time_absolute="2026-04-29",
    time_context="中午",
    location="北京",
    persons=["客户"],
    topics=["food", "business", "project"],
    keywords=["烤鸭", "预算"],
    emotion_valence=0.3,
    emotion_intensity=0.6,
    importance=0.8,
)

result = memory.retrieve("中午在北京吃了什么")
print(result.summary())
print(result.assembled_content)

输出类似：

[approved] path=core chunks=1 confidence=0.54 | 今天中午和客户在北京餐厅吃了烤鸭，聊了项目预算。
今天中午和客户在北京餐厅吃了烤鸭，聊了项目预算。

Attention Workspace

如果普通检索回答的是“记得什么”，注意力工作区回答的是“现在该想什么”。

from new_agent_memory import HumanLikeMemorySystem, MemoryType

memory = HumanLikeMemorySystem()

memory.start_goal(
    "修复测试失败并安全推送 PR",
    constraints=["先跑 pytest", "检查 git diff", "不要直接改 main"],
    open_loops=["PR 还没创建"],
)

memory.add_memory(
    content="上次 maintain() 失败是因为核心层缺少 decay_all_unused()。",
    memory_type=MemoryType.FACT,
    topics=["pytest", "maintenance", "bugfix"],
    importance=0.75,
)

memory.add_procedure(
    title="Safe PR workflow",
    steps=["run pytest", "run examples", "check git diff", "commit", "push branch"],
    triggers=["pytest", "tests", "PR", "push"],
    importance=0.85,
    confidence=0.8,
)

workspace = memory.focus("pytest 失败后怎么继续")
print(workspace.to_prompt_context())

输出会包含当前目标、应该带入上下文的程序记忆、以及真正相关的记忆。无关但重要的偏好会被审计记录下来，但不会自动进入工作区。

Cognitive Agent Loop

CognitiveAgent 是这个项目迈向通用 Agent 的第一具“数字身体”。它不假装已经拥有物理感受，但它能在一个可观察、可行动、有反馈、可累积后果的环境里运行。

from new_agent_memory import ActionResult, AgentAction, HumanLikeMemorySystem

memory = HumanLikeMemorySystem()
memory.start_goal(
    "帮助用户把项目推进到可运行的 Agent 原型",
    constraints=["先观察", "再行动", "最后复盘"],
)

agent = memory.create_agent(name="hermes-seed")

def planner(observation, workspace, tools):
    return AgentAction(
        name="inspect",
        arguments={
            "input": observation.content,
            "focus": workspace.to_prompt_context(),
        },
        rationale="用户要求检查，因此调用 inspect 工具。",
    )

def inspect_tool(arguments):
    return ActionResult(
        success=True,
        output="检查完成。当前注意力上下文长度：" + str(len(arguments.get("focus", ""))),
        cost=0.05,
    )

agent.planner = planner
agent.add_tool("inspect", "Inspect the current focus workspace.", inspect_tool)

episode = agent.run_turn("请检查当前 Agent 闭环是否能工作")
print(episode.lesson)
print(episode.next_policy)

每一轮会产生一个 ExperienceEpisode：

Observation -> FocusWorkspace -> AgentAction -> ActionResult -> reward
  -> lesson -> next_policy -> memory/procedure consolidation

这让系统开始记录“我做了什么、结果如何、下次该怎么做”，而不只是保存对话文本。

LLM Planner

new-agent-memory 本身是认知层，不是大模型。要让 Agent 做复杂推理，需要给 CognitiveAgent 接一个 LLM planner。

最小形式是传入一个 prompt -> text 的函数：

from new_agent_memory import CognitiveAgent, HumanLikeMemorySystem, LLMPlanner

memory = HumanLikeMemorySystem()
agent = CognitiveAgent(memory_system=memory)

def call_hermes_or_local_model(prompt: str) -> str:
    # 返回必须包含一个 JSON action
    return """
{
  "name": "respond",
  "arguments": {"message": "我会根据当前目标和记忆回答。"},
  "rationale": "No external tool is needed."
}
"""

agent.planner = LLMPlanner(call_hermes_or_local_model)
episode = agent.run_turn("下一步怎么做？")

如果使用 OpenAI-compatible /v1/chat/completions 服务，可以直接从环境变量创建：

from new_agent_memory import HumanLikeMemorySystem

memory = HumanLikeMemorySystem()
agent = memory.create_openai_agent()
episode = agent.run_turn("请读取当前记忆和认知状态，然后回复我。")

也可以手动构造：

from new_agent_memory import LLMPlanner, OpenAICompatibleConfig

config = OpenAICompatibleConfig(
    api_key="local-or-real-key",
    base_url="http://localhost:1234/v1",
    model="hermes-3",
)
planner = LLMPlanner.from_openai_compatible(config)

如果使用 OpenAI Responses 风格客户端，可以这样包一层：

from openai import OpenAI
from new_agent_memory import LLMPlanner

client = OpenAI()
planner = LLMPlanner.from_openai_responses(
    client=client,
    model="gpt-4.1-mini",
)

模型需要返回的 JSON：

{
  "name": "tool_name",
  "arguments": {},
  "rationale": "short reason"
}

name 必须是当前 Agent 已注册工具之一，例如 respond、remember 或你自己用 agent.add_tool(...) 添加的工具。

Reflective Cognition

CognitiveState 是这次新增的“内在状态”层。它不负责替代 LLM 推理，而是给推理核心提供一个稳定、可保存、可审计的自我/世界模型：

• Self model：身份、使命、能力边界和限制。
• Drive state：连贯性、胜任感、好奇心、有用性、安全性等 homeostatic drives。
• World beliefs：从观察、反馈和行动结果中形成带置信度的信念。
• Action priors：根据工具历史结果预测某个行动的成功率和成本。
• Reflection notes：每次行动后记录 outcome、insight、uncertainty 和 next question。

完整 Agent loop 现在会变成：

Observe -> update world model -> Focus -> attach CognitiveState
  -> Predict -> Act -> Evaluate -> Reflect -> Remember -> Consolidate

默认工具里新增了 introspect：

from new_agent_memory import CognitiveAgent, HumanLikeMemorySystem

memory = HumanLikeMemorySystem()
agent = CognitiveAgent(memory_system=memory, auto_consolidate=False)

episode = agent.run_turn("please introspect current state")
print(episode.result.output)

这让 Agent 可以主动读取自己的驱动力、开放问题、工具先验和最近反思。focus() 也会把 CognitiveState 注入 FocusWorkspace.to_prompt_context()，所以 LLMPlanner 会自然看到这层上下文。

Examples

python examples/simple_memory.py
python examples/forgotten_recall.py
python examples/persona_adaptation.py
python examples/attention_workspace.py
python examples/cognitive_agent.py
python examples/llm_planner.py
python examples/openai_compatible_agent.py
python examples/reflective_cognition.py

示例覆盖：

• 添加记忆并检索
• 伪遗忘层被线索唤醒
• 用户反馈改变主动回忆偏好
• 目标驱动的注意力工作区
• 数字身体闭环和经验巩固
• LLM 决策器如何选择工具行动
• OpenAI-compatible API 如何接入 Agent
• 自我/世界模型、反思记录和 introspect 工具

Architecture

用户输入
  |
  v
目标栈 + 观察输入
  |
  v
注意力门控 --选择--> 工作区上下文
  |
  +--> 程序记忆
  +--> 核心记忆层
  +--> 必要时唤醒伪遗忘层
  |
  v
Agent 决策 -> 工具行动 -> 结果评价
  |
  v
经验记录与巩固：记忆 / 程序 / 偏好 / 目标

模块结构：

new-agent-memory/
├── main.py                    # 统一 API：HumanLikeMemorySystem
├── memory_chunk.py            # 记忆碎片数据结构
├── memory_layer_core.py       # 核心记忆层、索引、缓存、权重计算
├── forgotten_layer.py         # 伪遗忘层与线索唤醒
├── retrieval.py               # 查询解析、检索、组装、审阅
├── core/
│   ├── agent_system.py        # CognitiveAgent、工具、经验层与行动闭环
│   ├── llm_planner.py         # 模型无关 LLMPlanner 和 OpenAI Responses 包装
│   ├── cognitive_state.py     # 自我模型、世界信念、驱动力、行动预期与反思
│   ├── attention_system.py    # GoalStack、程序记忆、注意力评分与工作区
│   ├── weight_system.py       # 自适应权重系统实验
│   ├── emotion_engine.py      # 情绪推断与情绪系数采样
│   └── persona_layer.py       # 行为反馈与人格适应
├── examples/                  # 可运行示例
└── tests/                     # 行为测试

Memory Model

权重由多种信号共同决定：

effective_weight =
  time_decay
  + access_frequency
  + recency
  + emotion_boost
  + association_density
  + importance
  + connection_value

当核心记忆权重低于阈值时，它会降级到伪遗忘层。伪遗忘层不会主动参与普通检索，但当查询里出现足够强的锚点，例如地点、人物、主题，系统可以重新唤醒这段记忆。

Attention Model

注意力工作区使用可解释分数，而不是黑盒排序：

attention_score =
  goal_relevance
  + query_relevance
  + user_importance
  + recency
  + frequency
  + emotional_salience
  + uncertainty_need
  + novelty
  - distraction_penalty
  - staleness_penalty

这让系统可以做到：

• 当前目标相关的记忆优先进入上下文
• 程序记忆在触发词出现时被带入，例如 pytest、release、PR
• 重要但无关的记忆会被干扰惩罚挡住
• 每次选择都有 audit，可解释分数来源

Performance Notes

核心层已合入实验中的主要优化：

• 多级倒排索引：时间、主题、地点、人物
• 权重缓存：避免重复计算同一批候选
• 候选集限制：默认最多扫描 200 条候选
• 早期退出：找到足够候选后停止扫描

历史实验报告见 experiments/OPTIMIZATION_REPORT.md。

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m compileall .

当前测试覆盖：

• 核心层添加与检索
• maintain() 安全运行与弱记忆降级
• 伪遗忘层线索唤醒
• 保存与加载
• 人格正反馈提升兴趣度
• 目标驱动注意力门控
• 注意力状态持久化
• CognitiveAgent 行动闭环
• 经验 episode 巩固为长期记忆和程序记忆
• LLMPlanner JSON 行动解析、fallback 和工具选择
• CognitiveState 自我/世界模型、行动预期、反思和持久化

Roadmap

• 标准 Python 包入口
• 核心层索引、缓存和早期退出
• 基础测试与 GitHub Actions
• 可运行 examples
• GoalStack、程序记忆和注意力工作区
• CognitiveAgent 数字身体闭环
• 模型无关 LLMPlanner
• CognitiveState 自我/世界模型与反思闭环
• Hermes / OpenAI-compatible Agent adapter
• CLI：memory add/search/stats
• 自动记忆提取器 MemoryExtractor
• 经验复盘与矛盾处理 ConsolidationEngine
• SQLite 持久化后端
• 更强的自然语言线索解析
• LLM 驱动的碎片组装与审阅
• 向量检索 / BM25 / 图关联的混合检索
• MCP 或 LangGraph 集成示例

Positioning

这个项目不是 Mem0、Zep、LangChain Memory 的替代品，而是一个更小、更可解释的类人记忆与注意力机制实验。它适合用于：

• 学习长期记忆系统怎么分层、衰减、唤醒
• 研究 Agent 如何在有限上下文里决定“现在该想什么”
• 给个人 Agent 增加可解释的长期记忆原型
• 研究“遗忘机制”本身，而不是只研究语义检索

License

AGPL-3.0-or-later. See LICENSE.