最近在尝试为 AI 智能体（Agent）构建一个能够“记住”代码上下文、理解代码结构的长期记忆系统时，发现了一个非常有意思的项目：Lybrary。它不是一个简单的代码片段管理器，而是一个持久化、具备抽象语法树（AST）感知能力的代码记忆库，专门为 AI Agent 设计，并可以通过MCP（Model Context Protocol）服务器的方式轻松集成。

如果你正在开发基于大模型的代码生成、代码分析或自动化编程助手，常常会面临 Agent 的“记忆”是短暂的、缺乏对代码结构深层理解的问题。Lybrary 正是为了解决这个痛点而生。本文将带你从零开始，深入理解 Lybrary 的核心概念，并手把手教你如何通过pip install安装、配置 MCP 服务器，最终将其集成到你的 AI Agent 工作流中。

1. 背景与核心概念：为什么需要 AST 感知的代码记忆？

在深入实操之前，我们有必要先厘清几个关键概念，理解 Lybrary 要解决的根本问题。

1.1 AI Agent 的“记忆失忆”问题

当前的 AI Agent，尤其是基于大语言模型（LLM）的代码助手，在处理复杂、多步骤的编程任务时存在一个显著短板：上下文窗口有限。这意味着：

1. 会话隔离：每次对话或请求都是独立的，Agent 无法记住之前会话中分析、修改或生成的代码。
2. 结构遗忘：即使在同一会话中，当代码量增大时，Agent 也可能“忘记”早先定义的函数、类或它们之间的关系。
3. 缺乏语义理解：Agent 通常将代码视为纯文本，无法像程序员一样理解代码的语法结构（如这是一个函数定义、那是一个类继承）和语义关系（如这个函数调用了哪些其他函数）。

这导致 Agent 在长期项目协作、代码库维护和重构等场景中力不从心。

1.2 Lybrary 的解决方案：持久化 AST 记忆

Lybrary 提出了一个优雅的解决方案：为 AI Agent 建立一个外部的、持久的、基于 AST 的代码记忆库。

• 持久化（Persistent）：记忆被存储在本地或远程数据库中，跨越不同的 Agent 会话和生命周期。Agent 可以随时“回忆”起之前处理过的任何代码。
• AST 感知（AST-aware）：Lybrary 不是简单地存储代码字符串。它会解析代码，生成抽象语法树（Abstract Syntax Tree）。AST 是源代码语法结构的一种树状表示，它剥离了格式细节（如空格、换行），直接暴露了程序的逻辑结构（如函数、参数、循环、条件）。这使得 Lybrary 能够进行基于结构的查询，例如“查找所有调用了函数calculate_score的地方”。
• 为 AI Agents 设计：它通过标准协议（如 MCP）暴露接口，使得任何兼容的 AI Agent 框架（如 Claude Desktop, Cursor, Windsurf 等）都可以方便地查询和更新这个记忆库。

1.3 MCP（Model Context Protocol）服务器：标准化的桥梁

MCP（Model Context Protocol）是由 Anthropic 提出的一种开放协议，旨在为 AI 应用程序（如 Claude Desktop）和外部工具、数据源之间建立一个标准化的通信桥梁。你可以把它想象成 AI 世界的“USB 标准”。

一个MCP 服务器就是一个实现了 MCP 协议的服务，它可以将特定的能力（如读取文件系统、查询数据库、调用 API）暴露给 AI 应用程序。Lybrary 就是以 MCP 服务器的形式运行的，这样，支持 MCP 的 AI Agent 就能直接向 Lybrary 发送诸如“记住这段代码”或“查找与这个模式匹配的代码”的指令。

核心价值串联：Lybrary(AST记忆库) +MCP Server(标准化接口) = 一个能让 AI Agent 拥有长期、结构化代码记忆的强大能力。

2. 环境准备与安装

接下来，我们开始动手搭建环境。整个过程主要分为两步：安装 Lybrary 库本身，以及配置一个 MCP 服务器来承载它。

2.1 系统与 Python 环境

• 操作系统：Lybrary 是 Python 库，因此支持 Windows、macOS 和 Linux。本文演示基于 macOS/Linux 命令行，Windows 用户建议使用 PowerShell 或 WSL。
• Python 版本：建议使用Python 3.8 及以上版本。确保python和pip命令可用。
• 虚拟环境（强烈推荐）：为避免依赖冲突，建议使用虚拟环境。

  # 创建并激活虚拟环境 (venv) python -m venv lybrary-env source lybrary-env/bin/activate # Linux/macOS # 对于 Windows: lybrary-env\Scripts\activate

2.2 安装 Lybrary 核心库

