Memory Learning Agent

记忆型 AI 学习助手。用户可以通过自然语言记录学习进度、查询薄弱点、获取复习建议；后端用 LangGraph 编排对话规划、记忆检索、记忆评估、分层写入、使用强化和清理归档。

Tech Stack

Frontend: Vite + React + TypeScript + Tailwind CSS
Backend: FastAPI + Python + LangGraph
Memory Store: SQLite primary storage + SQLite FTS5 BM25
Retrieval: jieba tokenization + BM25 + Alibaba-compatible vector recall + RRF reranking
Embedding: Alibaba DashScope / OpenAI-compatible embedding API
Observability: optional Langfuse observations for agent planning, memory search, writes, embedding indexing, and cleanup

Run

Backend:

cd backend
$env:PYTHONPATH='.'
uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

Model Config

Local configuration lives in:

backend/.env

Use backend/.env.example as the template. If the chat model variables are not set, the backend uses a fake local model for development.

$env:AI_BASE_URL='https://ark.cn-beijing.volces.com/api/v3'
$env:AI_API_KEY='your-api-key'
$env:AI_MODEL='your-model-name'

Embedding Config

Embedding is optional. If embedding is unavailable, retrieval degrades to BM25-only. When embedding variables are configured, new profile, note, and conversation memories are embedded automatically after they are written. core memory is still injected directly into context and is not indexed for BM25/vector search.

$env:EMBEDDING_BASE_URL='your-alibaba-openai-compatible-base-url'
$env:EMBEDDING_API_KEY='your-api-key'
$env:EMBEDDING_MODEL='text-embedding-v4'

Do not write real API keys into source code, tests, docs, or logs.

Langfuse Config

Langfuse is optional. If any variable is missing, tracing is disabled. When configured, the backend emits observations for the main agent steps and stores retrieval metadata such as rewritten query, sources, recalled memory ids, upsert result, and embedding-index result.

$env:LANGFUSE_PUBLIC_KEY='your-public-key'
$env:LANGFUSE_SECRET_KEY='your-secret-key'
$env:LANGFUSE_BASE_URL='https://cloud.langfuse.com'

Memory Architecture

core: stable long-term facts, injected into every turn.
profile: structured learning state such as goals, progress, weaknesses.
note: detailed archival memory.
conversation: completed user + assistant turns, searchable with low source weight.
archive: excluded from default retrieval.

SQLite database:

.memory/memory.db

Legacy .memory/*.json files are no longer the source of truth.

Eval Harness

Run the local memory retrieval harness:

cd backend
$env:PYTHONPATH='.'
python -m app.evals.runner --cases evals/cases/memory_retrieval.jsonl

The harness prints local JSON metrics such as Recall@K and MRR. Langfuse score export can be added on top of the same runner.

smf-h/memory-learning-agent

README