fix: preserve agent memory files when installing RA-H rules

- Add RA-H graph memory as a marked section instead of replacing files
- Make install-rules idempotent for AGENTS.md and CLAUDE.md
- Document the demo-safe memory file setup command

Generated with Claude Code

README.md

@@ -217,6 +217,8 @@ If you need a frozen version for debugging, pin it explicitly and restart the cl
 Suggested snippet:
 
 ```md
+## RA-H Graph Memory
+
 You are helping build a thoughtful graph of atomic units of context.
 
 - Use `queryNodes` for direct lookup of a specific existing node.
@@ -226,6 +228,12 @@ You are helping build a thoughtful graph of atomic units of context.
 - Preserve the user's wording in `source` for user-authored ideas unless they explicitly want a rewrite.
 ```
 
+Or install that guidance into the repo memory file:
+
+```bash
+npx -y ra-h-mcp-server@latest install-rules --client codex --target . --yes
+```
+
 Available tools:
 
 | Tool | What it does |

apps/mcp-server-standalone/README.md

@@ -88,9 +88,17 @@ Once connected, the agent should:
 If you use external agents through this MCP server, you may add one short instruction line to your agent memory file (`AGENTS.md`, `CLAUDE.md`, etc.) as optional reinforcement:
 
 ```md
+## RA-H Graph Memory
+
 Retrieve relevant RA-H context before substantive work, search before creating, and keep durable writeback prompts brief and confirmation-gated.
 ```
 
+Install or refresh that guidance without replacing the rest of the memory file:
+
+```bash
+npx -y ra-h-mcp-server@latest install-rules --client codex --target . --yes
+```
+
 RA-H should still work well without this line. The MCP tools, server instructions, skills, and docs are meant to carry the core behavior on their own.
 
 Do not create contradictory instruction files. Prefer one short reinforcement line over a pile of overlapping guidance.

apps/mcp-server-standalone/cli.js

@@ -344,7 +344,9 @@ function validateClient(client) {
 }
 
 function rulesSnippet() {
-  return `You are helping build a thoughtful graph of atomic units of context.
+  return `## RA-H Graph Memory
+
+You are helping build a thoughtful graph of atomic units of context.
 
 - Before substantive work that touches the user's projects, ideas, people, decisions, or prior context, retrieve relevant graph context from RA-H.
 - Use queryNodes for direct lookup of a specific existing node.
@@ -356,6 +358,19 @@ function rulesSnippet() {
 `;
 }
 
+function mergeRulesFile(existing, content) {
+  const start = '<!-- RA-H_GRAPH_MEMORY_START -->';
+  const end = '<!-- RA-H_GRAPH_MEMORY_END -->';
+  const block = `${start}\n${content.trimEnd()}\n${end}`;
+  const pattern = new RegExp(`${start}[\\s\\S]*?${end}`);
+
+  if (pattern.test(existing)) {
+    return `${existing.replace(pattern, block).trimEnd()}\n`;
+  }
+
+  return `${existing.trimEnd()}${existing.trim() ? '\n\n' : ''}${block}\n`;
+}
+
 function rulesTarget(client, target) {
   const base = expandPath(target || process.cwd());
   if (client === 'cursor') return path.join(base, '.cursor', 'rules', 'ra-h.mdc');
@@ -415,8 +430,9 @@ function commandInstallRules(args) {
   }
 
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-  fs.writeFileSync(targetPath, content);
-  log(`Wrote rules to ${targetPath}`);
+  const existing = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8') : '';
+  fs.writeFileSync(targetPath, mergeRulesFile(existing, content));
+  log(`Updated rules in ${targetPath}`);
 }
 
 function commandSetup(args) {

apps/mcp-server-standalone/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ra-h-mcp-server",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ra-h-mcp-server",
-      "version": "3.2.1",
+      "version": "3.2.2",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.0.0",

apps/mcp-server-standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ra-h-mcp-server",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Connect Claude Code/Desktop to your RA-H knowledge base. Direct SQLite access to an existing RA-H database.",
   "main": "index.js",
   "bin": {

docs/8_mcp.md

@@ -133,6 +133,8 @@ Recommended guidance:
 Suggested memory-file snippet:
 
 ```md
+## RA-H Graph Memory
+
 You are helping build a thoughtful graph of atomic units of context.
 
 - Use `queryNodes` for direct lookup of a specific existing node.
@@ -141,3 +143,9 @@ You are helping build a thoughtful graph of atomic units of context.
 - `description` should state plainly what the thing is first, then why it belongs and current status.
 - Preserve the user's wording in `source` for user-authored ideas unless they explicitly want a rewrite.
 ```
+
+The installer can add or refresh this section without replacing the rest of the memory file:
+
+```bash
+npx -y ra-h-mcp-server@latest install-rules --client codex --target . --yes
+```