@datafrog-io/n2n-memory 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -6,25 +6,54 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.2.0] - 2025-01-12
+## [Unreleased]
+
+### Fixed
+- Normal reads now refresh cached graph/context snapshots when the underlying `.mcp` files change.
+- Existing but unreadable `memory.json` or `context.json` files now raise data integrity errors instead of being treated as empty state.
+- `n2n_create_relations` now rejects relations that reference missing entities.
+- `n2n_export_markdown` now rejects absolute output paths and relative paths that escape the project root.
+- `projectPath` validation now rejects relative paths before resolving them.
+- Production and development dependency audits now pass with zero vulnerabilities.
+
+### Changed
+- Clarified that `projectPath` must point to the project root or workspace top-level directory.
+- Refactored JSON storage writes through a shared atomic-write path and normalized graph copies before persisting.
+- Switched the test runner from Mocha to Vitest to keep the development dependency tree clean.
+- Tool discovery now exposes concrete JSON input schemas generated from the Zod schemas.
+- README-only directories are treated as weak roots and are rejected during project recognition.
+- Server logs hide full local paths by default unless `N2N_LOG_LEVEL=debug` is set.
+- Updated English and Chinese documentation to reflect the current tool set, storage contract, path containment rules, and graph integrity behavior.
+
+### Added
+- GitHub CI workflow for pull requests and pushes to `main`.
+- Hardened publish workflow that runs the full check suite before `npm publish`.
+- npm package `files` whitelist and richer package metadata.
+- Open-source governance files: contributing guide, security policy, code of conduct, issue templates, and PR template.
+
+## [1.2.1] - 2026-01-12
 
 ### Added
+- **Structured JSON Tool Responses**:
+  - Upgraded all tool responses from plain text to structured JSON.
+  - Added `status`, `message`, and `_protocol` metadata fields for better machine readability.
+- **Dynamic N2N-SYNC Protocol Reminders**:
+  - Implemented automatic injection of `[N2N-SYNC]` protocol reminders into `nextSteps`.
+  - Embedded protocol hints in tool metadata to guide AI assistants toward better synchronization habits.
 - **Similarity-Based Observation Deduplication**:
   - New `similarity.ts` utility module with Jaccard similarity, Levenshtein distance, and containment detection algorithms.
   - `addEntities()` and `addObservations()` now use intelligent deduplication instead of exact-match `Set` deduplication.
   - Automatically keeps the longer (more detailed) observation when duplicates are detected.
   - Prevents redundant entries like "version 2.4.1" and "version 2.4.1 is the current release" from coexisting.
-
 - **Fuzzy Search with Relevance Ranking**:
   - `n2n_search` tool now supports fuzzy matching by default.
   - New optional parameters: `fuzzy` (boolean) and `minScore` (0-1 threshold).
   - Search results are ranked by relevance score (highest first).
   - Handles typos via Levenshtein similarity.
   - Supports word-level partial matching and semantic similarity via Jaccard index.
-
 - **New Unit Tests**:
   - Comprehensive test suite for all similarity functions (`similarity.test.ts`).
-  - 99 tests passing.
+  - Expanded regression coverage for memory and search behavior.
 
 ## [1.1.0] - 2024-12-19
 

package/README.md

@@ -1,5 +1,7 @@
 # n2n-memory
 
