🧬 长期记忆 Store ★

class BaseStore(ABC):
    """持久化 KV 存储基类。

    Stores 实现跨 thread 共享的持久记忆，
    可按 user_id / assistant_id 等任意 namespace 分组。

    ★ 部分实现支持语义搜索（通过 index 配置开启）。
    语义搜索默认禁用，需创建时提供 index 配置。
    TTL（过期）也默认禁用，子类需显式 supports_ttl = True。
    """

    supports_ttl: bool = False
    ttl_config: TTLConfig | None = None

    # 核心抽象方法：批量执行操作（get/put/search/delete 都是封装）
    @abstractmethod
    def batch(self, ops: Iterable[Op]) -> list[Result]: ...
    @abstractmethod
    async def abatch(self, ops: Iterable[Op]) -> list[Result]: ...

    # ====== 便捷封装方法 ======
    def get(self, namespace: tuple[str, ...], key: str) -> Item | None:
        """按 namespace + key 精确取。"""

    def search(self, namespace_prefix, *, query=None, filter=None, limit=10):
        """★ 搜索：支持语义搜索（query）和元数据过滤（filter）。"""

    def put(self, namespace, key, value, *, index=None) -> None:
        """存。index 可指定对哪些字段做 embedding。"""

    def delete(self, namespace, key) -> None: ...
    def list_namespaces(self, *, prefix=None) -> list: ...

# namespace 是 tuple，分层隔离不同用户/场景
store.put(
    namespace=("users", "alice", "preferences"),  # ← 三层命名空间
    key="diet",
    value={"allergies": ["peanut"], "likes": ["italian"]},
)
store.put(
    namespace=("users", "bob", "preferences"),    # bob 的，和 alice 隔离
    key="diet",
    value={"allergies": [], "likes": ["japanese"]},
)

# search 时用 namespace_prefix 匹配前缀
store.search(("users", "alice"), query="饮食偏好")  # 只搜 alice 的

class IndexConfig(TypedDict):
    dims: int                    # :577 embedding 维度（如 1536）
    embed: ...                   # :590 embedding 函数
                                 #   - Embeddings 实例
                                 #   - 同步/异步函数
                                 #   - provider 字符串如 "openai:text-embedding-3-small"
    fields: list[str]            # :662 对哪些 JSON path 做 embedding
                                 #   默认 ["$"] 整体，可指定 ["$.content"] 只索引某字段

from langgraph.store.memory import InMemoryStore

# ★ 开启语义搜索只需传 index 配置
store = InMemoryStore(
    index={
        "dims": 1536,                                    # embedding 维度
        "embed": "openai:text-embedding-3-small",        # 用 OpenAI embedding
        "fields": ["$"],                                 # 对整个 value 做 embedding
    }
)

# 存入记忆（自动 embedding）
store.put(("users", "alice", "memories"), "m1",
          {"text": "我对花生过敏，喜欢意大利菜"})

# ★ 语义搜索：不靠精确匹配，靠语义相似
results = store.search(("users", "alice"), query="Alice 的饮食限制是什么？")
# 即使 query 没有"花生""过敏"字样，语义相近也能召回！
# 这就是长期记忆"越用越懂你"的基础

# pip install langgraph langchain-openai
# export OPENAI_API_KEY="sk-..."
from langgraph.store.memory import InMemoryStore
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

model = ChatOpenAI(model="gpt-4o-mini")

# ★ 长期记忆 Store（带语义搜索）
store = InMemoryStore(index={"dims": 1536, "embed": "openai:text-embedding-3-small"})

# 工具①：记住用户信息（写入长期记忆）
@tool
def remember(fact: str) -> str:
    """记住关于用户的重要信息。当用户提到偏好/个人信息时使用。"""
    # 用 user_id 作 namespace 隔离（实际从 config 取）
    store.put(("user_memories",), f"fact_{hash(fact) % 10000}",
              {"text": fact})
    return f"已记住：{fact}"

# 工具②：回忆用户信息（语义搜索长期记忆）
@tool
def recall(query: str) -> str:
    """回忆关于用户的信息。当需要用户的历史偏好/信息时使用。"""
    results = store.search(("user_memories",), query=query, limit=3)
    if not results:
        return "没有相关记忆"
    return "\n".join(f"- {r.value['text']}" for r in results)

# ★ Agent 同时配 checkpointer（短期）和 store（长期）
agent = create_react_agent(
    model, tools=[remember, recall],
    checkpointer=InMemorySaver(),   # 短期：对话历史
    store=store,                     # 长期：跨会话记忆
    prompt="你是私人助手。用户提到偏好时用 remember 记住；需要时用 recall 回忆。",
)

config = {"configurable": {"thread_id": "day1"}}

# ========== 会话1（周一）==========
print("=== 会话1 ===")
agent.invoke({"messages": [("user", "我对花生过敏，最喜欢意大利菜")]}, config)
agent.invoke({"messages": [("user", "记住我喜欢周末做饭")]}, config)

# ========== 会话2（周三，不同 thread！）==========
config2 = {"configurable": {"thread_id": "day3"}}
print("\n=== 会话2（跨会话，新thread）===")
result = agent.invoke({"messages": [("user", "推荐我今晚吃什么")]}, config2)
print(result["messages"][-1].content)
# ★ Agent 会用 recall 工具语义搜索到"花生过敏+意大利菜"，
#   即使这是另一个会话（thread 不同）！长期记忆跨会话生效。

# ========== 会话3（周五）==========
config3 = {"configurable": {"thread_id": "day5"}}
print("\n=== 会话3 ===")
result = agent.invoke({"messages": [("user", "周末有什么计划建议")]}, config3)
# recall 到"喜欢周末做饭"，给出相关建议

# 不依赖 Agent 主动 remember，而是每轮对话后自动抽取
def extract_and_store_memories(messages, user_id):
    """用 LLM 从对话中抽取'值得长期记住的事实'。"""
    extraction = model.invoke([
        SystemMessage(content=(
            "从对话中抽取值得记住的用户事实（偏好/个人信息/重要决定）。"
            "如果没有值得记的，返回空。JSON 数组格式。"
        )),
        *messages,
    ])
    facts = parse_json(extraction.content)  # [{"text": "对花生过敏"}, ...]
    for fact in facts:
        store.put(("user_memories", user_id), f"fact_{uuid4()}",
                  {"text": fact["text"]})

# 在图的末尾节点调用，自动沉淀记忆
# 优点：Agent 不用关心记忆，专注任务；缺点：多一次 LLM 调用

from langgraph.store.postgres import PostgresStore
import psycopg

# 生产级：PostgreSQL + pgvector
conn = psycopg.connect("postgresql://user:pass@localhost/langgraph")
store = PostgresStore(conn=conn, index={"dims": 1536, "embed": "openai:..."})
store.setup()   # 自动建表 + pgvector 索引

# 用法和 InMemoryStore 完全一样——这就是抽象的价值
agent = create_react_agent(model, tools=[...], store=store, ...)
# 进程重启、多实例部署，记忆都在 Postgres 里持久保留

# Memory
用户记忆存在 .github/instructions/memory.instruction.md
需要时自行读写更新该文件（带 applyTo: '**' front matter）

# OpenCode 的"长期记忆"本质：
# - 是 Agent 主动维护的 markdown 文件
# - instruction.resolve (instruction.ts:46) 自动注入到 prompt
# - 用户可直接打开文件查看/编辑记忆（完全透明）
# - 没有 embedding 语义搜索，靠 Agent 自己 grep/glob