Smart Memory MCP
Relevant source files
The following files were used as context for generating this wiki page:
Smart Memory MCP is an enhanced implementation of the Model Context Protocol (MCP) memory server designed to provide automatic project context detection and namespacing. Unlike standard memory implementations that require manual prefixing, Smart Memory identifies the current working environment (e.g., LegalAI, AdHub, or eng-platform) to categorize and filter knowledge graph entities, observations, and relations automatically.
Sources: mcp-servers/smart-memory/README.md:1-10, mcp-servers/smart-memory/index.js:5-8
System Architecture
The Smart Memory MCP operates as a Node.js server using the @modelcontextprotocol/sdk. It serves as a persistent knowledge layer that interacts with AI agents (like Claude Code or Cursor) via standard input/output (Stdio). The system is built around a centralized JSON storage file that maintains a versioned record of entities and observations scoped by project contexts.
Sources: mcp-servers/smart-memory/index.js:154-165, mcp-servers/smart-memory/package.json:1-15
Context Detection Logic
The core differentiator of this system is its ability to detect the "namespace" or "project context" of a request without explicit user input. It employs three primary methods for detection:
- Git Remote Mapping: It executes
git config --get remote.origin.urland compares the result against patterns defined in the server configuration. - Working Directory Analysis: It analyzes the current working directory (
cwd) for project markers or signature files (e.g.,prisma/schema.prismafor LegalAI ornext.config.jsfor AdHub). - Fallback to Org: If no specific project is identified, or if the user is working within the
eng-platformrepository, the system defaults to theorg(organization-wide) namespace.
Sources: mcp-servers/smart-memory/index.js:77-111, mcp-servers/smart-memory/README.md:15-25
The diagram above illustrates the multi-step context detection flow used to determine the storage namespace.
Sources: mcp-servers/smart-memory/index.js:77-111
Data Structure and Storage
Memory is stored in a single JSON file, typically located at .shared/team-memory.json to facilitate team-wide synchronization via Git.
Memory Schema
| Field | Type | Description |
|---|---|---|
version | String | Semantic version of the memory structure (e.g., "1.0.0"). |
last_updated | ISO Date | Timestamp of the most recent modification. |
entities | Object | Map of context-prefixed keys to entity objects containing metadata and observations. |
observations | Array | Flat list of observation objects including scope, author, and classification data. |
relations | Array | List of links between entities (e.g., A is part of B). |
Sources: mcp-servers/smart-memory/index.js:125-133, mcp-servers/README-SETUP.md:120-130
Observation Classification
Observations are classified as either org (org-wide standards) or project-specific based on keyword heuristics. Content containing phrases like "team standard" or "documentation standard" is automatically routed to the org scope, while references to "this project" or "database schema" remain project-scoped.
Sources: mcp-servers/smart-memory/index.js:174-210
Tool Definitions
The Smart Memory MCP exposes several tools through the MCP SDK to allow agents to manipulate and query the knowledge graph.
| Tool Name | Parameters | Purpose |
|---|---|---|
create_entity | name, type, observations | Creates a new entity. The context is auto-detected and prefixed to the name. |
create_observation | content | Adds a new observation. Heuristics determine if it is org or project scoped. |
search_memories | query, context (opt) | Searches for entities and observations, optionally filtered by a specific namespace. |
get_current_context | None | Returns the current auto-detected project name and working directory. |
Sources: mcp-servers/smart-memory/index.js:264-306, mcp-servers/smart-memory/README.md:76-81
Execution and Synchronization
Git-Based Sync Workflow
To ensure knowledge is shared across the engineering team, the platform utilizes a Git synchronization workflow:
- Pull: Developers pull the latest
team-memory.jsonfrom the repository. - Interact: AI agents use MCP tools to read/write to the local memory file.
- Push: Updated memory files are committed and pushed to the shared repository.
Sources: mcp-servers/README-SETUP.md:100-115
Sequence of an Observation Creation
Sequence illustrating the process from an agent request to a namespaced persistent update.
Sources: mcp-servers/smart-memory/index.js:220-250, mcp-servers/smart-memory/README.md:30-45
Testing and Validation
Validation is performed using a test-memory.js script that ensures syntax correctness, memory creation, and file persistence. Successful tests verify that entities (e.g., legalai_trpc_routers) are correctly linked to their parent systems (e.g., legalai_system) with appropriate metadata including author attribution.
Sources: mcp-servers/TEST_RESULTS.md:10-35, mcp-servers/README-SETUP.md:75-90
Smart Memory MCP provides a robust, low-friction method for maintaining a shared team knowledge graph across multiple projects by automating context management and providing developer-centric tools.