Lybrary 可以通过 pip 直接从 PyPI 安装。这是最核心的一步。

pip install lybrary

安装后验证：

python -c "import lybrary; print(lybrary.__version__)"

如果成功输出版本号（如0.1.0），说明核心库安装成功。

2.3 理解 MCP 服务器安装的两种方式

Lybrary 作为记忆库，需要被 AI Agent 访问。这通过 MCP 服务器实现。安装 MCP 服务器通常有两种场景：

1. 安装 Lybrary 自带的 MCP 服务器工具：Lybrary 项目可能提供了一个现成的 MCP 服务器包装脚本。
2. 为你使用的 AI 应用安装对应的 MCP 服务器：例如，如果你使用 Claude Desktop，你需要安装 Claude 能识别的 Lybrary MCP 服务器包。

根据网络上的常见问题（如“要安装缺失的节点，请先在你的 python 环境中运行 pip install -u --pre comfyui-m”），很多工具的 MCP 服务器是以独立 Python 包的形式存在的。对于 Lybrary，我们假设它提供了一个名为lybrary-mcp或类似的服务器包。请务必查阅 Lybrary 官方文档确认准确的包名。

这里以假设的包名lybrary-mcp-server为例：

pip install lybrary-mcp-server

重要提示：如果遇到网络问题导致pip install缓慢或失败，可以尝试更换 pip 源（即“换源”）。

# 临时使用清华源安装 pip install lybrary-mcp-server -i https://pypi.tuna.tsinghua.edu.cn/simple # 或设置为默认源（Linux/macOS） pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2.4 可能遇到的安装问题及解决思路

3. Lybrary 核心功能与 API 初探

在配置服务器之前，我们先通过 Python 脚本快速了解 Lybrary 的核心 API，理解它是如何工作的。

3.1 创建一个简单的代码记忆库

新建一个 Python 文件demo_lybrary.py。

# demo_lybrary.py import lybrary from pathlib import Path # 1. 初始化一个 Lybrary 实例，指定存储路径（例如，在当前目录下的 .lybrary 文件夹） library = lybrary.Lybrary(storage_path=Path("./.lybrary_db")) # 2. 定义一些要记住的代码片段 code_snippet_1 = """ def calculate_discount(price: float, rate: float) -> float: \"\"\"计算折扣后的价格\"\"\" if rate < 0 or rate > 1: raise ValueError("折扣率必须在0到1之间") return price * (1 - rate) """ code_snippet_2 = """ class ShoppingCart: def __init__(self): self.items = [] self.total = 0.0 def add_item(self, name: str, price: float): self.items.append({"name": name, "price": price}) self._update_total() def _update_total(self): self.total = sum(item["price"] for item in self.items) """ # 3. 将代码片段“记忆”到库中，并附加一些元数据（如文件路径、语言） library.remember( content=code_snippet_1, metadata={"filepath": "utils/price_calculator.py", "language": "python"} ) library.remember( content=code_snippet_2, metadata={"filepath": "models/shopping_cart.py", "language": "python"} ) print("代码片段已存入 Lybrary。")

运行这个脚本：

python demo_lybrary.py

这会在./.lybrary_db目录下创建数据库文件，并将两段代码的AST 表示和原始文本存储起来。

3.2 基于 AST 的智能查询

Lybrary 的强大之处在于基于 AST 的查询。我们修改上面的脚本，添加查询功能。

# ... 紧接上面的代码 ... print("\n--- 查询演示 ---") # 4. 基于文本的关键词搜索（传统方式） print("1. 关键词搜索 'discount':") text_results = library.search(query="discount", search_type="text") for res in text_results: print(f" - 匹配片段来自: {res.metadata.get('filepath')}") # 显示代码预览 print(f" 代码预览: {res.content[:100]}...") # 5. 基于 AST 结构的搜索（Lybrary 核心能力） print("\n2. AST 结构搜索：查找所有函数定义:") ast_results = library.search(query="FunctionDef", search_type="ast_kind") # 查找 AST 节点类型为‘函数定义’的代码 for res in ast_results: print(f" - 在文件 {res.metadata.get('filepath')} 中找到函数定义。") print("\n3. AST 结构搜索：查找所有类定义:") ast_results = library.search(query="ClassDef", search_type="ast_kind") # 查找 AST 节点类型为‘类定义’的代码 for res in ast_results: print(f" - 在文件 {res.metadata.get('filepath')} 中找到类定义。") # 6. 更复杂的 AST 模式查询（示例：查找带有特定参数名的函数） # 注意：实际 API 可能更复杂，这里展示概念。 print("\n4. 概念性查询：查找参数中包含 'rate' 的函数") # 假设有一个 `search_by_ast_pattern` 方法 # pattern = {"node_type": "FunctionDef", "args": {"args": [{"arg": "rate"}]}} # complex_results = library.search_by_ast_pattern(pattern) # ...