+Project-local memory MCP server for AI coding agents.
+
 [![npm version](https://img.shields.io/npm/v/@datafrog-io/n2n-memory)](https://www.npmjs.com/package/@datafrog-io/n2n-memory)
 [![npm total downloads](https://img.shields.io/npm/dt/@datafrog-io/n2n-memory)](https://www.npmjs.com/package/@datafrog-io/n2n-memory)
 [![license](https://img.shields.io/github/license/n2ns/n2n-memory)](https://github.com/n2ns/n2n-memory/blob/main/LICENSE)
@@ -14,16 +16,56 @@
 
 > **Context as code. Memory as asset.**
 
-A specialized MCP server designed to solve "memory pollution" during AI-assisted cross-project development. It persists AI's cognitive fragments directly within each project's own directory.
+n2n-memory is an open-source, local-first Model Context Protocol (MCP) memory server for AI coding assistants. It prevents cross-project memory pollution by storing durable project knowledge in `.mcp/memory.json` and active task context in `.mcp/context.json` inside each repository.
+
+### Search-friendly positioning
+
+If you are searching for:
+- AI coding memory
+- project-local MCP memory
+- local-first context memory for coding agents
+- repository-isolated memory graph for Claude/Cursor/VS Code workflows
+
+This server is designed for these goals: deterministic JSON output, project isolation, and Git-friendly reviewability.
+
+## What Is n2n-memory?
+
+n2n-memory gives AI coding tools a project-local knowledge graph they can read and update through MCP. It is designed for developers and teams who use AI assistants across multiple repositories and want memory that is local, auditable, Git-friendly, and not mixed with unrelated projects.
+
+**TL;DR**
+- **Install**: `npx -y @datafrog-io/n2n-memory`
+- **Protocol**: Model Context Protocol (MCP), stdio transport
+- **Storage**: `.mcp/memory.json` for durable memory, `.mcp/context.json` for active task state
+- **Best for**: AI coding assistant memory, project architecture notes, shared team context
+- **Not for**: cloud sync, global personal memory, source code indexing, or vector database replacement
 
 ### 🌟 Key Highlights
-- **Project-Level Physical Isolation**: Memory files are stored at `[Project Root]/.mcp/memory.json`.
+- **Project-Level Physical Isolation**: Memory and active context are stored under `[Project Root]/.mcp/`.
 - **Git-Friendly**: JSON data is automatically sorted by key to generate clean and readable `git diff`.
+- **Dual-Buffer State**: Durable graph knowledge lives in `memory.json`; high-frequency task state lives in `context.json`.
 - **Tool Agnostic**: Uses the `.mcp` naming convention, not tied to any specific AI brand or IDE plugin.
 - **Assets for Your Code**: Memory stays with your code; team members can share AI's understanding of the architecture by simply pulling the repository.
-- **Universal Compatibility**: Works with all MCP-enabled models including **Claude 4.5**, **Gemini 3 Pro/Flash**, **GPT-5/5.2**, and **DeepSeek V3.2**.
+- **Universal Compatibility**: Works with MCP-enabled clients and AI coding tools that support stdio MCP servers.
 - **Privacy-First**: Built with security by design, keeping your data local and isolated.
 
+## Use Cases
+
+- Restore project context at the start of an AI coding session.
+- Preserve architecture decisions, implementation notes, known pitfalls, and active task state.
+- Share durable project memory with teammates through Git.
+- Keep memory isolated per repository when working across many client, product, or open-source projects.
+- Query a local project knowledge graph without adding a database or cloud service.
+
+## How It Compares
+
+| Approach | Best for | Tradeoff |
+| --- | --- | --- |
+| n2n-memory | Project-local MCP memory for AI coding agents | Requires assistants to call MCP tools intentionally |
+| Global MCP memory | Personal memory across many chats or projects | Can mix unrelated project context |
+| Markdown memory bank | Human-readable project notes | Less structured for graph queries and tool updates |
+| Vector database memory | Semantic retrieval over large corpora | Heavier infrastructure and less deterministic diffs |
+| IDE-specific rules | Steering assistant behavior in one IDE | Less portable across MCP clients |
+
 ### 🚀 Quick Start
 
 #### 1. Installation & Config (IDE / Claude Desktop)
@@ -50,29 +92,91 @@ Add in the MCP settings panel:
 - **Type**: `command`
 - **Command**: `npx -y @datafrog-io/n2n-memory`
 
+##### Other MCP clients
+- The server uses stdio MCP and can be wired to any MCP client that supports local command execution.
+- If your client supports it, set `N2N_LOG_LEVEL=debug` only when troubleshooting local path resolution.
+
 #### 2. Usage Guide
 
 This service is path-driven. AI assistants should pay attention to:
 
-1. **Absolute Paths**: When calling any `n2n_*` tool, the absolute path of the current project root (`projectPath`) must be provided.
-2. **Auto Storage**: Memory is automatically saved to `[ProjectPath]/.mcp/memory.json`.
-3. **Collaboration**: It is recommended to commit `.mcp/memory.json` to your Git repository to share the knowledge graph with your team.
+1. **Absolute Project Root**: When calling any `n2n_*` tool, provide the absolute path of the current project root or workspace top-level directory (`projectPath`).
+2. **Initialization Handshake**: If `.mcp` does not exist yet, call the tool again with `confirmNewProjectRoot` set to the detected root returned by the server.
+3. **Auto Storage**: Durable memory is saved to `[ProjectPath]/.mcp/memory.json`; active task context is saved to `[ProjectPath]/.mcp/context.json`.
+4. **Collaboration**: Commit `.mcp/memory.json` when the knowledge graph should be shared with the team. Commit `context.json` only if your workflow wants active task state shared.
+
+Recommended `.gitignore` policy for teams that want to share durable memory:
+
+```gitignore
+.mcp/context.json
+!.mcp/
+!.mcp/memory.json
+```
+
+If your project memory may contain private implementation details, keep the whole `.mcp/` directory ignored.
 
 ##### Available Tools:
 - `n2n_add_entities`: Create new entities.
 - `n2n_add_observations`: Append observations or facts.
-- `n2n_create_relations`: Establish connections between entities.
+- `n2n_create_relations`: Establish connections between existing entities.
 - `n2n_read_graph`: Read project memory and active context (Supports `summaryMode` and `pagination`).
 - `n2n_get_graph_summary`: Quickly fetch a lightweight index of all entities (Supports `pagination`).
 - `n2n_update_context`: Update current task status and next steps.
-- `n2n_search`: Search the graph via keywords (Supports `pagination`).
+- `n2n_search`: Search the graph via keyword or fuzzy matching (Supports `pagination`).
+- `n2n_delete_entities`: Remove entities and their attached relations.
+- `n2n_delete_observations`: Remove specific observations from entities.
+- `n2n_delete_relations`: Remove specific relations.
 - `n2n_open_nodes`: Retrieve specific entities by name.
+- `n2n_export_markdown`: Export the graph to a Markdown file inside the project root.
+
+##### Safety Notes:
+- Existing but unreadable JSON files are treated as data integrity errors, not as empty memory.
+- Export paths must be relative and must stay inside the project root.
+- Relations that point to missing entities are rejected.
+- Generic README-only folders are not treated as project roots; use a real project marker such as `.git`, `package.json`, or language-specific build files.
+- Full local paths are hidden from server logs by default. Set `N2N_LOG_LEVEL=debug` when diagnosing path issues.
 
 ### 🗺️ Future Roadmap
 - **Semantic Search**: Integration of minimalist Vector Embeddings for fuzzy memory retrieval.
 - **Ontology Enforcement**: Optional schema for relation type consistency.
 - **Time Travel**: Versioned snapshots for memory rollback.
 
+## Security and governance notes
+
+- `n2n_delete_entities`, `n2n_delete_observations`, and `n2n_delete_relations` are destructive and should be governed by review workflows.
+- Keep `context.json` uncommitted by default, and commit `.mcp/memory.json` only when team sharing is intentional.
+- See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+
+### Search disambiguation note
+
+`n2n-memory` is not a network VPN or mesh overlay project. It is an MCP memory server for AI coding agents.
+
+## FAQ
+
+### Is n2n-memory a vector database?
+
+No. n2n-memory stores a deterministic JSON knowledge graph. Semantic search may be added later, but the core design is structured, Git-friendly project memory.
+
+### Should I commit `.mcp/memory.json`?
+
+Commit `.mcp/memory.json` when the knowledge graph is useful to your team. Keep it ignored if it may contain private implementation details. `context.json` is active task state and is often better left uncommitted.
+
+### Does n2n-memory send data to the cloud?
+
+No. n2n-memory is a local MCP server. It reads and writes files under your project directory.
+
+### How is this different from global memory?
+
+Global memory follows the assistant or user across contexts. n2n-memory follows the repository, so unrelated projects do not contaminate each other's memory.
+
+### Does it work with Claude Desktop, Cursor, and VS Code?
+
+Yes, when the client supports stdio MCP servers. The README includes Claude Desktop and Cursor / VS Code MCP configuration examples.
+
+### Is this the same as a global AI memory store?
+
+No. This is a repository-scoped memory server. Each project gets its own `.mcp` workspace.
+
 ---
 
 ## 📖 Related Docs
@@ -81,10 +185,11 @@ This service is path-driven. AI assistants should pay attention to:
 - **[API Reference](./docs/API_REFERENCE.md)**: Tool descriptions and schema.
 - **[Development](./docs/DEVELOPMENT.md)**: How to build, test and extend.
 - **[Changelog](./CHANGELOG.md)**: Version history and incident recovery.
+- **[llms.txt](./llms.txt)**: Short AI-readable project summary for coding agents and answer engines.
 
 ## 📄 License
 This project is licensed under the [MIT License](./LICENSE).
 
 ---
 
-**N2N Studio** — The AI Innovation Lab of [DataFrog.io](https://datafrog.io).
+Built by N2NS Lab, the open-source lab from Datafrog, focused on practical AI developer tools.

package/build/core/memory-manager.js

@@ -6,16 +6,16 @@ export const CONTEXT_FILE_PATH = ".mcp/context.json";
 export class MemoryManager {
     static async readGraph(projectPath) {
         const filePath = path.resolve(projectPath, MEMORY_FILE_PATH);
+        if (!await fs.pathExists(filePath)) {
+            return { entities: [], relations: [] };
+        }
         try {
-            if (await fs.pathExists(filePath)) {
-                const data = await fs.readJson(filePath);
-                return KnowledgeGraphSchema.parse(data);
-            }
+            const data = await fs.readJson(filePath);
+            return KnowledgeGraphSchema.parse(data);
         }
         catch (error) {
-            console.error(`[MemoryManager] Read error at ${filePath}:`, error);
+            throw new Error(`Failed to read memory file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        return { entities: [], relations: [] };
     }
     /**
      * Writes the graph to disk atomically using a temporary file.
@@ -23,69 +23,34 @@ export class MemoryManager {
      */
     static async writeGraph(projectPath, graph) {
         const filePath = path.resolve(projectPath, MEMORY_FILE_PATH);
-        const tempPath = `${filePath}.${Date.now()}.tmp`;
-        const dirPath = path.dirname(filePath);
+        const normalizedGraph = this.normalizeGraphForStorage(graph);
         try {
-            // Git-friendly sorting
-            graph.entities.sort((a, b) => a.name.localeCompare(b.name));
-            graph.entities.forEach(entity => {
-                if (entity.observations) {
-                    entity.observations.sort();
-                }
-                else {
-                    entity.observations = [];
-                }
-            });
-            graph.relations.sort((a, b) => {
-                const fromComp = a.from.localeCompare(b.from);
-                if (fromComp !== 0)
-                    return fromComp;
-                const toComp = a.to.localeCompare(b.to);
-                if (toComp !== 0)
-                    return toComp;
-                return a.relationType.localeCompare(b.relationType);
-            });
-            await fs.ensureDir(dirPath);
-            // 1. Write to temporary file
-            await fs.writeJson(tempPath, graph, { spaces: 2 });
-            // 2. Atomic rename
-            await fs.move(tempPath, filePath, { overwrite: true });
+            await this.atomicWriteJson(filePath, normalizedGraph);
         }
         catch (error) {
-            // Cleanup temp file if it exists and write failed
-            if (await fs.pathExists(tempPath)) {
-                await fs.remove(tempPath);
-            }
             throw new Error(`Failed to write memory file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     static async readContext(projectPath) {
         const filePath = path.resolve(projectPath, CONTEXT_FILE_PATH);
+        if (!await fs.pathExists(filePath)) {
+            return { status: "PLANNING", nextSteps: [] };
+        }
         try {
-            if (await fs.pathExists(filePath)) {
-                const data = await fs.readJson(filePath);
-                return ProjectContextSchema.parse(data);
-            }
+            const data = await fs.readJson(filePath);
+            return ProjectContextSchema.parse(data);
         }
         catch (error) {
-            console.error(`[MemoryManager] Context read error at ${filePath}:`, error);
+            throw new Error(`Failed to read context file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        return { status: "PLANNING", nextSteps: [] };
     }
     static async writeContext(projectPath, context) {
         const filePath = path.resolve(projectPath, CONTEXT_FILE_PATH);
-        const tempPath = `${filePath}.${Date.now()}.tmp`;
-        const dirPath = path.dirname(filePath);
         try {
             context.updatedAt = new Date().toISOString();
-            await fs.ensureDir(dirPath);
-            await fs.writeJson(tempPath, context, { spaces: 2 });
-            await fs.move(tempPath, filePath, { overwrite: true });
+            await this.atomicWriteJson(filePath, context);
         }
         catch (error) {
-            if (await fs.pathExists(tempPath)) {
-                await fs.remove(tempPath);
-            }
             throw new Error(`Failed to write context file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -102,7 +67,7 @@ export class MemoryManager {
     }
     static async exportToMarkdown(projectPath, outputPath) {
         const graph = await this.readGraph(projectPath);
-        const filePath = path.resolve(projectPath, outputPath || "KNOWLEDGE_GRAPH.md");
+        const filePath = this.resolveProjectOutputPath(projectPath, outputPath || "KNOWLEDGE_GRAPH.md");
         let md = "# Knowledge Graph\n\n";
         md += `> Generated from \`${MEMORY_FILE_PATH}\`\n\n`;
         md += "## Entities\n\n";
@@ -137,5 +102,55 @@ export class MemoryManager {
         await fs.writeFile(filePath, md, "utf-8");
         return filePath;
     }
+    static normalizeGraphForStorage(graph) {
+        return {
+            entities: graph.entities
+                .map(entity => ({
+                ...entity,
+                observations: [...(entity.observations || [])].sort()
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            relations: [...graph.relations].sort((a, b) => {
+                const fromComp = a.from.localeCompare(b.from);
+                if (fromComp !== 0)
+                    return fromComp;
+                const toComp = a.to.localeCompare(b.to);
+                if (toComp !== 0)
+                    return toComp;
+                return a.relationType.localeCompare(b.relationType);
+            })
+        };
+    }
+    static async atomicWriteJson(filePath, data) {
+        const dirPath = path.dirname(filePath);
+        const tempPath = this.createTempPath(filePath);
+        try {
+            await fs.ensureDir(dirPath);
+            await fs.writeJson(tempPath, data, { spaces: 2 });
+            await fs.move(tempPath, filePath, { overwrite: true });
+        }
+        catch (error) {
+            if (await fs.pathExists(tempPath)) {
+                await fs.remove(tempPath);
+            }
+            throw error;
+        }
+    }
+    static createTempPath(filePath) {
+        const suffix = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+        return `${filePath}.${suffix}.tmp`;
+    }
+    static resolveProjectOutputPath(projectPath, outputPath) {
+        if (path.isAbsolute(outputPath)) {
+            throw new Error("Export outputPath must be relative to the project root.");
+        }
+        const projectRoot = path.resolve(projectPath);
+        const filePath = path.resolve(projectRoot, outputPath);
+        const relative = path.relative(projectRoot, filePath);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("Export outputPath must stay inside the project root.");
+        }
+        return filePath;
+    }
 }
 //# sourceMappingURL=memory-manager.js.map

package/build/core/memory-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-manager.js","sourceRoot":"","sources":["../../src/core/memory-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory-manager.js","sourceRoot":"","sources":["../../src/core/memory-manager.ts"],"names":[],"mappings":"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"}

package/build/core/memory-service.js

@@ -4,6 +4,7 @@ import fs from "fs-extra";
 import path from "path";
 import { deduplicateObservations, fuzzyMatchScore } from "../utils/similarity.js";
 import { MemoryManager, MEMORY_FILE_PATH, CONTEXT_FILE_PATH } from "./memory-manager.js";
+import { formatProjectPath, logError, logInfo } from "../utils/logging.js";
 /**
  * MemoryService - High reliability dual-buffer memory manager.
  * - Snapshot Buffer: Instant in-memory reads for both Graph and Context.
@@ -38,7 +39,7 @@ export class MemoryService {
      * Gracefully shuts down the service, releasing all active file locks.
      */
     async shutdown() {
-        console.error(`[MemoryService] Shutting down, releasing ${this.activeLocks.size} locks...`);
+        logInfo(`[MemoryService] Shutting down, releasing ${this.activeLocks.size} locks...`);
         const lockReleases = Array.from(this.activeLocks.values());
         await Promise.all(lockReleases.map(release => release().catch(() => { })));
         this.activeLocks.clear();
@@ -77,61 +78,47 @@ export class MemoryService {
     async loadSnapshot(projectPath) {
         this.touchProject(projectPath);
         const filePath = path.resolve(projectPath, MEMORY_FILE_PATH);
-        try {
-            if (await fs.pathExists(filePath)) {
-                const stats = await fs.stat(filePath);
-                const currentMtime = stats.mtimeMs;
-                if (this.snapshots.has(projectPath) && this.lastMtimes.get(projectPath) === currentMtime) {
-                    return this.snapshots.get(projectPath);
-                }
-                const graph = await MemoryManager.readGraph(projectPath);
-                this.snapshots.set(projectPath, graph);
-                this.lastMtimes.set(projectPath, currentMtime);
-                return graph;
+        if (await fs.pathExists(filePath)) {
+            const stats = await fs.stat(filePath);
+            const currentMtime = stats.mtimeMs;
+            if (this.snapshots.has(projectPath) && this.lastMtimes.get(projectPath) === currentMtime) {
+                return this.snapshots.get(projectPath);
             }
-        }
-        catch (error) {
-            console.error(`[MemoryService] Failed to load graph snapshot: ${error}`);
+            const graph = await MemoryManager.readGraph(projectPath);
+            this.snapshots.set(projectPath, graph);
+            this.lastMtimes.set(projectPath, currentMtime);
+            return graph;
         }
         const emptyGraph = { entities: [], relations: [] };
         this.snapshots.set(projectPath, emptyGraph);
+        this.lastMtimes.delete(projectPath);
         return emptyGraph;
     }
     async getGraph(projectPath) {
-        if (!this.snapshots.has(projectPath)) {
-            return await this.loadSnapshot(projectPath);
-        }
-        return this.snapshots.get(projectPath);
+        return await this.loadSnapshot(projectPath);
     }
     // --- Context Operations ---
     async loadContextSnapshot(projectPath) {
         this.touchProject(projectPath);
         const filePath = path.resolve(projectPath, CONTEXT_FILE_PATH);
-        try {
-            if (await fs.pathExists(filePath)) {
-                const stats = await fs.stat(filePath);
-                const currentMtime = stats.mtimeMs;
-                if (this.contextSnapshots.has(projectPath) && this.contextMtimes.get(projectPath) === currentMtime) {
-                    return this.contextSnapshots.get(projectPath);
-                }
-                const context = await MemoryManager.readContext(projectPath);
-                this.contextSnapshots.set(projectPath, context);
-                this.contextMtimes.set(projectPath, currentMtime);
-                return context;
+        if (await fs.pathExists(filePath)) {
+            const stats = await fs.stat(filePath);
+            const currentMtime = stats.mtimeMs;
+            if (this.contextSnapshots.has(projectPath) && this.contextMtimes.get(projectPath) === currentMtime) {
+                return this.contextSnapshots.get(projectPath);
             }
-        }
-        catch (error) {
-            console.error(`[MemoryService] Failed to load context snapshot: ${error}`);
+            const context = await MemoryManager.readContext(projectPath);
+            this.contextSnapshots.set(projectPath, context);
+            this.contextMtimes.set(projectPath, currentMtime);
+            return context;
         }
         const defaultContext = { status: "PLANNING", nextSteps: [] };
         this.contextSnapshots.set(projectPath, defaultContext);
+        this.contextMtimes.delete(projectPath);
         return defaultContext;
     }
     async getContext(projectPath) {
-        if (!this.contextSnapshots.has(projectPath)) {
-            return await this.loadContextSnapshot(projectPath);
-        }
-        return this.contextSnapshots.get(projectPath);
+        return await this.loadContextSnapshot(projectPath);
     }
     /**
      * Updates project context with independent locking.
@@ -169,11 +156,33 @@ export class MemoryService {
         });
     }
     // --- Combined Operations ---
+    /**
+     * Protocol reminder prefix for nextSteps.
+     * Used to inject and identify protocol reminders in context.
+     */
+    static PROTOCOL_PREFIX = "[N2N-SYNC]";
+    static PROTOCOL_REMINDER = `${MemoryService.PROTOCOL_PREFIX} Before 'git commit': call n2n_update_context to sync your progress.`;
+    /**
+     * Injects protocol reminder into nextSteps if not already present.
+     * Preserves user-defined nextSteps while ensuring protocol visibility.
+     */
+    injectProtocolReminder(context) {
+        const hasProtocolReminder = context.nextSteps.some(step => step.startsWith(MemoryService.PROTOCOL_PREFIX));
+        if (!hasProtocolReminder) {
+            return {
+                ...context,
+                nextSteps: [MemoryService.PROTOCOL_REMINDER, ...context.nextSteps]
+            };
+        }
+        return context;
+    }
     async getCompleteState(projectPath, options = {}) {
-        const [graph, context] = await Promise.all([
+        const [graph, rawContext] = await Promise.all([
             this.getGraph(projectPath),
             this.getContext(projectPath)
         ]);
+        // Inject protocol reminder into context.nextSteps
+        const context = this.injectProtocolReminder(rawContext);
         const totalEntityCount = graph.entities.length;
         const offset = options.offset || 0;
         const limit = options.limit || totalEntityCount;
@@ -232,7 +241,7 @@ export class MemoryService {
                 this.snapshots.set(projectPath, currentGraph);
             }
             catch (error) {
-                console.error(`[MemoryService] Write operation failed for ${projectPath}:`, error);
+                logError(`[MemoryService] Write operation failed for ${formatProjectPath(projectPath)}.`, error);
                 throw error;
             }
             finally {
@@ -282,6 +291,17 @@ export class MemoryService {
     }
     async createRelations(projectPath, relations) {
         await this.executeWrite(projectPath, (graph) => {
+            const entityNames = new Set(graph.entities.map(entity => entity.name));
+            const missingNames = new Set();
+            for (const relation of relations) {
+                if (!entityNames.has(relation.from))
+                    missingNames.add(relation.from);
+                if (!entityNames.has(relation.to))
+                    missingNames.add(relation.to);
+            }
+            if (missingNames.size > 0) {
+                throw new Error(`Cannot create relations with missing entities: ${Array.from(missingNames).sort().join(", ")}`);
+            }
             relations.forEach(newRel => {
                 const exists = graph.relations.some(r => r.from === newRel.from && r.to === newRel.to && r.relationType === newRel.relationType);
                 if (!exists) {