Turn scattered notes, ideas, and conversations into a private second brain that retrieves, reasons, creates, and remembers you.

Most note-taking tools stop at storing: search is keyword-based and connecting ideas is left entirely to your brain. I wanted a knowledge base that actually thinks: you type one sentence in natural language, and a Coordinator Agent routes it to the right sub-agent — knowledge-graph Q&A, proactive recommendations, idea generation, long-form synthesis, or document ingestion — while continuously learning long-term memory about you.

The whole project is built for "does it actually work well", as a full-stack app (FastAPI + React), using China-based cloud services throughout (DeepSeek-V3 / SiliconFlow bge-m3).

Full design and phased implementation details are in SecondBrain_Execution_Report.md.

• Multi-agent orchestration: one chat entry point; the LLM routes intent to Q&A / recommend / ideate / synthesize / ingest capabilities.
• GraphRAG hybrid Q&A: vector retrieval + multi-hop knowledge-graph traversal, answers with [n] citations, falling back to general knowledge when the knowledge base is insufficient.
• Multi-format ingestion: PDF / DOCX / TXT / Markdown / web pages / plain text → information cards → embeddings + entity/relation extraction into the graph.
• Two-layer long-term memory: semantic memory (vector recall, contradiction resolution, capacity-based forgetting) + Zep-style graph memory (temporal triples merged into the knowledge graph).
• MCP tool calling: the Coordinator Agent can invoke external tools (e.g. fetch a web page / go online), breaking past the "knowledge-base only" boundary.

Tech stack: FastAPI · SQLAlchemy 2.0 · LangGraph · PostgreSQL + pgvector · Neo4j · MinIO · Vite + React + TypeScript · DeepSeek-V3 + SiliconFlow bge-m3.

For day-to-day start/restart and troubleshooting, see OPERATIONS.md.

docker compose up -d        # PostgreSQL + Neo4j + MinIO
docker ps                   # confirm all three containers are Up

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev,llm]"

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,llm]"

Copy the example and fill in your API keys (use copy on Windows, cp on macOS/Linux):

copy .env.example .env      # macOS/Linux: cp .env.example .env

Key settings:

LLM_PROVIDER=openai
LLM_API_KEY=<DeepSeek Key>     LLM_BASE_URL=https://api.deepseek.com     LLM_MODEL=deepseek-chat
EMBEDDING_PROVIDER=openai
EMBEDDING_API_KEY=<SiliconFlow Key> EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1 EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_DIM=1024  EMBEDDING_DIMENSIONS=0
MEMORY_GRAPH_ENABLED=true      # Zep graph-memory switch (restart backend after changing)

.venv\Scripts\python.exe -m uvicorn apps.api.main:app --reload

On macOS/Linux replace .venv\Scripts\python.exe with .venv/bin/python.

cd apps\web
npm install
npm run dev

Open http://localhost:5173 — the Coordinator Agent is at the top of the page. You can also run the backend only and open http://127.0.0.1:8000/docs for the API docs.

pip install -e ".[mcp]"        # install MCP SDK + local fetch server
# .env: MCP_ENABLED=true        # switch (default false); restart backend after changing

Mounted tools are declared in mcp.json at the repo root (it ships with a pure-Python fetch web-fetch tool). Once enabled, tell the Coordinator Agent something like "fetch https://… and take a look" to trigger it.

.venv\Scripts\python.exe -m pytest tests/unit          # unit tests (offline)
.venv\Scripts\python.exe -m pytest tests/integration   # integration tests (needs PostgreSQL)

.venv\Scripts\python.exe scripts\check_providers.py       # LLM / Embedding connectivity self-check
.venv\Scripts\python.exe scripts\verify_memory_graph.py   # graph memory: write / invalidate / merged recall
.venv\Scripts\python.exe scripts\verify_mcp.py            # MCP tool calling end-to-end

• Best-effort throughout: when Neo4j is unavailable, graph / graph-memory writes are skipped with a warning, and the core Q&A flow is unaffected.
• This is a personal project; it does not include full authentication / multi-tenancy or production-grade security hardening, focusing instead on features and experience.

Released under the MIT License. Replace the copyright holder in the LICENSE file with your own name / GitHub username.