关键点解释：

• search_type=“text”：进行传统的全文检索。
• search_type=“ast_kind”：根据 AST 节点类型进行检索。这是 Lybrary 的核心，让你可以找到所有“函数定义”、“类定义”、“循环”、“导入语句”等结构元素。
• 模式匹配：更高级的用法是进行 AST 模式匹配，例如“找到所有调用open()函数的语句”、“找到所有继承了BaseModel的类”。这需要 Lybrary 提供相应的查询接口。

3.3 回忆（Retrieve）与上下文关联

除了搜索，Lybrary 还能根据当前代码上下文，回忆最相关的历史代码。

# 假设我们正在编写一段新代码，其中提到了“购物车”和“总价” current_context = """ # 用户添加商品后，需要更新购物车总价 cart_total = some_cart.total print(f"总计: {cart_total}") """ print("\n--- 上下文回忆演示 ---") print(f"当前上下文:\n{current_context}") relevant_memories = library.retrieve(context=current_context, top_k=2) print(f"\nLybrary 回忆起的相关代码:") for i, memory in enumerate(relevant_memories): print(f"[{i+1}] 来自 {memory.metadata.get('filepath')}:") print(memory.content) print("-" * 40)

这里，library.retrieve方法可能会利用嵌入向量（embedding）计算语义相似度，从记忆库中找出与current_context最相关的代码片段，这对于 AI Agent 续写或修改代码极其有用。

4. 配置 Lybrary 作为 MCP 服务器运行

让 Lybrary 通过 MCP 协议提供服务，AI Agent 才能直接与其对话。这通常需要一个服务器入口脚本。

4.1 创建 MCP 服务器脚本

创建一个名为lybrary_mcp_server.py的文件。注意：以下代码为概念实现，具体需根据lybrary-mcp-server包的实际 API 调整。

# lybrary_mcp_server.py import asyncio from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import lybrary from pathlib import Path import sys # 初始化 Lybrary LIBRARY_DB_PATH = Path("./.lybrary_agent_db") library = lybrary.Lybrary(storage_path=LIBRARY_DB_PATH) # 创建 MCP 服务器 server = Server("lybrary-mcp-server") # 1. 定义工具（Tools）：供 AI Agent 调用的函数 @server.list_tools() async def handle_list_tools(): """告诉 AI 本服务器提供哪些工具""" return [ { "name": "remember_code", "description": "将一段代码及其元数据存储到 Lybrary 记忆库中。", "inputSchema": { "type": "object", "properties": { "code_content": {"type": "string", "description": "要记忆的代码字符串"}, "filepath": {"type": "string", "description": "代码所在的虚拟文件路径"}, "language": {"type": "string", "description": "编程语言，如 'python'、'javascript'"} }, "required": ["code_content"] } }, { "name": "search_code_by_text", "description": "在 Lybrary 记忆库中通过文本关键词搜索代码。", "inputSchema": { "type": "object", "properties": { "query_text": {"type": "string", "description": "搜索关键词"} }, "required": ["query_text"] } }, { "name": "search_code_by_ast", "description": "在 Lybrary 记忆库中通过 AST 节点类型搜索代码（如查找所有函数定义）。", "inputSchema": { "type": "object", "properties": { "ast_node_kind": {"type": "string", "description": "AST节点类型，如 'FunctionDef', 'ClassDef'"} }, "required": ["ast_node_kind"] } }, ] # 2. 实现工具的执行函数 @server.call_tool() async def handle_call_tool(name: str, arguments: dict): """执行 AI Agent 请求的工具""" if name == "remember_code": code_content = arguments["code_content"] filepath = arguments.get("filepath", "unknown.py") language = arguments.get("language", "python") library.remember(content=code_content, metadata={"filepath": filepath, "language": language}) return { "content": [{"type": "text", "text": f"代码已成功记忆到 Lybrary (路径: {filepath})。"}] } elif name == "search_code_by_text": query = arguments["query_text"] results = library.search(query=query, search_type="text") response_text = f"找到 {len(results)} 个结果:\n" for r in results[:5]: # 限制返回前5个 response_text += f"- {r.metadata.get('filepath')}: {r.content[:80]}...\n" return { "content": [{"type": "text", "text": response_text}] } elif name == "search_code_by_ast": node_kind = arguments["ast_node_kind"] results = library.search(query=node_kind, search_type="ast_kind") response_text = f"找到 {len(results)} 个 '{node_kind}' 节点:\n" for r in results[:5]: response_text += f"- {r.metadata.get('filepath')}\n" return { "content": [{"type": "text", "text": response_text}] } else: raise ValueError(f"未知工具: {name}") # 3. 资源（Resources）定义：服务器可以提供的静态数据（可选） # @server.list_resources() # async def handle_list_resources(): # return [{"uri": "lybrary://info", "name": "Lybrary Info", "description": "关于Lybrary存储的信息"}] # @server.read_resource() # async def handle_read_resource(uri: str): # if uri == "lybrary://info": # return {"contents": [{"type": "text", "text": f"Lybrary 数据库位于: {LIBRARY_DB_PATH.absolute()}"}]} async def main(): """运行 MCP 服务器（使用 stdio 通信）""" async with server.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ == "__main__": asyncio.run(main())

