@time-machine-lab/tmlbrain 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# TMLBrain
+
+TMLBrain (T M L 外置大脑) is a lightweight, AI-native team knowledge base.
+
+It is designed as TML's external brain: easy to search, easy to modify,
+safe to back up, and friendly to AI agents that need to read, update, classify,
+and maintain shared knowledge.
+
+## Core Idea
+
+TMLBrain keeps three coordinated copies of the knowledge base:
+
+- Local snapshot: used by team members and AI agents for fast search and local indexes.
+- Server knowledge base: the shared source and only normal write surface.
+- Dedicated knowledge repository: server-side restore, disaster recovery, and version history.
+
+## Initial Scope
+
+- Maintain a clean folder structure for documents.
+- Let AI search local snapshots and request server-side precise Markdown updates.
+- Pull read-only local snapshots from the server copy.
+- Back up the server copy to GitHub on a server-side schedule.
+- Build an optional online reading layer later.
+
+## Repository Layout
+
+```text
+TMLBrain/
+  knowledge/              Team knowledge files.
+  skills/tmlbrain/        AI skill for search, server-side writes, lifecycle, and sync workflows.
+  bin/tmlbrain.js         CLI/server runtime for search, validation, indexing, sync, writes, and backup.
+  scripts/sync/           Local/server/GitHub synchronization scripts.
+  scripts/index/          Search index and knowledge graph scripts.
+  docs/                   Architecture, decisions, and operating docs.
+```
+
+## Local Tooling
+
+The npm package exposes a dependency-light CLI:
+
+```text
+npx @time-machine-lab/tmlbrain client install
+tmlbrain find "keyword"
+tmlbrain save --title "Title" --content "Content"
+```
+
+Clients use Node for exact search and local indexing. HTTP-only clients do not
+need Git. Server-side writes use Node plus Git from the server worktree.
+Python-based CocoIndex and LightRAG support are optional graph retrieval
+enhancements.
+
+Interactive client install asks for a server URL. Leave it empty to start in
+local-only mode, or provide the TMLBrain server URL and token to enable team
+sync and server-side writes.
+
+Non-interactive client install:
+
+```text
+npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+```
+
+## Server Docker
+
+The server is deployed separately from clients and requires a token:
+
+```text
+docker run -d --name tmlbrain-server \
+  -p 7389:7389 \
+  -e TMLBRAIN_SERVER_TOKEN=change-me \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REF=main \
+  -v tmlbrain-data:/data \
+  <DOCKER_REPO>:latest
+```
+
+Or with Compose:
+
+```text
+TMLBRAIN_SERVER_TOKEN=change-me docker compose up -d
+```
+
+Client npm releases and server Docker releases are separate artifacts, but they
+are published from the same commit-message driven workflow:
+`.github/workflows/auto-release.yml`.
+
+Only pushes to `main` are considered. A release runs when the HEAD commit
+message contains `<Auto>` and a version flag:
+
+```text
+[tml-brain]<Auto> release server and client -v:0.1.0 -rp:7389 -de:<-e KEY=value>
+```
+
+- `-v` is required and becomes both the npm package version and Docker image
+  version; use a Docker-compatible value such as `0.1.0` or `0.1.0-beta.1`.
+- `-rp` sets the default server port baked into the Docker image; it defaults
+  to `7389`.
+- `-de` is optional runtime Docker argument metadata recorded in
+  the commit message and may also be copied into `prod_deploy.log` manually.
+
+The workflow publishes `@time-machine-lab/tmlbrain` to npm, pushes the server
+image to the Docker repository configured by `DOCKER_REPO`, and then deploys
+that image to the configured server with `SERVER_HOST`, `SERVER_USER`, and
+`SERVER_PWD`. Docker images are tagged as `latest`, `version`, and `vversion`.
+The workflow does not mutate repository files; if
+maintainers want a production release note, update `prod_deploy.log` manually
+before committing the auto-release instruction.
+
+Required GitHub Actions secrets:
+
+```text
+NPM_TOKEN
+DOCKER_USERNAME
+DOCKER_PASSWORD
+DOCKER_REPO
+SERVER_HOST
+SERVER_USER
+SERVER_PWD
+TMLBRAIN_SERVER_TOKEN
+```
+
+For a private dedicated knowledge repository, also configure:
+
+```text
+TMLBRAIN_KNOWLEDGE_REPO
+TMLBRAIN_KNOWLEDGE_TOKEN
+TMLBRAIN_KNOWLEDGE_REF
+```
+
+`TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS URL such as
+`https://github.com/org/repo.git`. `TMLBRAIN_KNOWLEDGE_TOKEN` is a GitHub token
+with write access to that repository. Fine-grained tokens are preferred;
+classic tokens also work when they have the right repository scope: use `repo`
+for private repositories, or `public_repo` only for public repositories. The
+running server needs this credential to push knowledge backups to GitHub;
+clients never need it.
+
+The Docker image contains the TMLBrain tool and knowledge templates only. Real
+team knowledge should live in a dedicated knowledge repository configured with
+`TMLBRAIN_KNOWLEDGE_REPO`. If the server volume already has `/data/worktree`,
+the container reuses it instead of cloning again.
+For team deployments, do not omit `TMLBRAIN_KNOWLEDGE_REPO`; without it, a new
+volume starts from a template-only skeleton intended for development or blank
+starts.
+
+## Guiding Principles
+
+- Files are the source of truth.
+- Markdown is the default document format.
+- Small, precise server-side edits are preferred over whole-document rewrites.
+- Every document should have a clear owner, status, and update path.
+- AI should help maintain the knowledge base instead of only searching it.
+- Clients do not push to the server repository or dedicated knowledge repository.