在項目迭代和日常開發(fā)中我們常常需要向AI助手如ChatGPT、Claude、DeepSeek等反復提供項目背景、代碼片段、API文檔等上下文信息。每次開啟新對話都像“從頭開始”手動復制粘貼既低效又容易遺漏關鍵細節(jié)。你是否也渴望一個能自動記錄、整理并智能關聯工作上下文的“AI記憶卡”本文將分享一套完整的解決方案通過構建一個輕量級的本地“AI記憶卡”系統自動收集你的工作進度、代碼變更、會議紀要和靈感碎片并在與AI交互時自動附上相關上下文。這套方案基于開源工具鏈無需復雜部署適合開發(fā)者、產品經理和任何需要頻繁使用AI輔助工作的知識工作者。學完后你將掌握從環(huán)境搭建、數據收集、向量化存儲到智能檢索集成的全流程實戰(zhàn)能力。1. 背景與核心概念為什么需要“AI記憶卡”1.1 當前AI協作的痛點現代AI大模型在代碼生成、問題排查、方案設計等方面表現出色但其對話本質上是“無狀態(tài)”的。這意味著上下文丟失每次新對話AI都不知道你之前討論過什么、項目進展到哪一步。信息重復輸入你需要反復解釋項目結構、技術棧、業(yè)務規(guī)則。知識碎片化有價值的工作記錄、決策思路散落在各個聊天記錄和本地文件中難以系統化利用。1.2 “AI記憶卡”是什么“AI記憶卡”是一個比喻它指的是一套本地化、自動化的工作上下文管理與注入系統。其核心功能是自動收集監(jiān)控你的工作環(huán)境如代碼倉庫、筆記文檔、通訊工具自動抓取結構化信息。智能存儲將收集的信息轉化為向量Embedding存入向量數據庫實現語義化檢索。按需注入在你與AI助手對話時系統自動根據你的問題從記憶庫中檢索最相關的上下文片段并拼接到提示詞Prompt中實現“有記憶”的對話。1.3 核心價值與應用場景對開發(fā)者自動關聯當前Git提交、代碼片段、錯誤日志讓AI精準理解bug上下文。對團隊共享項目文檔、API設計稿、會議紀要讓AI基于最新團隊共識提供建議。對個人鏈接你的知識庫、學習筆記、待辦清單讓AI成為你的個性化第二大腦。 與手動整理相比這套系統實現了從“被動喂養(yǎng)”到“主動關聯”的轉變顯著提升AI協作的深度和效率。2. 環(huán)境準備與版本說明我們將使用Python作為主要開發(fā)語言結合一系列輕量級開源庫。請確保你的環(huán)境滿足以下要求。2.1 基礎環(huán)境操作系統Windows 10/11, macOS 10.15, 或主流Linux發(fā)行版如Ubuntu 20.04。Python版本 3.8 - 3.11。推薦使用3.9或3.10以獲得最佳兼容性。包管理工具pip通常隨Python安裝。版本控制Git用于監(jiān)控代碼變更。可選IDEVS Code, PyCharm等。2.2 核心依賴庫及版本我們將創(chuàng)建一個requirements.txt文件來管理依賴。以下是核心庫及其作用# 核心框架與異步 fastapi0.104.1 uvicorn[standard]0.24.0 pydantic2.5.0 # 文件監(jiān)控與系統交互 watchfiles0.20.0 python-dotenv1.0.0 # 文本處理與加載 langchain0.0.340 langchain-community0.0.10 # 包含多種文檔加載器 unstructured0.12.0 # 用于解析多種文檔格式 # 向量數據庫與嵌入模型 chromadb0.4.18 # 輕量級向量數據庫 sentence-transformers2.2.2 # 本地運行嵌入模型 # 或者使用OpenAI嵌入需API Key # openai1.3.0 # 前端界面可選 streamlit1.28.0版本說明以上版本在撰寫時經過測試能保證基本功能運行。由于開源庫迭代迅速實際使用時若遇到兼容性問題可適當調整次要版本。重點在于理解各庫的職責和配置方式。2.3 項目結構預覽在開始前我們先規(guī)劃項目目錄這有助于理解后續(xù)的代碼組織。ai_memory_card/ ├── .env # 環(huán)境變量如API密鑰 ├── requirements.txt # 項目依賴 ├── app.py # FastAPI主應用入口 ├── config.py # 配置文件 ├── memory_core/ # 核心模塊 │ ├── __init__.py │ ├── collector.py # 數據收集器 │ ├── embedder.py # 嵌入模型管理 │ ├── vector_store.py # 向量數據庫操作 │ └── retriever.py # 檢索器 ├── sources/ # 監(jiān)控的數據源目錄示例 │ ├── code/ │ ├── notes/ │ └── logs/ ├── storage/ # 向量數據庫持久化目錄 │ └── chroma_db/ └── scripts/ # 工具腳本 └── init_memory.py # 初始化記憶庫腳本接下來我們開始搭建系統核心。3. 核心模塊拆解與原理“AI記憶卡”系統主要由四個核心模塊組成收集器Collector、嵌入器Embedder、向量存儲Vector Store和檢索器Retriever。3.1 收集器Collector自動捕獲工作上下文收集器的職責是從不同源頭抓取數據。我們采用基于事件如文件變化和基于輪詢如定時讀取Git日志的混合策略。關鍵設計文件系統監(jiān)控使用watchfiles庫監(jiān)聽sources/目錄下的文件變動增、刪、改實時觸發(fā)處理流程。Git鉤子集成在項目的.git/hooks/post-commit中注入腳本在每次提交后自動捕獲提交信息、差異代碼作為記憶片段。文檔加載器利用LangChain的UnstructuredFileLoader、TextLoader等支持解析.txt,.md,.py,.pdf等多種格式。元數據附加為每一段文本記憶片段附加來源、時間戳、類型代碼/筆記/日志等元數據便于后續(xù)篩選。3.2 嵌入器Embedder與向量存儲這是實現語義檢索的核心。我們將文本轉換為計算機能理解的數值向量。工作流程文本分塊長文檔需要被切割成大小適中的片段如500字符同時保持語義連貫。LangChain的RecursiveCharacterTextSplitter是常用工具。向量化使用嵌入模型將文本塊轉換為固定維度的向量如384維或768維。我們優(yōu)先選用本地模型如all-MiniLM-L6-v2它平衡了速度與精度且無需網絡調用和付費。向量存儲將向量及其對應的文本塊、元數據存入ChromaDB。ChromaDB 是一個輕量級、可持久化的向量數據庫支持按集合Collection組織數據非常適合個人或小團隊使用。3.3 檢索器Retriever智能關聯問題與記憶當用戶提出問題時檢索器負責找到最相關的記憶片段。檢索過程將用戶問題同樣轉換為向量。在向量數據庫中進行相似性搜索通常使用余弦相似度。返回相似度最高的前k個文本片段如前3個?；旌蠙z索除了向量檢索還可以結合元數據過濾例如只檢索“代碼”類型的記憶或最近一周的記憶使結果更精準。4. 完整實戰(zhàn)構建你的第一張“AI記憶卡”現在我們將一步步實現上述系統。請跟隨操作并注意代碼中的注釋。4.1 初始化項目與環(huán)境首先創(chuàng)建項目目錄并安裝依賴。# 1. 創(chuàng)建項目目錄 mkdir ai_memory_card cd ai_memory_card # 2. 創(chuàng)建虛擬環(huán)境推薦 python -m venv venv # Windows 激活: venv\Scripts\activate # macOS/Linux 激活: source venv/bin/activate # 3. 創(chuàng)建 requirements.txt 并寫入上一節(jié)的依賴內容 # 可以使用編輯器創(chuàng)建或使用 echo 命令注意版本號 # 4. 安裝依賴 pip install -r requirements.txt # 5. 創(chuàng)建項目結構所需目錄 mkdir -p memory_core sources/{code,notes,logs} storage/chroma_db scripts4.2 編寫核心配置文件創(chuàng)建config.py集中管理配置參數。# config.py import os from pathlib import Path from pydantic_settings import BaseSettings class Settings(BaseSettings): # 項目路徑 BASE_DIR: Path Path(__file__).parent SOURCES_DIR: Path BASE_DIR / sources STORAGE_DIR: Path BASE_DIR / storage VECTOR_DB_PATH: Path STORAGE_DIR / chroma_db # 向量數據庫配置 COLLECTION_NAME: str work_memory EMBEDDING_MODEL: str all-MiniLM-L6-v2 # 本地句子嵌入模型 # 如果使用OpenAI請取消注釋并設置API Key # OPENAI_API_KEY: str # EMBEDDING_MODEL: str text-embedding-ada-002 # 文本處理配置 CHUNK_SIZE: int 500 # 文本分塊大小 CHUNK_OVERLAP: int 50 # 塊之間重疊字符數 # 檢索配置 RETRIEVE_TOP_K: int 3 # 每次檢索返回的記憶片段數量 # 文件監(jiān)控配置 WATCH_PATTERNS: list [*.md, *.txt, *.py, *.js, *.java, *.json] class Config: env_file .env # 從.env文件加載環(huán)境變量 settings Settings()4.3 實現嵌入與向量存儲模塊創(chuàng)建memory_core/embedder.py和memory_core/vector_store.py。# memory_core/embedder.py from sentence_transformers import SentenceTransformer from langchain.embeddings import HuggingFaceEmbeddings import numpy as np from config import settings import logging logger logging.getLogger(__name__) class LocalEmbedder: 本地嵌入模型封裝 def __init__(self): model_name settings.EMBEDDING_MODEL logger.info(f正在加載嵌入模型: {model_name}) # 使用LangChain封裝的HuggingFace嵌入兼容性更好 self.embeddings HuggingFaceEmbeddings( model_namefsentence-transformers/{model_name}, model_kwargs{device: cpu}, # 有GPU可改為 cuda encode_kwargs{normalize_embeddings: True} # 歸一化便于余弦相似度計算 ) logger.info(嵌入模型加載完畢。) def embed_documents(self, texts: list[str]) - list[list[float]]: 將一批文本轉換為向量 return self.embeddings.embed_documents(texts) def embed_query(self, text: str) - list[float]: 將單個查詢文本轉換為向量 return self.embeddings.embed_query(text) # 全局嵌入器實例 embedder LocalEmbedder()# memory_core/vector_store.py import chromadb from chromadb.config import Settings as ChromaSettings from typing import List, Dict, Any from config import settings import logging from memory_core.embedder import embedder logger logging.getLogger(__name__) class VectorStoreManager: 向量數據庫管理類 def __init__(self): self.client chromadb.PersistentClient( pathstr(settings.VECTOR_DB_PATH), settingsChromaSettings(anonymized_telemetryFalse) # 禁用匿名數據收集 ) self.collection self.client.get_or_create_collection( namesettings.COLLECTION_NAME, metadata{description: AI工作記憶存儲} ) logger.info(f向量數據庫連接成功集合: {settings.COLLECTION_NAME}) def add_memories(self, documents: List[str], metadatas: List[Dict], ids: List[str]): 添加記憶片段到向量數據庫 if not documents: return # 生成嵌入向量 embeddings embedder.embed_documents(documents) # 添加到集合 self.collection.add( embeddingsembeddings, documentsdocuments, metadatasmetadatas, idsids ) logger.info(f成功添加 {len(documents)} 條記憶。) def search(self, query: str, filter_metadata: Dict None, top_k: int None) - List[Dict[str, Any]]: 檢索與查詢最相關的記憶 if top_k is None: top_k settings.RETRIEVE_TOP_K # 將查詢文本向量化 query_embedding embedder.embed_query(query) # 執(zhí)行搜索 results self.collection.query( query_embeddings[query_embedding], n_resultstop_k, wherefilter_metadata # 元數據過濾條件 ) # 格式化結果 memories [] if results[documents]: for i in range(len(results[documents][0])): memories.append({ content: results[documents][0][i], metadata: results[metadatas][0][i], distance: results[distances][0][i] # 距離越小越相似 }) return memories def list_all_collections(self): 列出所有集合用于調試 return self.client.list_collections() # 全局向量存儲管理器實例 vector_store VectorStoreManager()4.4 實現文件收集器創(chuàng)建memory_core/collector.py實現一個監(jiān)控指定目錄的簡易收集器。# memory_core/collector.py import hashlib import time from pathlib import Path from typing import List, Dict, Any from langchain.document_loaders import TextLoader, UnstructuredMarkdownLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from config import settings from memory_core.vector_store import vector_store import logging logger logging.getLogger(__name__) class FileCollector: 文件收集器 def __init__(self): self.text_splitter RecursiveCharacterTextSplitter( chunk_sizesettings.CHUNK_SIZE, chunk_overlapsettings.CHUNK_OVERLAP, length_functionlen, separators[\n\n, \n, 。, , , , , , ] ) def process_file(self, file_path: Path) - List[Dict[str, Any]]: 處理單個文件返回文本塊和元數據列表 memories [] try: # 根據后綴選擇加載器 if file_path.suffix.lower() in [.txt, .md, .py, .js, .java, .json]: if file_path.suffix .md: loader UnstructuredMarkdownLoader(str(file_path)) else: loader TextLoader(str(file_path), encodingutf-8) documents loader.load() for doc in documents: # 分割文本 chunks self.text_splitter.split_text(doc.page_content) for i, chunk in enumerate(chunks): if not chunk.strip(): continue # 為每個塊生成唯一ID文件路徑內容哈希 chunk_id f{file_path.stem}_{i}_{hashlib.md5(chunk.encode()).hexdigest()[:8]} # 構建元數據 metadata { source: str(file_path.relative_to(settings.BASE_DIR)), type: self._get_file_type(file_path), timestamp: time.time(), chunk_index: i } memories.append({ id: chunk_id, content: chunk, metadata: metadata }) logger.info(f處理文件 {file_path.name}生成 {len(chunks)} 個文本塊。) else: logger.warning(f暫不支持的文件格式: {file_path.suffix}) except Exception as e: logger.error(f處理文件 {file_path} 時出錯: {e}) return memories def _get_file_type(self, file_path: Path) - str: 根據文件后綴判斷類型 suffix file_path.suffix.lower() if suffix in [.py, .js, .java, .cpp, .go]: return code elif suffix in [.md, .txt]: return note elif suffix in [.log, .err]: return log else: return other def process_directory(self, directory: Path) - int: 處理整個目錄并存入向量數據庫 all_memories [] if not directory.exists(): logger.warning(f目錄不存在: {directory}) return 0 # 遞歸查找支持的文件 for pattern in settings.WATCH_PATTERNS: for file_path in directory.rglob(pattern): if file_path.is_file(): memories self.process_file(file_path) all_memories.extend(memories) # 批量添加到向量數據庫 if all_memories: documents [m[content] for m in all_memories] metadatas [m[metadata] for m in all_memories] ids [m[id] for m in all_memories] vector_store.add_memories(documents, metadatas, ids) return len(all_memories) # 全局收集器實例 collector FileCollector()4.5 實現檢索器與API接口創(chuàng)建memory_core/retriever.py和app.py提供檢索API。# memory_core/retriever.py from typing import List, Dict, Any from config import settings from memory_core.vector_store import vector_store import logging logger logging.getLogger(__name__) class MemoryRetriever: 記憶檢索器 def retrieve(self, query: str, source_filter: str None, type_filter: str None) - List[Dict[str, Any]]: 根據查詢檢索相關記憶。 Args: query: 查詢文本 source_filter: 按來源過濾如 sources/notes/xxx.md type_filter: 按類型過濾如 code, note, log Returns: 相關記憶列表按相關性排序 # 構建元數據過濾條件 filter_metadata {} if source_filter: filter_metadata[source] {$contains: source_filter} if type_filter: filter_metadata[type] type_filter logger.info(f檢索查詢: {query}, 過濾器: {filter_metadata}) memories vector_store.search(query, filter_metadatafilter_metadata if filter_metadata else None) # 格式化輸出 formatted_results [] for mem in memories: formatted_results.append({ content: mem[content][:200] ... if len(mem[content]) 200 else mem[content], source: mem[metadata].get(source, unknown), type: mem[metadata].get(type, unknown), relevance_score: round(1 - mem[distance], 4) # 將距離轉換為相似度分數 }) return formatted_results def get_context_for_ai(self, query: str, max_chars: int 1500) - str: 為AI對話生成上下文提示。 將檢索到的記憶片段拼接成一段連貫的上下文。 memories self.retrieve(query) if not memories: return 暫無相關歷史上下文。\n context_parts [以下是你之前的相關工作記錄供參考\n] total_chars 0 for i, mem in enumerate(memories, 1): mem_text f[{i}] 來源{mem[source]} (類型{mem[type]}, 相關度{mem[relevance_score]:.2%})\n{mem[content]}\n\n if total_chars len(mem_text) max_chars: break context_parts.append(mem_text) total_chars len(mem_text) context_parts.append(f\n--- 以上是基于你工作記憶的 {len(context_parts)-1} 條相關上下文 ---\n) return .join(context_parts) retriever MemoryRetriever()# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import Optional, List import uvicorn import logging from memory_core.retriever import retriever from memory_core.collector import collector from config import settings # 配置日志 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) app FastAPI(titleAI記憶卡 API, description自動管理工作上下文并與AI集成的服務) class SearchRequest(BaseModel): query: str source_filter: Optional[str] None type_filter: Optional[str] None class SearchResponse(BaseModel): query: str memories: List[dict] count: int class IndexRequest(BaseModel): path: str # 相對于sources目錄的路徑或絕對路徑 app.get(/) async def root(): return {message: AI記憶卡服務運行中, version: 1.0.0} app.post(/search, response_modelSearchResponse) async def search_memories(request: SearchRequest): 檢索相關記憶 try: memories retriever.retrieve( queryrequest.query, source_filterrequest.source_filter, type_filterrequest.type_filter ) return SearchResponse( queryrequest.query, memoriesmemories, countlen(memories) ) except Exception as e: logger.error(f檢索失敗: {e}) raise HTTPException(status_code500, detailf檢索失敗: {str(e)}) app.post(/index) async def index_directory(request: IndexRequest): 手動索引一個目錄或文件 import os from pathlib import Path target_path Path(request.path) if not target_path.is_absolute(): target_path settings.BASE_DIR / target_path if not target_path.exists(): raise HTTPException(status_code404, detailf路徑不存在: {target_path}) try: if target_path.is_file(): # 索引單個文件 memories collector.process_file(target_path) if memories: documents [m[content] for m in memories] metadatas [m[metadata] for m in memories] ids [m[id] for m in memories] from memory_core.vector_store import vector_store vector_store.add_memories(documents, metadatas, ids) count len(memories) else: count 0 msg f文件已索引 else: # 索引目錄 count collector.process_directory(target_path) msg f目錄已索引 return {message: f{msg}新增 {count} 條記憶。} except Exception as e: logger.error(f索引失敗: {e}) raise HTTPException(status_code500, detailf索引失敗: {str(e)}) app.get(/generate-context) async def generate_context(query: str, max_chars: int 1500): 生成用于AI提示的上下文文本 try: context retriever.get_context_for_ai(query, max_chars) return {query: query, context: context} except Exception as e: logger.error(f生成上下文失敗: {e}) raise HTTPException(status_code500, detailf生成上下文失敗: {str(e)}) if __name__ __main__: logger.info(啟動AI記憶卡服務...) uvicorn.run(app, host0.0.0.0, port8000)4.6 運行與驗證現在讓我們啟動服務并進行測試。步驟1啟動API服務# 在項目根目錄下執(zhí)行 python app.py看到日志INFO: Uvicorn running on http://0.0.0.0:8000表示啟動成功。步驟2準備示例數據在sources/notes/目錄下創(chuàng)建一個筆記文件project_plan.md。# 項目計劃個人任務管理系統 **目標**開發(fā)一個CLI工具管理每日任務。 **技術棧**Python, Typer, SQLite。 **核心功能** 1. 添加任務addtaskman add “寫周報” -p high 2. 列出任務list按優(yōu)先級排序。 3. 完成任務done標記任務狀態(tài)。 **當前進展**已完成數據庫模型設計正在開發(fā)add命令。 **遇到的問題**Typer的回調函數中如何共享數據庫連接步驟3手動索引數據使用curl或瀏覽器訪問API端點索引我們剛創(chuàng)建的筆記目錄。# 使用curl命令 curl -X POST http://localhost:8000/index \ -H Content-Type: application/json \ -d {path: sources/notes} # 預期返回 # {message:目錄已索引新增 X 條記憶。}步驟4檢索記憶現在我們可以模擬一個開發(fā)問題看看系統能否找到相關記憶。curl -X POST http://localhost:8000/search \ -H Content-Type: application/json \ -d {query: Typer回調函數里怎么共享數據庫連接, type_filter: note} # 預期返回簡化 # { # query: ..., # memories: [ # { # content: **遇到的問題**Typer的回調函數中如何共享數據庫連接..., # source: sources/notes/project_plan.md, # type: note, # relevance_score: 0.92 # }, # ...其他相關片段 # ], # count: 2 # }步驟5生成AI對話上下文這是最關鍵的一步獲取格式化后的上下文以便粘貼給AI助手。curl http://localhost:8000/generate-context?queryTyper共享數據庫連接max_chars1000返回的context字段內容可以直接作為提示詞前綴發(fā)給ChatGPT等AI例如以下是你之前的相關工作記錄供參考 [1] 來源sources/notes/project_plan.md (類型note, 相關度92.00%) **遇到的問題**Typer的回調函數中如何共享數據庫連接 --- 以上是基于你工作記憶的 1 條相關上下文 --- 我的問題是Typer共享數據庫連接5. 自動化集成與高級用法基礎系統搭建完成后我們可以讓它更自動化、更智能。5.1 實現文件監(jiān)控與自動索引創(chuàng)建scripts/watch_and_index.py實現后臺自動監(jiān)控。# scripts/watch_and_index.py import time from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler from pathlib import Path from memory_core.collector import collector from config import settings import logging logger logging.getLogger(__name__) class SourceFileHandler(FileSystemEventHandler): 處理文件系統事件 def on_modified(self, event): if not event.is_directory: self._process_event(event) def on_created(self, event): if not event.is_directory: self._process_event(event) def _process_event(self, event): file_path Path(event.src_path) logger.info(f檢測到文件變動: {file_path}) # 避免頻繁觸發(fā)可加入防抖邏輯 time.sleep(0.5) # 簡單防抖 try: memories collector.process_file(file_path) if memories: logger.info(f自動索引文件: {file_path.name}, 新增 {len(memories)} 個片段。) except Exception as e: logger.error(f自動索引失敗: {e}) def start_watching(): 啟動文件監(jiān)控 event_handler SourceFileHandler() observer Observer() observer.schedule(event_handler, str(settings.SOURCES_DIR), recursiveTrue) observer.start() logger.info(f開始監(jiān)控目錄: {settings.SOURCES_DIR}) try: while True: time.sleep(1) except KeyboardInterrupt: observer.stop() observer.join() if __name__ __main__: start_watching()5.2 集成到AI聊天工具瀏覽器擴展思路完全自動化需要與AI界面深度集成。一個可行的方案是開發(fā)一個瀏覽器擴展如Chrome Extension。擴展核心邏輯content script監(jiān)聽ChatGPT等網頁的輸入框。當用戶開始輸入時提取輸入框中的關鍵詞或句子。向本地http://localhost:8000/generate-context發(fā)送請求獲取相關上下文。將返回的上下文自動插入到輸入框的最前面。由于實現瀏覽器擴展涉及特定API這里提供概念性偽代碼// 偽代碼Chrome擴展內容腳本概念 async function enhanceAIInput() { const inputBox document.querySelector(textarea[aria-label*message]); // 根據實際網頁調整選擇器 if (!inputBox) return; inputBox.addEventListener(input, _.debounce(async (e) { const query e.target.value; if (query.length 5) return; // 輸入過短時不查詢 try { const resp await fetch(http://localhost:8000/generate-context?query${encodeURIComponent(query)}); const data await resp.json(); if (data.context data.context.includes(相關上下文)) { // 將上下文智能地添加到輸入內容前 const enhancedPrompt data.context \n\n query; // 注意直接設置value會觸發(fā)循環(huán)需要巧妙處理 // 一種方法是提供一個“添加上下文”的按鈕 } } catch (err) { console.error(獲取記憶上下文失敗:, err); } }, 500)); // 防抖500毫秒 }5.3 與Git集成捕獲代碼上下文創(chuàng)建.git/hooks/post-commit鉤子需賦予可執(zhí)行權限在每次提交后自動記錄。#!/bin/bash # .git/hooks/post-commit REPO_ROOT$(git rev-parse --show-toplevel) HOOKS_DIR$REPO_ROOT/.git/hooks MEMORY_CARD_DIR$REPO_ROOT/../ai_memory_card # 假設記憶卡項目在倉庫同級目錄 # 獲取本次提交信息 COMMIT_MSG$(git log -1 --pretty%B) LAST_COMMIT_HASH$(git rev-parse HEAD) AUTHOR$(git log -1 --prettyformat:%an) # 構建記憶文本 MEMORY_CONTENTGit提交$LAST_COMMIT_HASH 作者$AUTHOR 信息$COMMIT_MSG # 調用記憶卡API進行記錄 curl -X POST http://localhost:8000/index \ -H Content-Type: application/json \ -d {\path\: \$REPO_ROOT\} \ --max-time 2 /dev/null 21 echo [AI記憶卡] 已嘗試記錄本次提交上下文。6. 常見問題與排查思路在搭建和使用過程中你可能會遇到以下問題。問題現象可能原因解決思路啟動app.py時報ImportError依賴未安裝或虛擬環(huán)境未激活1. 確認已激活虛擬環(huán)境。2. 運行pip install -r requirements.txt。訪問http://localhost:8000無響應服務未啟動或端口被占用1. 檢查python app.py是否運行。2. 使用netstat -ano | findstr :8000(Win) 或lsof -i:8000(Mac/Linux) 查看端口占用并終止沖突進程。文件監(jiān)控腳本不觸發(fā)文件路徑不正確或事件未捕獲1. 確認sources/目錄下有文件。2. 檢查watchdog庫是否安裝正確。3. 嘗試手動修改一個文件看日志輸出。檢索結果不相關嵌入模型不適合或文本分塊過大1. 嘗試更換嵌入模型如paraphrase-multilingual-MiniLM-L12-v2支持中文。2. 調整config.py中的CHUNK_SIZE如改為300和CHUNK_OVERLAP。3. 檢查查詢語句是否足夠明確。向量數據庫報錯Collection not found數據庫路徑損壞或版本不兼容1. 刪除storage/chroma_db目錄重啟服務會重建。2. 檢查 ChromaDB 版本嘗試降級到穩(wěn)定版如pip install chromadb0.4.15。處理中文文本亂碼或錯誤文件編碼問題1. 確保源代碼文件保存為 UTF-8 編碼。2. 在TextLoader中明確指定encodingutf-8。內存占用過高嵌入模型加載或文件過大1. 對于大型文檔先進行預處理和過濾。2. 考慮使用更輕量的嵌入模型。3. 定期清理不重要的記憶片段可通過API擴展刪除功能。7. 最佳實踐與工程建議將“AI記憶卡”投入日常使用以下建議能幫助你獲得更好體驗并避免陷阱。7.1 數據源管理分級分類在sources/下建立清晰的子目錄如sources/project_a/code/,sources/project_b/docs/。通過元數據type和source進行高效過濾。敏感信息過濾切勿將包含密碼、密鑰、個人隱私信息的文件放入監(jiān)控目錄。可通過在collector.py的process_file方法中添加關鍵詞過濾邏輯。文件類型限制只監(jiān)控你真正關心的文件類型在config.py的WATCH_PATTERNS中配置避免處理二進制文件如圖片、視頻產生無意義內容。7.2 性能與可維護性增量索引當前示例是全量處理目錄。生產環(huán)境應記錄已索引文件的哈希值實現增量更新避免重復計算嵌入向量。批量操作向量數據庫的add操作應批量進行而不是單條插入以提高效率。定期清理設計一個簡單的TTL生存時間機制或手動審核界面定期清理過時、無效的記憶片段控制數據庫大小。日志記錄為關鍵操作如文件處理、向量添加、檢索查詢添加詳細日志便于后期調試和審計。7.3 提示詞工程優(yōu)化上下文格式化get_context_for_ai方法生成的上下文格式直接影響AI的理解?？梢詢?yōu)化模板使其更符合特定AI助手的提示風格。例如為ChatGPT設計專用模板。相關性閾值在retriever.py中可以為檢索結果設置一個相似度分數閾值如relevance_score 0.7則丟棄避免注入不相關的低質量上下文。元數據利用在構建最終提示時除了內容還可以強調來源和時間如“這是你昨天寫的關于XXX的代碼”幫助AI更好地理解上下文的新舊和重要性。7.4 安全邊界本地化部署本文方案的核心優(yōu)勢是數據完全本地化。嵌入模型、向量數據庫均在本地運行確保了工作隱私的安全。網絡訪問控制app.py默認監(jiān)聽0.0.0.0:8000。如果僅在本地使用可改為127.0.0.1:8000避免局域網內其他設備訪問。輸入驗證API接口如/index應對傳入的路徑參數進行嚴格校驗防止目錄遍歷攻擊Path Traversal。7.5 擴展方向支持更多數據源除了文件系統可以擴展收集器以支持從Notion、飛書文檔、Jira Issue、Slack頻道等平臺同步數據。集成更多AI工具除了Web端可以開發(fā)VS Code插件、Obsidian插件在編碼環(huán)境和筆記軟件內直接調用記憶上下文。實現記憶“對話”引入輕量級LLM如通過Ollama運行本地模型對檢索到的記憶進行總結、關聯分析而不僅僅是簡單羅列。這套“AI記憶卡”系統將一個理想化的概念變成了可運行的代碼。它可能不是最完美的但提供了一個堅實、可擴展的起點。你可以從今天開始先將sources/notes目錄用于記錄工作日志和問題體驗上下文自動關聯帶來的效率提升。然后逐步將代碼庫、項目文檔納入監(jiān)控范圍。隨著記憶庫的豐富你會發(fā)現向AI提問前不再需要費力組織背景信息它仿佛真的成為了你項目團隊中的一員始終記得之前的每一次討論和決策。技術的價值在于解決真實世界的摩擦希望這個項目能成為你高效工作的得力助手。 構建本地AI記憶卡系統：實現工作上下文智能管理與自動關聯
在項目迭代和日常開發(fā)中我們常常需要向AI助手如ChatGPT、Claude、DeepSeek等反復提供項目背景、代碼片段、API文檔等上下文信息。每次開啟新對話都像“從頭開始”手動復制粘貼既低效又容易遺漏關鍵細節(jié)。你是否也渴望一個能自動記錄、整理并智能關聯工作上下文的“AI記憶卡”本文將分享一套完整的解決方案通過構建一個輕量級的本地“AI記憶卡”系統自動收集你的工作進度、代碼變更、會議紀要和靈感碎片并在與AI交互時自動附上相關上下文。這套方案基于開源工具鏈無需復雜部署適合開發(fā)者、產品經理和任何需要頻繁使用AI輔助工作的知識工作者。學完后你將掌握從環(huán)境搭建、數據收集、向量化存儲到智能檢索集成的全流程實戰(zhàn)能力。1. 背景與核心概念為什么需要“AI記憶卡”1.1 當前AI協作的痛點現代AI大模型在代碼生成、問題排查、方案設計等方面表現出色但其對話本質上是“無狀態(tài)”的。這意味著上下文丟失每次新對話AI都不知道你之前討論過什么、項目進展到哪一步。信息重復輸入你需要反復解釋項目結構、技術棧、業(yè)務規(guī)則。知識碎片化有價值的工作記錄、決策思路散落在各個聊天記錄和本地文件中難以系統化利用。1.2 “AI記憶卡”是什么“AI記憶卡”是一個比喻它指的是一套本地化、自動化的工作上下文管理與注入系統。其核心功能是自動收集監(jiān)控你的工作環(huán)境如代碼倉庫、筆記文檔、通訊工具自動抓取結構化信息。智能存儲將收集的信息轉化為向量Embedding存入向量數據庫實現語義化檢索。按需注入在你與AI助手對話時系統自動根據你的問題從記憶庫中檢索最相關的上下文片段并拼接到提示詞Prompt中實現“有記憶”的對話。1.3 核心價值與應用場景對開發(fā)者自動關聯當前Git提交、代碼片段、錯誤日志讓AI精準理解bug上下文。對團隊共享項目文檔、API設計稿、會議紀要讓AI基于最新團隊共識提供建議。對個人鏈接你的知識庫、學習筆記、待辦清單讓AI成為你的個性化第二大腦。 與手動整理相比這套系統實現了從“被動喂養(yǎng)”到“主動關聯”的轉變顯著提升AI協作的深度和效率。2. 環(huán)境準備與版本說明我們將使用Python作為主要開發(fā)語言結合一系列輕量級開源庫。請確保你的環(huán)境滿足以下要求。2.1 基礎環(huán)境操作系統Windows 10/11, macOS 10.15, 或主流Linux發(fā)行版如Ubuntu 20.04。Python版本 3.8 - 3.11。推薦使用3.9或3.10以獲得最佳兼容性。包管理工具pip通常隨Python安裝。版本控制Git用于監(jiān)控代碼變更。可選IDEVS Code, PyCharm等。2.2 核心依賴庫及版本我們將創(chuàng)建一個requirements.txt文件來管理依賴。以下是核心庫及其作用# 核心框架與異步 fastapi0.104.1 uvicorn[standard]0.24.0 pydantic2.5.0 # 文件監(jiān)控與系統交互 watchfiles0.20.0 python-dotenv1.0.0 # 文本處理與加載 langchain0.0.340 langchain-community0.0.10 # 包含多種文檔加載器 unstructured0.12.0 # 用于解析多種文檔格式 # 向量數據庫與嵌入模型 chromadb0.4.18 # 輕量級向量數據庫 sentence-transformers2.2.2 # 本地運行嵌入模型 # 或者使用OpenAI嵌入需API Key # openai1.3.0 # 前端界面可選 streamlit1.28.0版本說明以上版本在撰寫時經過測試能保證基本功能運行。由于開源庫迭代迅速實際使用時若遇到兼容性問題可適當調整次要版本。重點在于理解各庫的職責和配置方式。2.3 項目結構預覽在開始前我們先規(guī)劃項目目錄這有助于理解后續(xù)的代碼組織。ai_memory_card/ ├── .env # 環(huán)境變量如API密鑰 ├── requirements.txt # 項目依賴 ├── app.py # FastAPI主應用入口 ├── config.py # 配置文件 ├── memory_core/ # 核心模塊 │ ├── __init__.py │ ├── collector.py # 數據收集器 │ ├── embedder.py # 嵌入模型管理 │ ├── vector_store.py # 向量數據庫操作 │ └── retriever.py # 檢索器 ├── sources/ # 監(jiān)控的數據源目錄示例 │ ├── code/ │ ├── notes/ │ └── logs/ ├── storage/ # 向量數據庫持久化目錄 │ └── chroma_db/ └── scripts/ # 工具腳本 └── init_memory.py # 初始化記憶庫腳本接下來我們開始搭建系統核心。3. 核心模塊拆解與原理“AI記憶卡”系統主要由四個核心模塊組成收集器Collector、嵌入器Embedder、向量存儲Vector Store和檢索器Retriever。3.1 收集器Collector自動捕獲工作上下文收集器的職責是從不同源頭抓取數據。我們采用基于事件如文件變化和基于輪詢如定時讀取Git日志的混合策略。關鍵設計文件系統監(jiān)控使用watchfiles庫監(jiān)聽sources/目錄下的文件變動增、刪、改實時觸發(fā)處理流程。Git鉤子集成在項目的.git/hooks/post-commit中注入腳本在每次提交后自動捕獲提交信息、差異代碼作為記憶片段。文檔加載器利用LangChain的UnstructuredFileLoader、TextLoader等支持解析.txt,.md,.py,.pdf等多種格式。元數據附加為每一段文本記憶片段附加來源、時間戳、類型代碼/筆記/日志等元數據便于后續(xù)篩選。3.2 嵌入器Embedder與向量存儲這是實現語義檢索的核心。我們將文本轉換為計算機能理解的數值向量。工作流程文本分塊長文檔需要被切割成大小適中的片段如500字符同時保持語義連貫。LangChain的RecursiveCharacterTextSplitter是常用工具。向量化使用嵌入模型將文本塊轉換為固定維度的向量如384維或768維。我們優(yōu)先選用本地模型如all-MiniLM-L6-v2它平衡了速度與精度且無需網絡調用和付費。向量存儲將向量及其對應的文本塊、元數據存入ChromaDB。ChromaDB 是一個輕量級、可持久化的向量數據庫支持按集合Collection組織數據非常適合個人或小團隊使用。3.3 檢索器Retriever智能關聯問題與記憶當用戶提出問題時檢索器負責找到最相關的記憶片段。檢索過程將用戶問題同樣轉換為向量。在向量數據庫中進行相似性搜索通常使用余弦相似度。返回相似度最高的前k個文本片段如前3個?；旌蠙z索除了向量檢索還可以結合元數據過濾例如只檢索“代碼”類型的記憶或最近一周的記憶使結果更精準。4. 完整實戰(zhàn)構建你的第一張“AI記憶卡”現在我們將一步步實現上述系統。請跟隨操作并注意代碼中的注釋。4.1 初始化項目與環(huán)境首先創(chuàng)建項目目錄并安裝依賴。# 1. 創(chuàng)建項目目錄 mkdir ai_memory_card cd ai_memory_card # 2. 創(chuàng)建虛擬環(huán)境推薦 python -m venv venv # Windows 激活: venv\Scripts\activate # macOS/Linux 激活: source venv/bin/activate # 3. 創(chuàng)建 requirements.txt 并寫入上一節(jié)的依賴內容 # 可以使用編輯器創(chuàng)建或使用 echo 命令注意版本號 # 4. 安裝依賴 pip install -r requirements.txt # 5. 創(chuàng)建項目結構所需目錄 mkdir -p memory_core sources/{code,notes,logs} storage/chroma_db scripts4.2 編寫核心配置文件創(chuàng)建config.py集中管理配置參數。# config.py import os from pathlib import Path from pydantic_settings import BaseSettings class Settings(BaseSettings): # 項目路徑 BASE_DIR: Path Path(__file__).parent SOURCES_DIR: Path BASE_DIR / sources STORAGE_DIR: Path BASE_DIR / storage VECTOR_DB_PATH: Path STORAGE_DIR / chroma_db # 向量數據庫配置 COLLECTION_NAME: str work_memory EMBEDDING_MODEL: str all-MiniLM-L6-v2 # 本地句子嵌入模型 # 如果使用OpenAI請取消注釋并設置API Key # OPENAI_API_KEY: str # EMBEDDING_MODEL: str text-embedding-ada-002 # 文本處理配置 CHUNK_SIZE: int 500 # 文本分塊大小 CHUNK_OVERLAP: int 50 # 塊之間重疊字符數 # 檢索配置 RETRIEVE_TOP_K: int 3 # 每次檢索返回的記憶片段數量 # 文件監(jiān)控配置 WATCH_PATTERNS: list [*.md, *.txt, *.py, *.js, *.java, *.json] class Config: env_file .env # 從.env文件加載環(huán)境變量 settings Settings()4.3 實現嵌入與向量存儲模塊創(chuàng)建memory_core/embedder.py和memory_core/vector_store.py。# memory_core/embedder.py from sentence_transformers import SentenceTransformer from langchain.embeddings import HuggingFaceEmbeddings import numpy as np from config import settings import logging logger logging.getLogger(__name__) class LocalEmbedder: 本地嵌入模型封裝 def __init__(self): model_name settings.EMBEDDING_MODEL logger.info(f正在加載嵌入模型: {model_name}) # 使用LangChain封裝的HuggingFace嵌入兼容性更好 self.embeddings HuggingFaceEmbeddings( model_namefsentence-transformers/{model_name}, model_kwargs{device: cpu}, # 有GPU可改為 cuda encode_kwargs{normalize_embeddings: True} # 歸一化便于余弦相似度計算 ) logger.info(嵌入模型加載完畢。) def embed_documents(self, texts: list[str]) - list[list[float]]: 將一批文本轉換為向量 return self.embeddings.embed_documents(texts) def embed_query(self, text: str) - list[float]: 將單個查詢文本轉換為向量 return self.embeddings.embed_query(text) # 全局嵌入器實例 embedder LocalEmbedder()# memory_core/vector_store.py import chromadb from chromadb.config import Settings as ChromaSettings from typing import List, Dict, Any from config import settings import logging from memory_core.embedder import embedder logger logging.getLogger(__name__) class VectorStoreManager: 向量數據庫管理類 def __init__(self): self.client chromadb.PersistentClient( pathstr(settings.VECTOR_DB_PATH), settingsChromaSettings(anonymized_telemetryFalse) # 禁用匿名數據收集 ) self.collection self.client.get_or_create_collection( namesettings.COLLECTION_NAME, metadata{description: AI工作記憶存儲} ) logger.info(f向量數據庫連接成功集合: {settings.COLLECTION_NAME}) def add_memories(self, documents: List[str], metadatas: List[Dict], ids: List[str]): 添加記憶片段到向量數據庫 if not documents: return # 生成嵌入向量 embeddings embedder.embed_documents(documents) # 添加到集合 self.collection.add( embeddingsembeddings, documentsdocuments, metadatasmetadatas, idsids ) logger.info(f成功添加 {len(documents)} 條記憶。) def search(self, query: str, filter_metadata: Dict None, top_k: int None) - List[Dict[str, Any]]: 檢索與查詢最相關的記憶 if top_k is None: top_k settings.RETRIEVE_TOP_K # 將查詢文本向量化 query_embedding embedder.embed_query(query) # 執(zhí)行搜索 results self.collection.query( query_embeddings[query_embedding], n_resultstop_k, wherefilter_metadata # 元數據過濾條件 ) # 格式化結果 memories [] if results[documents]: for i in range(len(results[documents][0])): memories.append({ content: results[documents][0][i], metadata: results[metadatas][0][i], distance: results[distances][0][i] # 距離越小越相似 }) return memories def list_all_collections(self): 列出所有集合用于調試 return self.client.list_collections() # 全局向量存儲管理器實例 vector_store VectorStoreManager()4.4 實現文件收集器創(chuàng)建memory_core/collector.py實現一個監(jiān)控指定目錄的簡易收集器。# memory_core/collector.py import hashlib import time from pathlib import Path from typing import List, Dict, Any from langchain.document_loaders import TextLoader, UnstructuredMarkdownLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from config import settings from memory_core.vector_store import vector_store import logging logger logging.getLogger(__name__) class FileCollector: 文件收集器 def __init__(self): self.text_splitter RecursiveCharacterTextSplitter( chunk_sizesettings.CHUNK_SIZE, chunk_overlapsettings.CHUNK_OVERLAP, length_functionlen, separators[\n\n, \n, 。, , , , , , ] ) def process_file(self, file_path: Path) - List[Dict[str, Any]]: 處理單個文件返回文本塊和元數據列表 memories [] try: # 根據后綴選擇加載器 if file_path.suffix.lower() in [.txt, .md, .py, .js, .java, .json]: if file_path.suffix .md: loader UnstructuredMarkdownLoader(str(file_path)) else: loader TextLoader(str(file_path), encodingutf-8) documents loader.load() for doc in documents: # 分割文本 chunks self.text_splitter.split_text(doc.page_content) for i, chunk in enumerate(chunks): if not chunk.strip(): continue # 為每個塊生成唯一ID文件路徑內容哈希 chunk_id f{file_path.stem}_{i}_{hashlib.md5(chunk.encode()).hexdigest()[:8]} # 構建元數據 metadata { source: str(file_path.relative_to(settings.BASE_DIR)), type: self._get_file_type(file_path), timestamp: time.time(), chunk_index: i } memories.append({ id: chunk_id, content: chunk, metadata: metadata }) logger.info(f處理文件 {file_path.name}生成 {len(chunks)} 個文本塊。) else: logger.warning(f暫不支持的文件格式: {file_path.suffix}) except Exception as e: logger.error(f處理文件 {file_path} 時出錯: {e}) return memories def _get_file_type(self, file_path: Path) - str: 根據文件后綴判斷類型 suffix file_path.suffix.lower() if suffix in [.py, .js, .java, .cpp, .go]: return code elif suffix in [.md, .txt]: return note elif suffix in [.log, .err]: return log else: return other def process_directory(self, directory: Path) - int: 處理整個目錄并存入向量數據庫 all_memories [] if not directory.exists(): logger.warning(f目錄不存在: {directory}) return 0 # 遞歸查找支持的文件 for pattern in settings.WATCH_PATTERNS: for file_path in directory.rglob(pattern): if file_path.is_file(): memories self.process_file(file_path) all_memories.extend(memories) # 批量添加到向量數據庫 if all_memories: documents [m[content] for m in all_memories] metadatas [m[metadata] for m in all_memories] ids [m[id] for m in all_memories] vector_store.add_memories(documents, metadatas, ids) return len(all_memories) # 全局收集器實例 collector FileCollector()4.5 實現檢索器與API接口創(chuàng)建memory_core/retriever.py和app.py提供檢索API。# memory_core/retriever.py from typing import List, Dict, Any from config import settings from memory_core.vector_store import vector_store import logging logger logging.getLogger(__name__) class MemoryRetriever: 記憶檢索器 def retrieve(self, query: str, source_filter: str None, type_filter: str None) - List[Dict[str, Any]]: 根據查詢檢索相關記憶。 Args: query: 查詢文本 source_filter: 按來源過濾如 sources/notes/xxx.md type_filter: 按類型過濾如 code, note, log Returns: 相關記憶列表按相關性排序 # 構建元數據過濾條件 filter_metadata {} if source_filter: filter_metadata[source] {$contains: source_filter} if type_filter: filter_metadata[type] type_filter logger.info(f檢索查詢: {query}, 過濾器: {filter_metadata}) memories vector_store.search(query, filter_metadatafilter_metadata if filter_metadata else None) # 格式化輸出 formatted_results [] for mem in memories: formatted_results.append({ content: mem[content][:200] ... if len(mem[content]) 200 else mem[content], source: mem[metadata].get(source, unknown), type: mem[metadata].get(type, unknown), relevance_score: round(1 - mem[distance], 4) # 將距離轉換為相似度分數 }) return formatted_results def get_context_for_ai(self, query: str, max_chars: int 1500) - str: 為AI對話生成上下文提示。 將檢索到的記憶片段拼接成一段連貫的上下文。 memories self.retrieve(query) if not memories: return 暫無相關歷史上下文。\n context_parts [以下是你之前的相關工作記錄供參考\n] total_chars 0 for i, mem in enumerate(memories, 1): mem_text f[{i}] 來源{mem[source]} (類型{mem[type]}, 相關度{mem[relevance_score]:.2%})\n{mem[content]}\n\n if total_chars len(mem_text) max_chars: break context_parts.append(mem_text) total_chars len(mem_text) context_parts.append(f\n--- 以上是基于你工作記憶的 {len(context_parts)-1} 條相關上下文 ---\n) return .join(context_parts) retriever MemoryRetriever()# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import Optional, List import uvicorn import logging from memory_core.retriever import retriever from memory_core.collector import collector from config import settings # 配置日志 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) app FastAPI(titleAI記憶卡 API, description自動管理工作上下文并與AI集成的服務) class SearchRequest(BaseModel): query: str source_filter: Optional[str] None type_filter: Optional[str] None class SearchResponse(BaseModel): query: str memories: List[dict] count: int class IndexRequest(BaseModel): path: str # 相對于sources目錄的路徑或絕對路徑 app.get(/) async def root(): return {message: AI記憶卡服務運行中, version: 1.0.0} app.post(/search, response_modelSearchResponse) async def search_memories(request: SearchRequest): 檢索相關記憶 try: memories retriever.retrieve( queryrequest.query, source_filterrequest.source_filter, type_filterrequest.type_filter ) return SearchResponse( queryrequest.query, memoriesmemories, countlen(memories) ) except Exception as e: logger.error(f檢索失敗: {e}) raise HTTPException(status_code500, detailf檢索失敗: {str(e)}) app.post(/index) async def index_directory(request: IndexRequest): 手動索引一個目錄或文件 import os from pathlib import Path target_path Path(request.path) if not target_path.is_absolute(): target_path settings.BASE_DIR / target_path if not target_path.exists(): raise HTTPException(status_code404, detailf路徑不存在: {target_path}) try: if target_path.is_file(): # 索引單個文件 memories collector.process_file(target_path) if memories: documents [m[content] for m in memories] metadatas [m[metadata] for m in memories] ids [m[id] for m in memories] from memory_core.vector_store import vector_store vector_store.add_memories(documents, metadatas, ids) count len(memories) else: count 0 msg f文件已索引 else: # 索引目錄 count collector.process_directory(target_path) msg f目錄已索引 return {message: f{msg}新增 {count} 條記憶。} except Exception as e: logger.error(f索引失敗: {e}) raise HTTPException(status_code500, detailf索引失敗: {str(e)}) app.get(/generate-context) async def generate_context(query: str, max_chars: int 1500): 生成用于AI提示的上下文文本 try: context retriever.get_context_for_ai(query, max_chars) return {query: query, context: context} except Exception as e: logger.error(f生成上下文失敗: {e}) raise HTTPException(status_code500, detailf生成上下文失敗: {str(e)}) if __name__ __main__: logger.info(啟動AI記憶卡服務...) uvicorn.run(app, host0.0.0.0, port8000)4.6 運行與驗證現在讓我們啟動服務并進行測試。步驟1啟動API服務# 在項目根目錄下執(zhí)行 python app.py看到日志INFO: Uvicorn running on http://0.0.0.0:8000表示啟動成功。步驟2準備示例數據在sources/notes/目錄下創(chuàng)建一個筆記文件project_plan.md。# 項目計劃個人任務管理系統 **目標**開發(fā)一個CLI工具管理每日任務。 **技術棧**Python, Typer, SQLite。 **核心功能** 1. 添加任務addtaskman add “寫周報” -p high 2. 列出任務list按優(yōu)先級排序。 3. 完成任務done標記任務狀態(tài)。 **當前進展**已完成數據庫模型設計正在開發(fā)add命令。 **遇到的問題**Typer的回調函數中如何共享數據庫連接步驟3手動索引數據使用curl或瀏覽器訪問API端點索引我們剛創(chuàng)建的筆記目錄。# 使用curl命令 curl -X POST http://localhost:8000/index \ -H Content-Type: application/json \ -d {path: sources/notes} # 預期返回 # {message:目錄已索引新增 X 條記憶。}步驟4檢索記憶現在我們可以模擬一個開發(fā)問題看看系統能否找到相關記憶。curl -X POST http://localhost:8000/search \ -H Content-Type: application/json \ -d {query: Typer回調函數里怎么共享數據庫連接, type_filter: note} # 預期返回簡化 # { # query: ..., # memories: [ # { # content: **遇到的問題**Typer的回調函數中如何共享數據庫連接..., # source: sources/notes/project_plan.md, # type: note, # relevance_score: 0.92 # }, # ...其他相關片段 # ], # count: 2 # }步驟5生成AI對話上下文這是最關鍵的一步獲取格式化后的上下文以便粘貼給AI助手。curl http://localhost:8000/generate-context?queryTyper共享數據庫連接max_chars1000返回的context字段內容可以直接作為提示詞前綴發(fā)給ChatGPT等AI例如以下是你之前的相關工作記錄供參考 [1] 來源sources/notes/project_plan.md (類型note, 相關度92.00%) **遇到的問題**Typer的回調函數中如何共享數據庫連接 --- 以上是基于你工作記憶的 1 條相關上下文 --- 我的問題是Typer共享數據庫連接5. 自動化集成與高級用法基礎系統搭建完成后我們可以讓它更自動化、更智能。5.1 實現文件監(jiān)控與自動索引創(chuàng)建scripts/watch_and_index.py實現后臺自動監(jiān)控。# scripts/watch_and_index.py import time from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler from pathlib import Path from memory_core.collector import collector from config import settings import logging logger logging.getLogger(__name__) class SourceFileHandler(FileSystemEventHandler): 處理文件系統事件 def on_modified(self, event): if not event.is_directory: self._process_event(event) def on_created(self, event): if not event.is_directory: self._process_event(event) def _process_event(self, event): file_path Path(event.src_path) logger.info(f檢測到文件變動: {file_path}) # 避免頻繁觸發(fā)可加入防抖邏輯 time.sleep(0.5) # 簡單防抖 try: memories collector.process_file(file_path) if memories: logger.info(f自動索引文件: {file_path.name}, 新增 {len(memories)} 個片段。) except Exception as e: logger.error(f自動索引失敗: {e}) def start_watching(): 啟動文件監(jiān)控 event_handler SourceFileHandler() observer Observer() observer.schedule(event_handler, str(settings.SOURCES_DIR), recursiveTrue) observer.start() logger.info(f開始監(jiān)控目錄: {settings.SOURCES_DIR}) try: while True: time.sleep(1) except KeyboardInterrupt: observer.stop() observer.join() if __name__ __main__: start_watching()5.2 集成到AI聊天工具瀏覽器擴展思路完全自動化需要與AI界面深度集成。一個可行的方案是開發(fā)一個瀏覽器擴展如Chrome Extension。擴展核心邏輯content script監(jiān)聽ChatGPT等網頁的輸入框。當用戶開始輸入時提取輸入框中的關鍵詞或句子。向本地http://localhost:8000/generate-context發(fā)送請求獲取相關上下文。將返回的上下文自動插入到輸入框的最前面。由于實現瀏覽器擴展涉及特定API這里提供概念性偽代碼// 偽代碼Chrome擴展內容腳本概念 async function enhanceAIInput() { const inputBox document.querySelector(textarea[aria-label*message]); // 根據實際網頁調整選擇器 if (!inputBox) return; inputBox.addEventListener(input, _.debounce(async (e) { const query e.target.value; if (query.length 5) return; // 輸入過短時不查詢 try { const resp await fetch(http://localhost:8000/generate-context?query${encodeURIComponent(query)}); const data await resp.json(); if (data.context data.context.includes(相關上下文)) { // 將上下文智能地添加到輸入內容前 const enhancedPrompt data.context \n\n query; // 注意直接設置value會觸發(fā)循環(huán)需要巧妙處理 // 一種方法是提供一個“添加上下文”的按鈕 } } catch (err) { console.error(獲取記憶上下文失敗:, err); } }, 500)); // 防抖500毫秒 }5.3 與Git集成捕獲代碼上下文創(chuàng)建.git/hooks/post-commit鉤子需賦予可執(zhí)行權限在每次提交后自動記錄。#!/bin/bash # .git/hooks/post-commit REPO_ROOT$(git rev-parse --show-toplevel) HOOKS_DIR$REPO_ROOT/.git/hooks MEMORY_CARD_DIR$REPO_ROOT/../ai_memory_card # 假設記憶卡項目在倉庫同級目錄 # 獲取本次提交信息 COMMIT_MSG$(git log -1 --pretty%B) LAST_COMMIT_HASH$(git rev-parse HEAD) AUTHOR$(git log -1 --prettyformat:%an) # 構建記憶文本 MEMORY_CONTENTGit提交$LAST_COMMIT_HASH 作者$AUTHOR 信息$COMMIT_MSG # 調用記憶卡API進行記錄 curl -X POST http://localhost:8000/index \ -H Content-Type: application/json \ -d {\path\: \$REPO_ROOT\} \ --max-time 2 /dev/null 21 echo [AI記憶卡] 已嘗試記錄本次提交上下文。6. 常見問題與排查思路在搭建和使用過程中你可能會遇到以下問題。問題現象可能原因解決思路啟動app.py時報ImportError依賴未安裝或虛擬環(huán)境未激活1. 確認已激活虛擬環(huán)境。2. 運行pip install -r requirements.txt。訪問http://localhost:8000無響應服務未啟動或端口被占用1. 檢查python app.py是否運行。2. 使用netstat -ano | findstr :8000(Win) 或lsof -i:8000(Mac/Linux) 查看端口占用并終止沖突進程。文件監(jiān)控腳本不觸發(fā)文件路徑不正確或事件未捕獲1. 確認sources/目錄下有文件。2. 檢查watchdog庫是否安裝正確。3. 嘗試手動修改一個文件看日志輸出。檢索結果不相關嵌入模型不適合或文本分塊過大1. 嘗試更換嵌入模型如paraphrase-multilingual-MiniLM-L12-v2支持中文。2. 調整config.py中的CHUNK_SIZE如改為300和CHUNK_OVERLAP。3. 檢查查詢語句是否足夠明確。向量數據庫報錯Collection not found數據庫路徑損壞或版本不兼容1. 刪除storage/chroma_db目錄重啟服務會重建。2. 檢查 ChromaDB 版本嘗試降級到穩(wěn)定版如pip install chromadb0.4.15。處理中文文本亂碼或錯誤文件編碼問題1. 確保源代碼文件保存為 UTF-8 編碼。2. 在TextLoader中明確指定encodingutf-8。內存占用過高嵌入模型加載或文件過大1. 對于大型文檔先進行預處理和過濾。2. 考慮使用更輕量的嵌入模型。3. 定期清理不重要的記憶片段可通過API擴展刪除功能。7. 最佳實踐與工程建議將“AI記憶卡”投入日常使用以下建議能幫助你獲得更好體驗并避免陷阱。7.1 數據源管理分級分類在sources/下建立清晰的子目錄如sources/project_a/code/,sources/project_b/docs/。通過元數據type和source進行高效過濾。敏感信息過濾切勿將包含密碼、密鑰、個人隱私信息的文件放入監(jiān)控目錄。可通過在collector.py的process_file方法中添加關鍵詞過濾邏輯。文件類型限制只監(jiān)控你真正關心的文件類型在config.py的WATCH_PATTERNS中配置避免處理二進制文件如圖片、視頻產生無意義內容。7.2 性能與可維護性增量索引當前示例是全量處理目錄。生產環(huán)境應記錄已索引文件的哈希值實現增量更新避免重復計算嵌入向量。批量操作向量數據庫的add操作應批量進行而不是單條插入以提高效率。定期清理設計一個簡單的TTL生存時間機制或手動審核界面定期清理過時、無效的記憶片段控制數據庫大小。日志記錄為關鍵操作如文件處理、向量添加、檢索查詢添加詳細日志便于后期調試和審計。7.3 提示詞工程優(yōu)化上下文格式化get_context_for_ai方法生成的上下文格式直接影響AI的理解?？梢詢?yōu)化模板使其更符合特定AI助手的提示風格。例如為ChatGPT設計專用模板。相關性閾值在retriever.py中可以為檢索結果設置一個相似度分數閾值如relevance_score 0.7則丟棄避免注入不相關的低質量上下文。元數據利用在構建最終提示時除了內容還可以強調來源和時間如“這是你昨天寫的關于XXX的代碼”幫助AI更好地理解上下文的新舊和重要性。7.4 安全邊界本地化部署本文方案的核心優(yōu)勢是數據完全本地化。嵌入模型、向量數據庫均在本地運行確保了工作隱私的安全。網絡訪問控制app.py默認監(jiān)聽0.0.0.0:8000。如果僅在本地使用可改為127.0.0.1:8000避免局域網內其他設備訪問。輸入驗證API接口如/index應對傳入的路徑參數進行嚴格校驗防止目錄遍歷攻擊Path Traversal。7.5 擴展方向支持更多數據源除了文件系統可以擴展收集器以支持從Notion、飛書文檔、Jira Issue、Slack頻道等平臺同步數據。集成更多AI工具除了Web端可以開發(fā)VS Code插件、Obsidian插件在編碼環(huán)境和筆記軟件內直接調用記憶上下文。實現記憶“對話”引入輕量級LLM如通過Ollama運行本地模型對檢索到的記憶進行總結、關聯分析而不僅僅是簡單羅列。這套“AI記憶卡”系統將一個理想化的概念變成了可運行的代碼。它可能不是最完美的但提供了一個堅實、可擴展的起點。你可以從今天開始先將sources/notes目錄用于記錄工作日志和問題體驗上下文自動關聯帶來的效率提升。然后逐步將代碼庫、項目文檔納入監(jiān)控范圍。隨著記憶庫的豐富你會發(fā)現向AI提問前不再需要費力組織背景信息它仿佛真的成為了你項目團隊中的一員始終記得之前的每一次討論和決策。技術的價值在于解決真實世界的摩擦希望這個項目能成為你高效工作的得力助手。