4.2 配置 AI 客户端（以 Claude Desktop 为例）

要让 Claude Desktop 连接我们的 Lybrary MCP 服务器，需要编辑其配置文件。

1. 找到 Claude Desktop 配置目录：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件：如果文件不存在则创建。添加mcpServers配置项。

{ "mcpServers": { "lybrary": { "command": "/path/to/your/lybrary-env/bin/python", "args": [ "/path/to/your/lybrary_mcp_server.py" ] } } }

关键配置说明：

• command：指向你虚拟环境中 Python 解释器的绝对路径。
• args：第一个元素是你的 MCP 服务器脚本的绝对路径。

3. 重启 Claude Desktop：保存配置文件后，完全重启 Claude Desktop 应用。

4.3 验证与使用

重启后，在 Claude Desktop 中新建对话。你应该能看到 Claude 拥有了新的能力。你可以尝试对它说：

“使用 Lybrary 工具，记住这段代码：def hello(): print(\"world\")，文件路径设为test.py。”

或者：

“使用 Lybrary 工具，搜索所有函数定义。”

Claude 会调用你编写的 MCP 服务器工具，与 Lybrary 数据库交互，并将结果返回给你。这样，AI Agent 就拥有了一个持久化的、可查询的代码记忆库。

5. 实战：构建一个具备长期记忆的代码助手工作流

让我们设计一个完整的场景，将 Lybrary 融入日常开发。

场景：你正在开发一个 Python Web 项目，使用 AI 助手（如 Cursor 或 Claude）帮忙。你希望助手能记住项目中的核心工具函数、数据模型和 API 端点，并在后续的编码中引用它们。

5.1 初始化项目与 Lybrary

# 1. 创建项目目录 mkdir my_web_project && cd my_web_project # 2. 创建虚拟环境并安装 Lybrary python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows pip install lybrary lybrary-mcp-server # 假设的服务器包 # 3. 创建 Lybrary 初始化脚本 init_lybrary.py

init_lybrary.py内容：

# init_lybrary.py - 扫描项目文件并存入 Lybrary import lybrary from pathlib import Path import ast def store_file_to_lybrary(file_path: Path, library_instance: lybrary.Lybrary): """读取单个文件并存储到 Lybrary""" try: content = file_path.read_text(encoding='utf-8') # 可以尝试解析，确保是有效代码（可选） # ast.parse(content) library_instance.remember( content=content, metadata={ "filepath": str(file_path.relative_to(Path.cwd())), "language": "python", "project": "my_web_project" } ) print(f"已记忆: {file_path}") except (UnicodeDecodeError, SyntaxError) as e: print(f"跳过非文本或语法错误文件 {file_path}: {e}") def main(): library_db = Path("./.lybrary_project_db") lib = lybrary.Lybrary(storage_path=library_db) # 扫描项目中的 .py 文件 project_root = Path.cwd() for py_file in project_root.rglob("*.py"): if ".venv" in str(py_file) or "__pycache__" in str(py_file): continue # 跳过虚拟环境和缓存目录 store_file_to_lybrary(py_file, lib) print(f"\n项目代码初始化完成！Lybrary 数据库位于: {library_db.absolute()}") if __name__ == "__main__": main()

运行此脚本，将当前项目所有 Python 文件存入 Lybrary。

5.2 集成到 AI 助手工作流

1. 配置 MCP 服务器：使用第 4 节的lybrary_mcp_server.py，但修改LIBRARY_DB_PATH指向./.lybrary_project_db。
2. 配置你的 AI 编辑器/助手：无论是 Claude Desktop、Cursor 还是其他支持 MCP 的工具，都按照其文档配置 MCP 服务器，指向你修改后的脚本。
3. 日常开发：
   • 当 AI 助手生成新代码时：提示它调用remember_code工具将新代码存入 Lybrary。
   • 当你需要查找已有代码时：直接让 AI 助手“搜索所有包含UserModel的代码”或“查找项目里所有的路由定义（@app.route）”。
   • 当进行重构时：让 AI 助手分析“如果修改了utils/validator.py中的validate_email函数，会影响哪些文件？”（这需要 Lybrary 支持更高级的 AST 依赖分析）。

5.3 自动化同步脚本（可选）

为了保持 Lybrary 记忆与项目代码同步，可以创建一个简单的 Git 钩子或文件监控脚本。

# watch_and_sync.py - 简易文件监控（概念示例，使用 watchdog 库） import time from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler from pathlib import Path import lybrary class LybrarySyncHandler(FileSystemEventHandler): def __init__(self, library_instance): self.lib = library_instance def on_modified(self, event): if not event.is_directory and event.src_path.endswith('.py'): self._update_file(Path(event.src_path)) def _update_file(self, file_path): try: content = file_path.read_text() # 简单的更新策略：先删除旧记忆（根据filepath），再添加新记忆 # 注意：实际 Lybrary API 可能需要 `update` 或 `delete` 方法 print(f"检测到更新: {file_path}. 请手动或通过API更新Lybrary。") # 示例：self.lib.update(content=content, metadata={"filepath": str(file_path)}) except Exception as e: print(f"处理文件 {file_path} 失败: {e}") if __name__ == "__main__": lib = lybrary.Lybrary(storage_path=Path("./.lybrary_project_db")) event_handler = LybrarySyncHandler(lib) observer = Observer() observer.schedule(event_handler, path=".", recursive=True) observer.start() try: while True: time.sleep(1) except KeyboardInterrupt: observer.stop() observer.join()

6. 常见问题与排查思路

在集成和使用 Lybrary 及 MCP 服务器时，你可能会遇到以下问题：

7. 最佳实践与工程建议

将 Lybrary 用于生产级 AI Agent 项目时，请考虑以下建议：

1. 分项目、分上下文存储：不要将所有代码混在一个 Lybrary 实例中。为不同的项目或代码库创建独立的存储路径（storage_path）。这能提高查询效率和准确性，避免无关代码干扰。

2. 精心设计元数据（Metadata）：metadata字段是强大的过滤器。除了filepath和language，可以添加module、author、created_at、tags（如“utility”，“database”，“api”）等。这将极大增强基于属性的检索能力。

3. 建立代码记忆的更新与淘汰机制：

   • 版本关联：将代码记忆与 Git commit hash 关联，可以追溯历史版本。
   • 定期清理：对于已删除或彻底重构的文件，应有 API 或脚本从 Lybrary 中移除旧记忆，防止提供过时信息。
   • 增量更新：监听文件变化，自动更新 Lybrary 中的对应记录，而不是全量重建。

4. 安全与隐私：

   • 敏感信息：Lybrary 会存储代码原文。切勿将包含密钥、密码、个人敏感信息的代码存入。考虑在记忆前进行简单的静态扫描或使用.gitignore类似的排除列表。
   • 数据库位置：将.lybrary_db目录加入项目的.gitignore文件中，避免将记忆数据库误提交到版本控制系统。

5. 结合其他 AI Agent 记忆模式：Lybrary 专注于代码的结构化记忆。对于自然语言对话历史、任务执行结果等，应结合其他记忆系统（如向量数据库存储对话摘要）。让 Lybrary 专注于它最擅长的领域——代码。

6. 测试你的 MCP 工具：在将 MCP 服务器交给 AI 使用前，务必编写简单的测试脚本，模拟 AI 调用工具的过程，确保每个工具（remember_code，search_code_by_ast）都能按预期工作并返回正确的格式。

通过本文的讲解，你应该已经理解了 Lybrary 如何作为一个持久化、AST 感知的代码记忆库来解决 AI Agent 的“记忆失忆”问题，并掌握了通过pip install安装、配置 MCP 服务器将其集成到 AI 工作流中的完整流程。从初始化记忆库、进行智能查询，到配置 MCP 服务器与 Claude 等客户端联动，每一步都提供了可运行的代码示例和详细的配置说明。

下一步，你可以探索 Lybrary 更高级的 AST 查询模式，将其与 CI/CD 流水线结合以实现代码变更的自动记忆更新，或者尝试为其他语言（如 JavaScript、Go）提供支持。拥有长期、结构化记忆的 AI 编码助手，将不再是简单的即时对话工具，而能真正成为你项目团队中一个“记得”所有技术细节的资深伙伴。