@utaba/deep-memory-local-mcp-server 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +100 -15
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,27 +1,92 @@
1
1
  # @utaba/deep-memory-local-mcp-server
2
2
 
3
- Local MCP server that exposes [@utaba/deep-memory](https://www.npmjs.com/package/@utaba/deep-memory) as Model Context Protocol tools. Designed for AI agents (Claude Code, Claude Desktop, etc.) to interact with knowledge graphs over stdio.
3
+ Local MCP server that exposes [@utaba/deep-memory](https://www.npmjs.com/package/@utaba/deep-memory) as Model Context Protocol tools. Gives AI agents (Claude Desktop, Claude Code, and any other MCP-capable client) persistent, structured memory backed by a knowledge graph — accessed over stdio.
4
4
 
5
- > **Note:** Indexing pipeline tools live in a separate server — [`@utaba/deep-memory-indexer-mcp-server`](https://www.npmjs.com/package/@utaba/deep-memory-indexer-mcp-server). This server focuses on memory repository operations only.
5
+ ## Quick start — Claude Desktop / Claude Code
6
6
 
7
- ## Installation
7
+ Memory is only useful if it survives restarts. The recommended setup runs a local SQL Server in Docker — everything stays on your machine, the database survives reboots, and you don't have to manage anything once it's installed.
8
8
 
9
- ```bash
10
- pnpm add @utaba/deep-memory @utaba/deep-memory-local-mcp-server
9
+ **Full step-by-step (Windows / Mac / Linux):** [quickstart-claude-desktop.md](https://github.com/TjWheeler/deep-memory/blob/main/quickstart-claude-desktop.md) — three installers + one config file, around 15 minutes.
10
+
11
+ The summary version: install Docker Desktop and Node.js, download the project ZIP, run `docker compose up sqlserver -d`, create the `deep-memory` database, then paste this into your MCP client's config:
12
+
13
+ **Mac / Linux:**
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "deep-memory": {
19
+ "command": "npx",
20
+ "args": ["-y", "@utaba/deep-memory-local-mcp-server"],
21
+ "env": {
22
+ "DEEP_MEMORY_ACTOR_ID": "claude-desktop",
23
+ "DEEP_MEMORY_ACTOR_TYPE": "agent",
24
+ "DEEP_MEMORY_STORAGE": "sqlserver",
25
+ "DEEP_MEMORY_SQL_HOST": "localhost",
26
+ "DEEP_MEMORY_SQL_PORT": "1435",
27
+ "DEEP_MEMORY_SQL_DATABASE": "deep-memory",
28
+ "DEEP_MEMORY_SQL_USER": "sa",
29
+ "DEEP_MEMORY_SQL_PASSWORD": "DeepMem@Dev1234",
30
+ "DEEP_MEMORY_SQL_TRUST_CERT": "true"
31
+ }
32
+ }
33
+ }
34
+ }
35
+ ```
36
+
37
+ **Windows** (the `cmd /c` wrapper is needed so the launcher can resolve `npx`):
38
+
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "deep-memory": {
43
+ "command": "cmd",
44
+ "args": ["/c", "npx", "-y", "@utaba/deep-memory-local-mcp-server"],
45
+ "env": {
46
+ "DEEP_MEMORY_ACTOR_ID": "claude-desktop",
47
+ "DEEP_MEMORY_ACTOR_TYPE": "agent",
48
+ "DEEP_MEMORY_STORAGE": "sqlserver",
49
+ "DEEP_MEMORY_SQL_HOST": "localhost",
50
+ "DEEP_MEMORY_SQL_PORT": "1435",
51
+ "DEEP_MEMORY_SQL_DATABASE": "deep-memory",
52
+ "DEEP_MEMORY_SQL_USER": "sa",
53
+ "DEEP_MEMORY_SQL_PASSWORD": "DeepMem@Dev1234",
54
+ "DEEP_MEMORY_SQL_TRUST_CERT": "true"
55
+ }
56
+ }
57
+ }
58
+ }
11
59
  ```
12
60
 
13
- ## Claude Code / Desktop Integration
61
+ **Config file locations:**
62
+
63
+ | Client | Path |
64
+ |--------|------|
65
+ | Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
66
+ | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
67
+ | Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
68
+ | Claude Code | `.mcp.json` at your project root, or `~/.mcp.json` for global |
14
69
 
15
- Add to `.mcp.json` at your project root:
70
+ The password and port above match the bundled `docker-compose.yml` in the project repo — change them in both places if you customise the database setup. CosmosDB Gremlin is also supported; see the [project repository](https://github.com/TjWheeler/deep-memory) for that path.
71
+
72
+ > **Security — change the default password.** `DeepMem@Dev1234` is a publicly known development default. Anyone who can reach your machine on port 1435 can read your entire memory with it. Before you put anything personal or sensitive into the database, change the `SA_PASSWORD` / `MSSQL_SA_PASSWORD` in `docker-compose.yml` (and the matching `DEEP_MEMORY_SQL_PASSWORD` in the MCP config above) to a strong, unique password. The default is only safe when the database is bound to `localhost` on a trusted machine.
73
+
74
+ Quit and reopen the MCP client. The server should show as connected with around 28 memory tools.
75
+
76
+ ## Test-only configuration (in-memory)
77
+
78
+ > **Use this only to verify the install works. Do not use it as your real memory — it is wiped every time the server restarts.**
79
+
80
+ If you just want to confirm the MCP server connects before going through the database setup, you can run with no storage at all:
16
81
 
17
82
  ```json
18
83
  {
19
84
  "mcpServers": {
20
85
  "deep-memory": {
21
- "command": "node",
22
- "args": ["node_modules/@utaba/deep-memory-local-mcp-server/dist/index.js"],
86
+ "command": "npx",
87
+ "args": ["-y", "@utaba/deep-memory-local-mcp-server"],
23
88
  "env": {
24
- "DEEP_MEMORY_ACTOR_ID": "mcp-agent",
89
+ "DEEP_MEMORY_ACTOR_ID": "test",
25
90
  "DEEP_MEMORY_ACTOR_TYPE": "agent"
26
91
  }
27
92
  }
@@ -29,18 +94,38 @@ Add to `.mcp.json` at your project root:
29
94
  }
30
95
  ```
31
96
 
32
- Restart Claude Code after editing `.mcp.json`.
97
+ (On Windows, use the `cmd /c npx ...` form from above.) Once you've confirmed the tools are wired up, switch to the SQL Server configuration above before storing anything you want to keep.
33
98
 
34
- ## Configuration
99
+ ## Configuration reference
35
100
 
36
- Environment variables:
101
+ Environment variables passed via the MCP client's `env` block:
37
102
 
38
103
  | Variable | Default | Description |
39
104
  |----------|---------|-------------|
40
105
  | `DEEP_MEMORY_ACTOR_ID` | `mcp-agent` | Actor ID stamped on provenance |
41
106
  | `DEEP_MEMORY_ACTOR_TYPE` | `agent` | Actor type: `agent`, `human`, or `system` |
107
+ | `DEEP_MEMORY_STORAGE` | `memory` | `memory` (test only — wiped on restart) or `sqlserver` (recommended) |
108
+ | `DEEP_MEMORY_SQL_HOST` | — | SQL Server hostname (when `DEEP_MEMORY_STORAGE=sqlserver`) |
109
+ | `DEEP_MEMORY_SQL_PORT` | `1433` | SQL Server port. The bundled `docker-compose.yml` publishes the container on host port **1435** (to avoid clashing with any local SQL install on the default 1433); use `1435` for that path. For a different SQL Server instance, check the port that instance is listening on. |
110
+ | `DEEP_MEMORY_SQL_DATABASE` | — | Database name |
111
+ | `DEEP_MEMORY_SQL_USER` | — | SQL Server username |
112
+ | `DEEP_MEMORY_SQL_PASSWORD` | — | SQL Server password |
113
+ | `DEEP_MEMORY_SQL_SCHEMA` | `dbo` | SQL Server schema |
114
+ | `DEEP_MEMORY_SQL_TRUST_CERT` | `false` | Trust self-signed certificates (set `true` for local Docker) |
115
+ | `DEEP_MEMORY_EMBEDDINGS_BASE_URL` | — | Embeddings API URL (enables semantic search). See [quickstart-embeddings.md](https://github.com/TjWheeler/deep-memory/blob/main/quickstart-embeddings.md) for provider-specific recipes. |
116
+ | `DEEP_MEMORY_EMBEDDINGS_MODEL` | — | Embeddings model identifier |
117
+ | `DEEP_MEMORY_EMBEDDINGS_DIMENSIONS` | auto-detected | Embedding vector dimensionality. Set only when the model supports configurable dimensions (e.g. OpenAI `text-embedding-3-*`). |
118
+ | `DEEP_MEMORY_EMBEDDINGS_API_KEY` | — | API key for authenticated embeddings endpoints |
119
+
120
+ ## Programmatic use
121
+
122
+ If you're embedding the server into your own code rather than launching it from an MCP client, install it as a dependency:
123
+
124
+ ```bash
125
+ pnpm add @utaba/deep-memory @utaba/deep-memory-local-mcp-server
126
+ ```
42
127
 
43
- The server uses `InMemoryStorageProvider` and `InMemorySearchProvider` by default — all data is lost on restart. For persistent storage, wire up your own server using the core library directly with a storage provider like `@utaba/deep-memory-storage-sqlserver` or `@utaba/deep-memory-storage-cosmosdb`.
128
+ The package exports the same entry point its `bin` invokes — see the [project repository](https://github.com/TjWheeler/deep-memory) for examples.
44
129
 
45
130
  ## Tools (28)
46
131
 
@@ -140,4 +225,4 @@ The streaming variants avoid buffering the entire repository in memory. The buff
140
225
  ## See also
141
226
 
142
227
  - [`@utaba/deep-memory`](https://www.npmjs.com/package/@utaba/deep-memory) — the underlying graph memory library
143
- - [`@utaba/deep-memory-indexer-mcp-server`](https://www.npmjs.com/package/@utaba/deep-memory-indexer-mcp-server) — sibling MCP server for driving the indexing pipeline
228
+ - [Project repository](https://github.com/TjWheeler/deep-memory) — source, quickstarts, starter kits, and the document-indexing pipeline (run from a clone of the repo)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@utaba/deep-memory-local-mcp-server",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Local MCP server exposing @utaba/deep-memory as tools for AI agents",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -48,10 +48,10 @@
48
48
  ],
49
49
  "dependencies": {
50
50
  "@modelcontextprotocol/sdk": "^1.28.0",
51
- "@utaba/deep-memory-storage-cosmosdb": "0.16.0",
52
- "@utaba/deep-memory": "0.16.0",
53
- "@utaba/deep-memory-storage-sqlserver": "0.16.0",
54
- "@utaba/deep-memory-embeddings-openai": "0.16.0"
51
+ "@utaba/deep-memory": "0.17.0",
52
+ "@utaba/deep-memory-storage-cosmosdb": "0.17.0",
53
+ "@utaba/deep-memory-storage-sqlserver": "0.17.0",
54
+ "@utaba/deep-memory-embeddings-openai": "0.17.0"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^22.0.0",