second-cerveau
Memory and control layer for running projects with AI agents. An MCP server enforces the rules, Claude Code hooks force a clean handoff, and no agent validates its own work.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/lionfaya58--second-cerveau)HTML
<a href="/listings/lionfaya58--second-cerveau"><img src="/api/listings/lionfaya58--second-cerveau/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires Node.js 22 or later. The steps below are for Windows; on macOS or Linux use `/` paths.
1. Copy the kit into place. `setup.mjs` keeps existing vault files and your `rules.json`, but overwrites the server code and the hooks with the kit's version. It prints the number of unfilled placeholders, which must be 0, and refuses a root inside OneDrive, Google Drive or Dropbox, because sync clients corrupt concurrent writes.
node scripts/setup.mjs --root "%USERPROFILE%\SecondCerveau" --home "%USERPROFILE%" --prenom "<your first name>" --vault aucun
2. Build and test the server.
cd "%USERPROFILE%\.mcp_modules\second-cerveau-project" npm ci npm run build npm test
3. Register the server in Claude Code (`claude.cmd` on Windows, since the PowerShell shim drops the `--`).
claude.cmd mcp add second-cerveau --scope user -e CERVEAU_ROOT="%USERPROFILE%\SecondCerveau\Mon_IA_Generaliste" -e SECOND_CERVEAU_AGENT=claude-code -- node "%USERPROFILE%\.mcp_modules\second-cerveau-project\dist\index.js"
4. Merge `config-templates/settings-hooks.json` into `~/.claude/settings.json`, replacing `{{ROOT}}`. Add to the existing arrays; do not replace your other hooks.
5. Check the install. `verify.mjs` starts the server, calls `initialize`, `tools/list` and `get_current_state`, and checks that the hook files exist and parse. It does not check that they are wired in `settings.json`. The install is finished only when it prints PASS.
node scripts/verify.mjs "%USERPROFILE%\SecondCerveau\Mon_IA_Generaliste" "%USERPROFILE%\.mcp_modules\second-cerveau-project\dist\index.js"
6. Restart Claude Code, then try `open_session`, `get_current_state` and `get_rules`. Fill in `Memory/USER.md` with your own preferences.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 124 lines
- # Second Cerveau
- A blank, installable kit of the memory and control layer I use to run several projects alone with AI agents (Claude Code, Codex, Gemini). The agents share one Markdown vault and are told to change it through an MCP server, which applies the rules on every write. Claude Code hooks remind them to log their work before they stop, so the next agent can pick it up.
- This repository holds the architecture only. It ships empty templates, and none of my data, clients or notes. Code comments and agent-facing messages are in French, because that is the language the system runs in.
- ## What it does
- - `NOW.md` is a short dashboard (focus, projects, next steps). Session narratives go to `Memory/Daily/`, project detail to `Memory/projets/<project>/`. An agent starting cold reads AGENTS.md, USER.md and NOW.md, then the summary of the project it works on.
- - `rules.json` is reread on every tool call. The server refuses a new next step once NOW.md holds 30, refuses to mark a kanban task done before it has been in review, writes under file locks, and removes byte order marks, which broke the YAML front matter of notes written from PowerShell.
- - Agents declare a session and a role, log what they did, and close. A Stop hook reminds them once per session to close when the transcript shows file edits.
- - Agents can message each other through the server. The bus is off by default and the human switches it on per conversation. This is a convention kept by the hooks: no MCP tool can turn it on, but an agent with a shell could create the marker file.
- ## Independent verification
- An agent never validates its own work. Some of this is checked by the server and some of it is only written down.
- What the server refuses:
- - A kanban task must be in `🟠 EN RELECTURE` before it can move to `🟢 TERMINÉ`. Any other jump to done is rejected (`qa_required_before_done`).
- - Every knowledge note written with `add_knowledge` starts in quarantine (`à vérifier`) with its author, date, source and an evidence level: `mesuré` (measured), `déduit` (inferred) or `supposé` (assumed). `verify_knowledge` refuses when the verifier is the author. The quarantine came after an agent wrote a false rule into shared memory.
- What the server only warns about:
- - When the agent who set a task's previous status also marks it done, `update_kanban` accepts the change and adds a warning that another agent should validate. This was a hard refusal at first. Agent identity is a free string, so any agent could get past it by changing its name, while the refusal kept blocking normal work; it became a warning. The comparison is exact, so a change of case is enough to avoid the warning. `verify_knowledge` refuses the author whatever the case, but it cannot tell when an agent gives itself a new name either.
- Rules written in `AGENTS.md` that no code checks:
- - Reviewers are at least as strong as the model they check and use a different method from the producer, such as their own tests, a real run or mutants.
- - Emails and messages are drafts only. Agents never send or schedule a send; the human does.
- ## How the pieces fit
- ```mermaid
- flowchart LR
- subgraph CC[Claude Code session]
- A[Agent]
- end
- A -- MCP stdio --> S[second-cerveau MCP server<br/>35 tools, rules.json]
- S -- locked writes, UTF-8 without BOM --> V[(Vault<br/>NOW.md, Daily/, projets/, Connaissances/)]
- H1[SessionStart: session_start] -. injects loading protocol .-> A
- H2[Stop: stop_gate] -. closing reminder after edits .-> A
- H3[Stop: bus_stop_gate] -. unread mail, bus watcher .-> A
- H4[PreCompact: precompact_gate] -. snapshots NOW.md and today's Daily .-> V
- H5[PostToolUse: bus_mail_ping] -. new bus mail notice .-> A
- Codex[Codex / Gemini] -- MCP --> S
- ```
- ### Hooks (`hooks/`)
- | Event | Script | What it does |
- |---|---|---|
- | SessionStart | `session_start.mjs` | Tells the agent what to load first (AGENTS.md, USER.md, NOW.md). After a context compaction it adds a resume table. Once a week, when NOW.md's next steps are full, it asks for a cleanup by a sub-agent (`now-curator`, part of the full system and not shipped here). |
- | Stop | `stop_gate.mjs` | If the transcript shows file edits, blocks the end of the turn once per session and asks for the closing routine. It does not check whether the session was already closed. Read-only sessions pass, and any internal error lets the turn end. |
- | Stop | `bus_stop_gate.mjs` | Applies only to a conversation where the human turned the bus on. It holds the turn while mail is unread or the watcher heartbeat is missing, two reminders at most. |
- | PreCompact | `precompact_gate.mjs` | Copies NOW.md, today's Daily, recent `_State.md` files and the session registry to `_archive/precompact/` before context compaction. |
- | PostToolUse | `bus_mail_ping.mjs` | Tells the agent, between tool calls, that bus mail is waiting. |
- `bus_inbox.mjs` is the shared library of the bus hooks. `bus_guetteur.mjs` is the watcher an agent arms between turns, and `bus_cooperation_cli.mjs` is the human's on/off switch.
- `stop_gate`, `session_start` and `precompact_gate` find the vault from their own location (`MCP_Core/scripts/../../Memory`). The bus hooks and the NOW.md cleanup check use `CERVEAU_ROOT` when it is set. No disk path is written in any of them.
- ### MCP tools (`mcp-server/`)
- | Area | Tools |
- |---|---|
- | State | `get_current_state`, `update_focus`, `update_next_steps`, `update_projects_table`, `get_rules` |
- | Sessions | `open_session`, `append_session_entry`, `close_session`, `get_active_sessions`, `reap_stale_sessions`, `get_session_board` |
- | Projects | `list_projects`, `get_project`, `create_project`, `archive_project`, `update_project_index` |
- | Work tracking | `update_kanban`, `add_progress_entry`, `get_progress`, `add_decision`, `get_decisions`, `manage_lock` |
- | Knowledge | `add_knowledge`, `verify_knowledge`, `search_knowledge`, `search_knowledge_semantic`, `get_knowledge_index`, `get_related_notes` |
- | Maintenance | `archive_old_entries`, `consolidate_memory`, `memory_doctor` |
- | Bus | `send_agent_message`, `get_messages`, `manage_bus_channel`, `archive_bus` |
- The server is TypeScript on the official MCP SDK, with `zod` schemas and `proper-lockfile`. It refuses to boot if `CERVEAU_ROOT` is missing, points into a cloud-synced folder, or does not contain `Memory/NOW.md`. The check exists because a stale variable once pointed the server at a backup copy of the vault.
- ## Repository layout
- ```
- mcp-server/ MCP server source, tests and rules.json
- hooks/ Claude Code hooks and their tests (hooks/test/)
- vault-skeleton/ Empty vault: AGENTS.md, routing, templates, blank Memory/
- config-templates/ Blocks to merge into Claude Code and Claude Desktop settings
- scripts/ setup.mjs (install) and verify.mjs (real JSON-RPC check)
- ```
- ## Install
- Requires Node.js 22 or later. The steps below are for Windows; on macOS or Linux use `/` paths.
- 1. Copy the kit into place. `setup.mjs` keeps existing vault files and your `rules.json`, but overwrites the server code and the hooks with the kit's version. It prints the number of unfilled placeholders, which must be 0, and refuses a root inside OneDrive, Google Drive or Dropbox, because sync clients corrupt concurrent writes.
- ```
- node scripts/setup.mjs --root "%USERPROFILE%\SecondCerveau" --home "%USERPROFILE%" --prenom "<your first name>" --vault aucun
- ```
- 2. Build and test the server.
- ```
- cd "%USERPROFILE%\.mcp_modules\second-cerveau-project"
- npm ci
- npm run build
- npm test
- ```
- 3. Register the server in Claude Code (`claude.cmd` on Windows, since the PowerShell shim drops the `--`).
- ```
- claude.cmd mcp add second-cerveau --scope user -e CERVEAU_ROOT="%USERPROFILE%\SecondCerveau\Mon_IA_Generaliste" -e SECOND_CERVEAU_AGENT=claude-code -- node "%USERPROFILE%\.mcp_modules\second-cerveau-project\dist\index.js"
- ```
- 4. Merge `config-templates/settings-hooks.json` into `~/.claude/settings.json`, replacing `{{ROOT}}`. Add to the existing arrays; do not replace your other hooks.
- 5. Check the install. `verify.mjs` starts the server, calls `initialize`, `tools/list` and `get_current_state`, and checks that the hook files exist and parse. It does not check that they are wired in `settings.json`. The install is finished only when it prints PASS.
- ```
- node scripts/verify.mjs "%USERPROFILE%\SecondCerveau\Mon_IA_Generaliste" "%USERPROFILE%\.mcp_modules\second-cerveau-project\dist\index.js"
- ```
- 6. Restart Claude Code, then try `open_session`, `get_current_state` and `get_rules`. Fill in `Memory/USER.md` with your own preferences.
- ## License
- Not chosen yet. Until a license file is added, all rights are reserved.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.