docs: update CLAUDE.md and resolve README merge conflicts (Step 1)
Bring repo docs in line with the Graphiti+Neo4j migration and prepare the codebase for Spec-Driven Development. CLAUDE.md: - Promote Neo4j + Graphiti to primary memory/graph layer; mark Zep Cloud as deprecated / compat-only. - Document the full env-var surface: NEO4J_*, EMBEDDING_MODEL, optional LLM_BOOST_* block. - Codify must-respect implementation rules (Task model for long ops, reasoning-output stripping, simulation IPC, subprocess cleanup, startup recovery, per-project group_id isolation, chat prefix injection). - Note i18n (vue-i18n + /locales/) and Docker prerequisite for dev. README.md / README-EN.md / README-ZH.md: - Resolve unresolved merge-conflict markers in README.md left over from the feat/graphiti-neo4j-migration merge (file was broken Markdown). - Lead with Docker as the recommended deployment path; keep source install as a documented alternative. - Replace Zep env vars with NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD / EMBEDDING_MODEL across all three READMEs. - Add optional LLM_BOOST_* block with omit-if-unused note. - Fix language-switcher links between the three READMEs. .claude/onboarding/step1_codebase/: - Document repo analysis, CLAUDE.md conventions decisions, and README resolution choices.
This commit is contained in:
Dominik Seemann
parent
44eb4588bf
commit
9a77b5921d
|
|
@ -0,0 +1,49 @@
|
|||
# Step 1 — Repo Analysis (Brownfield)
|
||||
|
||||
## Project: MiroFish
|
||||
Multi-Agent Swarm Intelligence Prediction Engine.
|
||||
|
||||
## Date: 2026-05-06
|
||||
|
||||
## Findings
|
||||
|
||||
### Top-level Structure
|
||||
```
|
||||
MiroFish/
|
||||
├── .claude/ # Claude Code config (Step 0 set up)
|
||||
├── .codegraph/ # local index, gitignored
|
||||
├── .github/workflows/ # CI
|
||||
├── backend/ # Python (Flask, uv)
|
||||
│ ├── app/{api,services,models,utils,config}
|
||||
│ ├── pyproject.toml, requirements.txt, run.py, uv.lock
|
||||
│ └── scripts/
|
||||
├── frontend/ # Vue 3 + Vite
|
||||
│ ├── src/{api,components,views,router,store,i18n,assets}
|
||||
│ ├── package.json, vite.config.js, index.html
|
||||
│ └── public/
|
||||
├── locales/, static/
|
||||
├── package.json # root orchestrator (concurrent dev)
|
||||
├── docker-compose.yml, Dockerfile
|
||||
├── README.md, README-EN.md, README-ZH.md
|
||||
├── CLAUDE.md
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
### Decisions
|
||||
|
||||
| Question | Decision |
|
||||
|----------|----------|
|
||||
| Q1 — Structure changes? | **No changes**. Existing layout is intentional and aligns with the layer-based convention from the Salestech Dev Guidelines. |
|
||||
| Q2 — Create `docs/`? | **No**. Documentation stays in `README*.md`, `CLAUDE.md`, and `.claude/onboarding/`. |
|
||||
| Q3 — Keep `.claude/`? | **Yes, keep as-is** (configured during Step 0). |
|
||||
| Q4 — `.gitignore` additions? | **No further changes**. Step 0 already updated `.gitignore` to track project-level `.claude/` and ignore `settings.local.json` and `.codegraph/`. |
|
||||
| Q5 — Trilingual README? | **Keep** the three READMEs (`README.md` = English default, `README-EN.md` = explicit EN, `README-ZH.md` = Chinese). |
|
||||
|
||||
### Already Configured (from Step 0)
|
||||
- `.claude/settings.json` — permissions (allow safe bash, deny secrets / destructive cmds)
|
||||
- `.claude/rules/` — markdown, file-paths, commits, error-handling, dev-guidelines
|
||||
- `.gitignore` — tracks project-level `.claude/`, ignores `settings.local.json` + `.codegraph/`
|
||||
|
||||
## Next
|
||||
- **PROMPT 2:** Review / update `CLAUDE.md` (tech stack, conventions, architecture, commands).
|
||||
- **PROMPT 3:** Review / update `README.md` (prerequisites, env vars, install).
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
# Step 1 — CLAUDE.md Conventions Decisions
|
||||
|
||||
Decisions made while updating `CLAUDE.md` (Step 1, PROMPT 2).
|
||||
|
||||
## Date: 2026-05-06
|
||||
|
||||
## Drivers
|
||||
The recent merge `feat/graphiti-neo4j-migration` (commit `6264828`)
|
||||
replaced Zep Cloud with **Neo4j + Graphiti** as the primary
|
||||
knowledge-graph store. The previous CLAUDE.md was out of date.
|
||||
|
||||
## Section-by-Section Decisions
|
||||
|
||||
### Tech Stack
|
||||
- **Memory/Graph (UPDATED):** Primary = **Neo4j + Graphiti** (`graphiti-core>=0.3`).
|
||||
Zep Cloud is now legacy / kept for backwards compatibility only. Code
|
||||
files still named `zep_*` are historical artefacts; the underlying
|
||||
store is Neo4j.
|
||||
- **Versions added:** Vue 3.5, Vite 7, axios 1.14, vue-router 4.6,
|
||||
vue-i18n 11, D3 7, camel-oasis 0.2.5, camel-ai 0.2.78.
|
||||
- **i18n:** Documented `vue-i18n` + `/locales/{en,zh,languages}.json`.
|
||||
|
||||
### Required Environment Variables
|
||||
Updated to reflect `app/config.py`:
|
||||
- Added: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, `EMBEDDING_MODEL`.
|
||||
- Added: optional `LLM_BOOST_*` block (omit entirely if unused).
|
||||
- Marked `ZEP_API_KEY` as deprecated/compat (empty string OK).
|
||||
|
||||
### Conventions (per user direction)
|
||||
- **Follow the conventions already established in this project.**
|
||||
- Don't impose external style guides on existing code.
|
||||
- 4-space indent, snake_case in Python; comments/docstrings mix English
|
||||
and Chinese — both styles must continue to work.
|
||||
- No enforced formatter or linter — match the surrounding file.
|
||||
- New tooling decisions (Ruff, Prettier, etc.) require discussion before
|
||||
adoption.
|
||||
|
||||
### Architecture — Must-Respect Rules
|
||||
Confirmed all architectural patterns drawn from the actual code:
|
||||
1. Background tasks via `Task` model (status + progress polling).
|
||||
2. Reasoning-model output stripping (`<think>` tags, code fences).
|
||||
3. Simulation IPC via `simulation_ipc.py`.
|
||||
4. Subprocess cleanup via `SimulationRunner.register_cleanup()`.
|
||||
5. Startup recovery via `_recover_stuck_projects()`.
|
||||
6. Per-project graph isolation via `group_id` (Neo4j-specific).
|
||||
7. Chat prefix injection to suppress tool calls in user-visible
|
||||
responses.
|
||||
|
||||
### Commands
|
||||
- Added a note that `npm run dev` requires Neo4j running.
|
||||
- Added a note that no lint/format command is configured.
|
||||
- Clarified that pytest currently has only one script-style test
|
||||
(`backend/scripts/test_profile_format.py`).
|
||||
|
||||
## What's Now in CLAUDE.md
|
||||
- Project overview (unchanged).
|
||||
- Commands (with Neo4j prerequisite note + lint disclaimer).
|
||||
- Tech stack (Neo4j+Graphiti primary, Zep deprecated, full versions).
|
||||
- Required env vars (Neo4j block, optional boost block, deprecated zep).
|
||||
- 5-step pipeline (rephrased to mention Graphiti+Neo4j).
|
||||
- Backend / frontend structure (added i18n, locale, logger to utils).
|
||||
- Key implementation conventions (the seven must-respect rules).
|
||||
- Coding conventions (project-internal, no external imposition).
|
||||
|
||||
## Next
|
||||
- **PROMPT 3:** Review / update `README.md`.
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# Step 1 — README Decisions
|
||||
|
||||
Decisions made while reviewing / repairing the READMEs (Step 1, PROMPT 3).
|
||||
|
||||
## Date: 2026-05-06
|
||||
|
||||
## Critical Finding
|
||||
`README.md` contained **unresolved git merge conflict markers**
|
||||
(`<<<<<<< HEAD` / `=======` / `>>>>>>>`) at two locations: the
|
||||
prerequisites table and the env-vars block. These were left over from
|
||||
the recent `feat/graphiti-neo4j-migration` merge (commit `6264828`) and
|
||||
needed to be resolved as part of Step 1.
|
||||
|
||||
`README-EN.md` and `README-ZH.md` did **not** have markers but the ZH
|
||||
file still referenced Zep Cloud (out of date).
|
||||
|
||||
## Decisions
|
||||
|
||||
| Question | Decision |
|
||||
|----------|----------|
|
||||
| Q1 — Resolve conflicts? | **Take Neo4j-branch content** (Neo4j prerequisite + Neo4j env vars). Zep references removed. |
|
||||
| Q2 — Prerequisites refinement? | **Out of scope for now.** Kept Neo4j install instructions as-is, will be revisited separately. |
|
||||
| Q3 — Add `LLM_BOOST_*` to README env vars? | **Yes.** Added as an optional block with a note to omit entirely if not used (matches `.env.example`). |
|
||||
| Q4 — Installation flow? | **Always assume Docker.** Reordered: Docker is now Option 1 (Recommended); Source is Option 2. |
|
||||
| Q5 — Sync three READMEs? | **Yes.** All three updated to reflect Neo4j and Docker-first install. |
|
||||
|
||||
## What Changed
|
||||
|
||||
### `README.md` (English default)
|
||||
- Resolved both merge conflict regions (prerequisites + env vars).
|
||||
- Reordered: **Docker first** (Option 1, recommended), Source second
|
||||
(Option 2).
|
||||
- Added `LLM_BOOST_*` optional env-var block with omit-if-unused note.
|
||||
- Removed the redundant note at end of source-deploy block.
|
||||
|
||||
### `README-EN.md` (explicit English)
|
||||
- Fixed language switcher: was `[English](./README-EN.md) | [中文文档](./README.md)` — now points to the correct files (`README.md` is English, `README-ZH.md` is Chinese).
|
||||
- Reordered Docker-first / Source-second to match `README.md`.
|
||||
- Added `LLM_BOOST_*` optional block.
|
||||
|
||||
### `README-ZH.md` (Chinese)
|
||||
- Removed Zep Cloud env-var section.
|
||||
- Added Neo4j prerequisite row + install instructions (translated).
|
||||
- Added `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` /
|
||||
`EMBEDDING_MODEL` env-var block (translated).
|
||||
- Reordered Docker-first / Source-second to match `README.md`.
|
||||
- Added `LLM_BOOST_*` optional block (translated).
|
||||
- Added the migration note (Zep → Graphiti + Neo4j) in Chinese.
|
||||
|
||||
## Verification
|
||||
- `grep` for `<<<<<<<` / `>>>>>>>` / `=======` across all three READMEs
|
||||
and `CLAUDE.md` returned no matches.
|
||||
- All three files are valid Markdown.
|
||||
- Language-switcher links between the three files are now consistent.
|
||||
|
||||
## Step 1 — Complete
|
||||
Outputs:
|
||||
- `.claude/onboarding/step1_codebase/01_repo_analysis.md`
|
||||
- `.claude/onboarding/step1_codebase/02_conventions.md`
|
||||
- `.claude/onboarding/step1_codebase/03_readme_decisions.md`
|
||||
|
||||
Updated files:
|
||||
- `CLAUDE.md` (Neo4j+Graphiti primary, Zep deprecated, full env vars,
|
||||
must-respect rules, project-internal coding conventions).
|
||||
- `README.md` / `README-EN.md` / `README-ZH.md` (Docker-first flow,
|
||||
Neo4j env vars, optional LLM_BOOST, language-switcher fixed).
|
||||
|
||||
## Next
|
||||
- Step 2: Claude Setup (settings.json, hooks, permissions)
|
||||
85
CLAUDE.md
85
CLAUDE.md
|
|
@ -22,6 +22,10 @@ npm run backend # Backend only: Flask on port 5001
|
|||
npm run frontend # Frontend only: Vite on port 3000
|
||||
```
|
||||
|
||||
> **Prerequisite:** Neo4j must be running (default `bolt://localhost:7687`).
|
||||
> The Graphiti-based knowledge graph requires it. Use `docker-compose up`
|
||||
> for the full stack including Neo4j.
|
||||
|
||||
### Build
|
||||
```bash
|
||||
npm run build # Build frontend (Vite)
|
||||
|
|
@ -30,7 +34,7 @@ npm run build # Build frontend (Vite)
|
|||
### Backend (Python)
|
||||
```bash
|
||||
cd backend && uv run python run.py # Start Flask server
|
||||
cd backend && uv run python -m pytest # Run tests (if any)
|
||||
cd backend && uv run python -m pytest # Run tests (currently scripts/test_profile_format.py only)
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
|
@ -38,39 +42,59 @@ cd backend && uv run python -m pytest # Run tests (if any)
|
|||
docker-compose up # Full stack via Docker
|
||||
```
|
||||
|
||||
> **Lint/format:** No linter or formatter is configured in this project.
|
||||
> Match the existing style of the file you're editing.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Stack
|
||||
- **Backend**: Python ≥3.11 Flask 3.0, managed by `uv`
|
||||
- **Frontend**: Vue 3 + Vite, port 3000; proxies `/api` → port 5001
|
||||
- **LLM**: OpenAI SDK-compatible (default: Qwen via `dashscope`; also works with GLM, OpenAI)
|
||||
- **Memory/Graph**: Zep Cloud (knowledge graph for entity storage and retrieval)
|
||||
- **Simulation**: CAMEL-OASIS (multi-agent Twitter + Reddit simulation)
|
||||
- **Visualization**: D3.js
|
||||
- **Backend**: Python ≥3.11, Flask 3.0, managed by `uv`
|
||||
- **Frontend**: Vue 3.5 + Vite 7, port 3000; proxies `/api` → port 5001
|
||||
- **LLM**: OpenAI SDK-compatible (default: Qwen via `dashscope`; also works with GLM, OpenAI, Gemini)
|
||||
- **Memory/Graph**: **Neo4j + Graphiti** (`graphiti-core>=0.3`) — primary store for the knowledge graph (entities/edges scoped by `group_id` per project)
|
||||
- **Memory/Graph (deprecated)**: Zep Cloud — legacy code path; new code should not depend on it. Several services still carry the `zep_*` filename prefix for historical reasons (`zep_tools.py`, `zep_entity_reader.py`, `zep_graph_memory_updater.py`).
|
||||
- **Simulation**: CAMEL-OASIS 0.2.5 + camel-ai 0.2.78 (multi-agent Twitter + Reddit simulation)
|
||||
- **Visualization**: D3.js 7
|
||||
- **i18n**: `vue-i18n` (frontend) + per-locale JSON in `/locales/` (`en.json`, `zh.json`, `languages.json`); backend logger messages translated as part of the i18n initiative
|
||||
|
||||
### Required Environment Variables
|
||||
Copy `.env.example` to `.env`:
|
||||
```
|
||||
LLM_API_KEY # Required
|
||||
LLM_BASE_URL # Default: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
LLM_MODEL_NAME # Default: qwen-plus
|
||||
ZEP_API_KEY # Required (Zep Cloud)
|
||||
# LLM (OpenAI SDK-compatible)
|
||||
LLM_API_KEY # Required
|
||||
LLM_BASE_URL # Default: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
LLM_MODEL_NAME # Default: qwen-plus
|
||||
|
||||
# Neo4j + Graphiti (knowledge graph)
|
||||
NEO4J_URI # Default: bolt://localhost:7687
|
||||
NEO4J_USER # Default: neo4j
|
||||
NEO4J_PASSWORD # Default: mirofish123 (override in real env)
|
||||
EMBEDDING_MODEL # Default: text-embedding-3-small
|
||||
# Override for non-OpenAI providers (e.g. Gemini: text-embedding-004)
|
||||
|
||||
# Optional — Accelerated LLM (omit entirely if not used)
|
||||
LLM_BOOST_API_KEY
|
||||
LLM_BOOST_BASE_URL
|
||||
LLM_BOOST_MODEL_NAME
|
||||
|
||||
# Deprecated, kept for backwards compat
|
||||
ZEP_API_KEY # Empty string acceptable
|
||||
```
|
||||
|
||||
### 5-Step Pipeline
|
||||
The core workflow is a sequential async pipeline:
|
||||
1. **Graph Build** — Upload files → LLM extracts ontology → Zep Cloud builds knowledge graph
|
||||
2. **Env Setup** — Read Zep entities → Generate OASIS agent profiles (AI personalities)
|
||||
1. **Graph Build** — Upload files → LLM extracts ontology → Graphiti writes nodes/edges to Neo4j (scoped by per-project `group_id`)
|
||||
2. **Env Setup** — Read entities from Neo4j → Generate OASIS agent profiles (AI personalities)
|
||||
3. **Simulation** — CAMEL-OASIS runs agents on dual platforms (Twitter + Reddit) in parallel
|
||||
4. **Report** — ReportAgent (ReACT loop) queries graph with tools: `SearchResult`, `InsightForge`, `Panorama`, `Interview`
|
||||
5. **Interaction** — Chat with simulated agents or the ReportAgent
|
||||
4. **Report** — `ReportAgent` (ReACT loop) queries the graph with tools: `SearchResult`, `InsightForge`, `Panorama`, `Interview`
|
||||
5. **Interaction** — Chat with simulated agents or the `ReportAgent`
|
||||
|
||||
### Backend Structure (`backend/app/`)
|
||||
- `api/` — Flask blueprints: `graph_bp`, `simulation_bp`, `report_bp`
|
||||
- `services/` — Core logic: graph building, simulation runner, report agent, Zep tools
|
||||
- `services/` — Core logic: graph building, simulation runner, report agent, Graphiti adapter, legacy Zep tools
|
||||
- `models/` — `Project` and `Task` state objects (in-memory, JSON-serializable)
|
||||
- `utils/` — LLM client wrapper, file parser, retry logic, Zep pagination
|
||||
- `config/config.py` — All configuration (LLM, Zep, chunking, simulation params)
|
||||
- `utils/` — LLM client wrapper, file parser, retry logic, Zep pagination, locale helpers, logger
|
||||
- `config.py` — All configuration (LLM, Neo4j, embedding, chunking, OASIS, ReportAgent params)
|
||||
|
||||
Long-running operations (ontology generation, graph build, profile generation, report generation) run as background tasks tracked via `Task` objects with progress polling.
|
||||
|
||||
|
|
@ -78,9 +102,24 @@ Long-running operations (ontology generation, graph build, profile generation, r
|
|||
- `views/` — Page components mapped to routes; `Process.vue` is the main 50KB workflow orchestrator
|
||||
- `components/` — `Step1-5` step components + `GraphPanel.vue` (D3 graph visualization)
|
||||
- `api/` — Axios services (`graph.js`, `simulation.js`, `report.js`) with 5-min timeout and exponential retry
|
||||
- `i18n/` — Locale loader; messages in repo-root `/locales/`
|
||||
- `router/`, `store/`, `assets/`
|
||||
|
||||
### Key Implementation Details
|
||||
- Reasoning model outputs (e.g., MiniMax/GLM with `<think>` tags or markdown code fences) are stripped before processing — see recent fix in commit `985f89f`
|
||||
- Simulation state is managed in `SimulationManager`; IPC between processes via `simulation_ipc.py`
|
||||
- Interview/chat with agents uses prefix injection to suppress tool calls in responses
|
||||
- Default simulation: max 10 rounds, Twitter actions include CREATE_POST/LIKE/REPOST/FOLLOW/QUOTE/DO_NOTHING; Reddit adds CREATE_COMMENT/DISLIKE
|
||||
### Key Implementation Conventions
|
||||
|
||||
These are conventions **established by this project**. Match them when adding new code.
|
||||
|
||||
- **Background tasks via `Task` model** — Any operation that takes more than a few seconds (ontology gen, graph build, profile gen, simulation, report) must be tracked through `Task` with status + progress fields and exposed via a polling endpoint.
|
||||
- **Reasoning-model output stripping** — Reasoning-model outputs (e.g. MiniMax/GLM with `<think>` tags or markdown code fences) must be stripped before JSON parsing. See the fix in commit `985f89f`.
|
||||
- **Simulation IPC via `simulation_ipc.py`** — Inter-process communication between the Flask app and simulation subprocesses goes through this module; do not call subprocess primitives directly elsewhere.
|
||||
- **Subprocess cleanup** — `SimulationRunner.register_cleanup()` is invoked at app start so simulation subprocesses are terminated on shutdown. Don't bypass it.
|
||||
- **Startup recovery (`_recover_stuck_projects`)** — On boot, projects stuck in `GRAPH_BUILDING` are auto-recovered to `GRAPH_COMPLETED` if Neo4j already has their nodes (the original task was killed by a restart). New code paths that introduce long-running tasks should follow the same recovery pattern.
|
||||
- **Per-project graph isolation** — All Neo4j/Graphiti queries must filter by the project's `group_id`. Cross-project graph access is not permitted.
|
||||
- **Interview / chat prefix injection** — Agent chat suppresses tool calls in user-visible responses via prefix injection. Preserve this when extending chat behavior.
|
||||
- **Default simulation parameters** — Max 10 rounds. Twitter actions: `CREATE_POST`, `LIKE_POST`, `REPOST`, `FOLLOW`, `QUOTE_POST`, `DO_NOTHING`. Reddit adds `CREATE_COMMENT`, `LIKE_COMMENT`, `DISLIKE_*`, `SEARCH_*`, `TREND`, `REFRESH`, `MUTE`. Configured in `app/config.py`.
|
||||
|
||||
### Coding Conventions
|
||||
- Follow the conventions already established in this project — match the surrounding file's style.
|
||||
- 4-space indentation, snake_case in Python; existing code mixes English and Chinese in comments/docstrings — keep both styles working.
|
||||
- Use type hints where the surrounding code uses them; otherwise match local style.
|
||||
- For new tooling decisions (lint, format, test runners), discuss before adding — the project intentionally has no enforced formatter at present.
|
||||
|
|
|
|||
50
README-EN.md
50
README-EN.md
|
|
@ -20,7 +20,7 @@
|
|||
[](https://x.com/mirofish_ai)
|
||||
[](https://www.instagram.com/mirofish_ai/)
|
||||
|
||||
[English](./README-EN.md) | [中文文档](./README.md)
|
||||
[English](./README.md) | [中文文档](./README-ZH.md)
|
||||
|
||||
</div>
|
||||
|
||||
|
|
@ -93,7 +93,24 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on
|
|||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: Source Code Deployment (Recommended)
|
||||
### Option 1: Docker Deployment (Recommended)
|
||||
|
||||
The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command.
|
||||
|
||||
```bash
|
||||
# 1. Copy and configure environment variables
|
||||
cp .env.example .env
|
||||
# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default)
|
||||
|
||||
# 2. Pull images and start
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Reads `.env` from the project root, exposes ports `3000` (frontend) and `5001` (backend).
|
||||
|
||||
> A faster mirror address is provided as a comment inside `docker-compose.yml`; uncomment to use it.
|
||||
|
||||
### Option 2: Source Code Deployment
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
|
|
@ -145,11 +162,22 @@ NEO4J_URI=bolt://localhost:7687
|
|||
NEO4J_USER=neo4j
|
||||
NEO4J_PASSWORD=your_neo4j_password
|
||||
|
||||
# Embedding model (uncomment if using Gemini API)
|
||||
# Embedding model (uncomment if using a non-OpenAI provider, e.g. Gemini)
|
||||
# EMBEDDING_MODEL=gemini-embedding-001
|
||||
```
|
||||
|
||||
> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party account required — completely free with no rate limits.
|
||||
**Optional — Accelerated LLM Configuration:**
|
||||
|
||||
If you have a faster/cheaper provider, you can route auxiliary calls through it.
|
||||
**Omit these entirely** if not used (do not leave placeholder values).
|
||||
|
||||
```env
|
||||
LLM_BOOST_API_KEY=your_api_key_here
|
||||
LLM_BOOST_BASE_URL=your_base_url_here
|
||||
LLM_BOOST_MODEL_NAME=your_model_name_here
|
||||
```
|
||||
|
||||
> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party knowledge-graph account is required — completely free with no rate limits.
|
||||
|
||||
#### 2. Install Dependencies
|
||||
|
||||
|
|
@ -186,20 +214,6 @@ npm run backend # Start backend only
|
|||
npm run frontend # Start frontend only
|
||||
```
|
||||
|
||||
### Option 2: Docker Deployment
|
||||
|
||||
```bash
|
||||
# 1. Configure environment variables (same as source deployment)
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Pull image and start
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 (backend)`
|
||||
|
||||
> Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
|
||||
|
||||
## 📬 Join the Conversation
|
||||
|
||||
<div align="center">
|
||||
|
|
|
|||
74
README-ZH.md
74
README-ZH.md
|
|
@ -93,7 +93,24 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体
|
|||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 一、源码部署（推荐）
|
||||
### 一、Docker 部署（推荐）
|
||||
|
||||
Docker 部署一键启动整个栈 —— 前端、后端和 Neo4j。
|
||||
|
||||
```bash
|
||||
# 1. 复制并配置环境变量
|
||||
cp .env.example .env
|
||||
# 编辑 .env，填入 LLM_API_KEY（如需覆盖默认 Neo4j 密码也一并修改）
|
||||
|
||||
# 2. 拉取镜像并启动
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）`。
|
||||
|
||||
> 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换。
|
||||
|
||||
### 二、源码部署
|
||||
|
||||
#### 前置要求
|
||||
|
||||
|
|
@ -102,6 +119,24 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体
|
|||
| **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` |
|
||||
| **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` |
|
||||
| **uv** | 最新版 | Python 包管理器 | `uv --version` |
|
||||
| **Neo4j** | 5.x Community | 本地知识图谱数据库 | `neo4j --version` |
|
||||
|
||||
**安装 Neo4j（选择适合你的方式）：**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install neo4j
|
||||
|
||||
# Linux (Debian/Ubuntu)
|
||||
# 参考官方文档：https://neo4j.com/docs/operations-manual/current/installation/linux/
|
||||
|
||||
# Windows / 所有平台
|
||||
# 下载 Desktop 版本：https://neo4j.com/download/
|
||||
|
||||
# 首次启动前设置密码，然后启动服务
|
||||
neo4j-admin dbms set-initial-password your_neo4j_password
|
||||
neo4j start
|
||||
```
|
||||
|
||||
#### 1. 配置环境变量
|
||||
|
||||
|
|
@ -122,11 +157,28 @@ LLM_API_KEY=your_api_key
|
|||
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
LLM_MODEL_NAME=qwen-plus
|
||||
|
||||
# Zep Cloud 配置
|
||||
# 每月免费额度即可支撑简单使用：https://app.getzep.com/
|
||||
ZEP_API_KEY=your_zep_api_key
|
||||
# 知识图谱配置（本地 Neo4j + Graphiti，免费无限制）
|
||||
NEO4J_URI=bolt://localhost:7687
|
||||
NEO4J_USER=neo4j
|
||||
NEO4J_PASSWORD=your_neo4j_password
|
||||
|
||||
# Embedding 模型（使用非 OpenAI 厂商时取消注释，例如 Gemini）
|
||||
# EMBEDDING_MODEL=gemini-embedding-001
|
||||
```
|
||||
|
||||
**可选 —— 加速 LLM 配置：**
|
||||
|
||||
如果有更快或更便宜的供应商，可以把辅助调用路由过去。
|
||||
**未使用时请整段省略**（不要保留占位符）。
|
||||
|
||||
```env
|
||||
LLM_BOOST_API_KEY=your_api_key_here
|
||||
LLM_BOOST_BASE_URL=your_base_url_here
|
||||
LLM_BOOST_MODEL_NAME=your_model_name_here
|
||||
```
|
||||
|
||||
> **注意：** MiroFish 已从 Zep Cloud 迁移至本地 **Graphiti + Neo4j**，无需注册任何第三方知识图谱服务，完全免费且无速率限制。
|
||||
|
||||
#### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
|
|
@ -162,20 +214,6 @@ npm run backend # 仅启动后端
|
|||
npm run frontend # 仅启动前端
|
||||
```
|
||||
|
||||
### 二、Docker 部署
|
||||
|
||||
```bash
|
||||
# 1. 配置环境变量（同源码部署）
|
||||
cp .env.example .env
|
||||
|
||||
# 2. 拉取镜像并启动
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）`
|
||||
|
||||
> 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换
|
||||
|
||||
## 📬 更多交流
|
||||
|
||||
<div align="center">
|
||||
|
|
|
|||
85
README.md
85
README.md
|
|
@ -93,41 +93,50 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on
|
|||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: Source Code Deployment (Recommended)
|
||||
### Option 1: Docker Deployment (Recommended)
|
||||
|
||||
The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command.
|
||||
|
||||
```bash
|
||||
# 1. Copy and configure environment variables
|
||||
cp .env.example .env
|
||||
# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default)
|
||||
|
||||
# 2. Pull images and start
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Reads `.env` from the project root, exposes ports `3000` (frontend) and `5001` (backend).
|
||||
|
||||
> A faster mirror address is provided as a comment inside `docker-compose.yml`; uncomment to use it.
|
||||
|
||||
### Option 2: Source Code Deployment
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
<<<<<<< HEAD
|
||||
| Tool | Version | Description | Check Installation |
|
||||
|------|---------|-------------|-------------------|
|
||||
| **Node.js** | 18+ | Frontend runtime, includes npm | `node -v` |
|
||||
| **Python** | ≥3.11, ≤3.12 | Backend runtime | `python --version` |
|
||||
| **uv** | Latest | Python package manager | `uv --version` |
|
||||
=======
|
||||
| 工具 | 版本要求 | 说明 | 安装检查 |
|
||||
|------|---------|------|---------|
|
||||
| **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` |
|
||||
| **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` |
|
||||
| **uv** | 最新版 | Python 包管理器 | `uv --version` |
|
||||
| **Neo4j** | 5.x Community | 本地知识图谱数据库 | `neo4j --version` |
|
||||
| **Neo4j** | 5.x Community | Local knowledge graph database | `neo4j --version` |
|
||||
|
||||
**安装 Neo4j（选择适合你的方式）：**
|
||||
**Install Neo4j (choose one):**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install neo4j
|
||||
|
||||
# Linux (Debian/Ubuntu)
|
||||
# 参考官方文档：https://neo4j.com/docs/operations-manual/current/installation/linux/
|
||||
# See official docs: https://neo4j.com/docs/operations-manual/current/installation/linux/
|
||||
|
||||
# Windows / 所有平台
|
||||
# 下载 Desktop 版本：https://neo4j.com/download/
|
||||
# Windows / All platforms
|
||||
# Download Neo4j Desktop: https://neo4j.com/download/
|
||||
|
||||
# 首次启动前设置密码，然后启动服务
|
||||
# Set password before first start, then launch
|
||||
neo4j-admin dbms set-initial-password your_neo4j_password
|
||||
neo4j start
|
||||
```
|
||||
>>>>>>> abhiyadav2345/feat/graphiti-neo4j-migration
|
||||
|
||||
#### 1. Configure Environment Variables
|
||||
|
||||
|
|
@ -148,29 +157,29 @@ LLM_API_KEY=your_api_key
|
|||
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
LLM_MODEL_NAME=qwen-plus
|
||||
|
||||
<<<<<<< HEAD
|
||||
# Zep Cloud Configuration
|
||||
# Free monthly quota is sufficient for simple usage: https://app.getzep.com/
|
||||
ZEP_API_KEY=your_zep_api_key
|
||||
```
|
||||
|
||||
#### 2. Install Dependencies
|
||||
=======
|
||||
# 知识图谱配置（本地 Neo4j + Graphiti，免费无限制）
|
||||
# 安装 Neo4j Community Edition：https://neo4j.com/download/
|
||||
# macOS 用户：brew install neo4j && neo4j start
|
||||
# Knowledge Graph — local Neo4j + Graphiti (free, no rate limits)
|
||||
NEO4J_URI=bolt://localhost:7687
|
||||
NEO4J_USER=neo4j
|
||||
NEO4J_PASSWORD=your_neo4j_password
|
||||
|
||||
# Embedding 模型（使用 Gemini API 时取消注释）
|
||||
# Embedding model (uncomment if using a non-OpenAI provider, e.g. Gemini)
|
||||
# EMBEDDING_MODEL=gemini-embedding-001
|
||||
```
|
||||
|
||||
> **注意：** MiroFish 已从 Zep Cloud 迁移至本地 **Graphiti + Neo4j**，无需注册任何第三方服务，完全免费且无速率限制。
|
||||
**Optional — Accelerated LLM Configuration:**
|
||||
|
||||
#### 2. 安装依赖
|
||||
>>>>>>> abhiyadav2345/feat/graphiti-neo4j-migration
|
||||
If you have a faster/cheaper provider, you can route auxiliary calls through it.
|
||||
**Omit these entirely** if not used (do not leave placeholder values).
|
||||
|
||||
```env
|
||||
LLM_BOOST_API_KEY=your_api_key_here
|
||||
LLM_BOOST_BASE_URL=your_base_url_here
|
||||
LLM_BOOST_MODEL_NAME=your_model_name_here
|
||||
```
|
||||
|
||||
> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party knowledge-graph account is required — completely free with no rate limits.
|
||||
|
||||
#### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
# One-click installation of all dependencies (root + frontend + backend)
|
||||
|
|
@ -205,20 +214,6 @@ npm run backend # Start backend only
|
|||
npm run frontend # Start frontend only
|
||||
```
|
||||
|
||||
### Option 2: Docker Deployment
|
||||
|
||||
```bash
|
||||
# 1. Configure environment variables (same as source deployment)
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Pull image and start
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 (backend)`
|
||||
|
||||
> Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
|
||||
|
||||
## 📬 Join the Conversation
|
||||
|
||||
<div align="center">
|
||||
|
|
@ -243,4 +238,4 @@ MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interacti
|
|||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</a>
|
||||
|
|
|
|||
Loading…
Reference in New Issue