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 accepted server writes to GitHub from the server side.
• Build an optional online reading layer later.

Repository Layout

TMLBrain/
  knowledge/              Team knowledge files.
  skills/tmlbrain/        AI skill for search, server-side writes, governance, 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.

Client Install

Recommended npm install:

npm install -g @time-machine-lab/tmlbrain@latest
tmlbrain client install

The installer 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 npm install:

npm install -g @time-machine-lab/tmlbrain@latest
tmlbrain client install --server http://server-host:8477 --token <token> --yes

After installation:

tmlbrain version
tmlbrain -v
tmlbrain -version
tmlbrain --version
tmlbrain version --json
tmlbrain find "keyword"
tmlbrain maintain report
tmlbrain save --title "Title" --content "Content"
tmlbrain save --title "Title" --content "Content" --merge
tmlbrain save --title "Title" --content "Content" --no-merge
tmlbrain remote update --file knowledge/30-resources/note.md --replace "old" --with "new"
tmlbrain remote delete --file knowledge/30-resources/old-note.md

Saving and archiving into the knowledge base are the same user intent: TMLBrain stores the content and classifies it through the governance model. It does not default normal saves to knowledge/00-inbox/; inbox is only for genuinely unclassified or explicitly temporary capture.

TMLBrain classifies saved knowledge with governance metadata such as placement, type, domain, workflow_state, classification_confidence, and classification_reason. It also treats small inputs as knowledge items: a server IP, database record, tool account, tutorial step, or project fact should update or append to an existing canonical knowledge container when one exists instead of blindly creating a new document. For organized document-shaped input, TMLBrain also looks for same-topic documents with compatible placement, domain, and type. When high-confidence matches exist, it lists candidates and asks for confirmation before merging. Use --merge after confirmation or --no-merge when a new standalone document is explicitly required.

Deletion is explicit: use remote delete only when the user really wants a document removed. Otherwise prefer marking content stale through remote update.

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.

Update an existing client without re-entering the setup flow:

tmlbrain update

Use npx -y @time-machine-lab/tmlbrain@latest client install only when you want a one-time install without keeping a global tmlbrain command. If PowerShell reports that tmlbrain is not recognized, install or refresh the global client with npm install -g @time-machine-lab/tmlbrain@latest, then open a new terminal so the npm global bin directory is on PATH.

Server Docker

The server is deployed separately from clients and requires a token:

docker run -d --name tmlbrain-server \
  -p 8477:8477 \
  -e TMLBRAIN_SERVER_TOKEN=change-me \
  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
  -e TMLBRAIN_KNOWLEDGE_REF=main \
  -v tmlbrain-data:/data \
  <DOCKER_REPO>:latest

Or with Compose:

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:

[tml-brain]<Auto> release server and client -v:0.1.0 -rp:8477 -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 8477.
• -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 server deploy step skips Docker login by default and directly pulls the public image. Only set TMLBRAIN_SERVER_DOCKER_LOGIN=true for private images. 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:

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:

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.

Optional GitHub connectivity secret:

TMLBRAIN_SERVER_GIT_PROXY_URL

Use it only when the server cannot reach GitHub directly. The deployment applies the proxy to Git operations for https://github.com only. If this secret is not set but a tmlbrain-proxy container exists on the server, deployment uses that container as the Git-only proxy automatically.

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.
• Saved knowledge should be classified by placement, type, domain, confidence, and reason instead of piling up in inbox.
• Knowledge items should be resolved into canonical containers before new documents are created.
• AI should help maintain the knowledge base instead of only searching it.
• Clients do not push to the server repository or dedicated knowledge repository.