Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lionfaya58--second-cerveau/badge.svg)](/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

i

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
  1. # Second Cerveau
  2. 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.
  3. 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.
  4. ## What it does
  5. - `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.
  6. - `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.
  7. - 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.
  8. - 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.
  9. ## Independent verification
  10. An agent never validates its own work. Some of this is checked by the server and some of it is only written down.
  11. What the server refuses:
  12. - 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`).
  13. - 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.
  14. What the server only warns about:
  15. - 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.
  16. Rules written in `AGENTS.md` that no code checks:
  17. - 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.
  18. - Emails and messages are drafts only. Agents never send or schedule a send; the human does.
  19. ## How the pieces fit
  20. ```mermaid
  21. flowchart LR
  22. subgraph CC[Claude Code session]
  23. A[Agent]
  24. end
  25. A -- MCP stdio --> S[second-cerveau MCP server<br/>35 tools, rules.json]
  26. S -- locked writes, UTF-8 without BOM --> V[(Vault<br/>NOW.md, Daily/, projets/, Connaissances/)]
  27. H1[SessionStart: session_start] -. injects loading protocol .-> A
  28. H2[Stop: stop_gate] -. closing reminder after edits .-> A
  29. H3[Stop: bus_stop_gate] -. unread mail, bus watcher .-> A
  30. H4[PreCompact: precompact_gate] -. snapshots NOW.md and today's Daily .-> V
  31. H5[PostToolUse: bus_mail_ping] -. new bus mail notice .-> A
  32. Codex[Codex / Gemini] -- MCP --> S
  33. ```
  34. ### Hooks (`hooks/`)
  35. | Event | Script | What it does |
  36. |---|---|---|
  37. | 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). |
  38. | 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. |
  39. | 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. |
  40. | PreCompact | `precompact_gate.mjs` | Copies NOW.md, today's Daily, recent `_State.md` files and the session registry to `_archive/precompact/` before context compaction. |
  41. | PostToolUse | `bus_mail_ping.mjs` | Tells the agent, between tool calls, that bus mail is waiting. |
  42. `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.
  43. `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.
  44. ### MCP tools (`mcp-server/`)
  45. | Area | Tools |
  46. |---|---|
  47. | State | `get_current_state`, `update_focus`, `update_next_steps`, `update_projects_table`, `get_rules` |
  48. | Sessions | `open_session`, `append_session_entry`, `close_session`, `get_active_sessions`, `reap_stale_sessions`, `get_session_board` |
  49. | Projects | `list_projects`, `get_project`, `create_project`, `archive_project`, `update_project_index` |
  50. | Work tracking | `update_kanban`, `add_progress_entry`, `get_progress`, `add_decision`, `get_decisions`, `manage_lock` |
  51. | Knowledge | `add_knowledge`, `verify_knowledge`, `search_knowledge`, `search_knowledge_semantic`, `get_knowledge_index`, `get_related_notes` |
  52. | Maintenance | `archive_old_entries`, `consolidate_memory`, `memory_doctor` |
  53. | Bus | `send_agent_message`, `get_messages`, `manage_bus_channel`, `archive_bus` |
  54. 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.
  55. ## Repository layout
  56. ```
  57. mcp-server/ MCP server source, tests and rules.json
  58. hooks/ Claude Code hooks and their tests (hooks/test/)
  59. vault-skeleton/ Empty vault: AGENTS.md, routing, templates, blank Memory/
  60. config-templates/ Blocks to merge into Claude Code and Claude Desktop settings
  61. scripts/ setup.mjs (install) and verify.mjs (real JSON-RPC check)
  62. ```
  63. ## Install
  64. Requires Node.js 22 or later. The steps below are for Windows; on macOS or Linux use `/` paths.
  65. 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.
  66. ```
  67. node scripts/setup.mjs --root "%USERPROFILE%\SecondCerveau" --home "%USERPROFILE%" --prenom "<your first name>" --vault aucun
  68. ```
  69. 2. Build and test the server.
  70. ```
  71. cd "%USERPROFILE%\.mcp_modules\second-cerveau-project"
  72. npm ci
  73. npm run build
  74. npm test
  75. ```
  76. 3. Register the server in Claude Code (`claude.cmd` on Windows, since the PowerShell shim drops the `--`).
  77. ```
  78. 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"
  79. ```
  80. 4. Merge `config-templates/settings-hooks.json` into `~/.claude/settings.json`, replacing `{{ROOT}}`. Add to the existing arrays; do not replace your other hooks.
  81. 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.
  82. ```
  83. node scripts/verify.mjs "%USERPROFILE%\SecondCerveau\Mon_IA_Generaliste" "%USERPROFILE%\.mcp_modules\second-cerveau-project\dist\index.js"
  84. ```
  85. 6. Restart Claude Code, then try `open_session`, `get_current_state` and `get_rules`. Fill in `Memory/USER.md` with your own preferences.
  86. ## License
  87. Not chosen yet. Until a license file is added, all rights are reserved.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.