@memstack/server 0.5.0 → 0.7.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 (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +38 -5
  3. package/package.json +21 -15
  4. package/dist/index.js +0 -11874
  5. package/dist/index.js.map +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MemStack
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,23 +1,32 @@
1
1
  # @memstack/server
2
2
 
3
- REST API server for MemStack — self-hostable agent memory. Run anywhere Bun runs.
3
+ REST API server for MemStack — self-hostable agent memory. Runs on Node.js 18+ or Bun.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @memstack/server
9
9
  # or via Docker:
10
- docker pull ghcr.io/isiomac/memstack-server:v0.5.0
10
+ docker pull ghcr.io/isiomac/memstack-server:0.6.4
11
11
  ```
12
12
 
13
13
  ## Quick Start
14
14
 
15
15
  ```bash
16
+ # Node.js
17
+ npx @memstack/server
18
+ # or, if installed as a dependency:
19
+ node node_modules/@memstack/server/dist/serve.js
20
+
21
+ # Bun
16
22
  bun run node_modules/@memstack/server/dist/index.js
17
- # or via Docker:
18
- docker run -p 3000:3000 -e MEMSTACK_STORAGE=memory -e OPENAI_API_KEY=sk-... ghcr.io/isiomac/memstack-server:v0.5.0
23
+
24
+ # Docker
25
+ docker run -p 3000:3000 -e MEMSTACK_STORAGE=memory -e OPENAI_API_KEY=sk-... ghcr.io/isiomac/memstack-server:0.6.4
19
26
  ```
20
27
 
28
+ Under Node, `dist/serve.js` starts the server explicitly via [`@hono/node-server`](https://github.com/honojs/node-server). Under Bun, `dist/index.js`'s default export (`{ port, fetch }`) is auto-started by the Bun runtime — no extra wiring needed. Both entry points serve the same Hono app, so behavior is identical either way.
29
+
21
30
  ## Configuration
22
31
 
23
32
  All via environment variables.
@@ -33,6 +42,7 @@ All via environment variables.
33
42
  | `ANTHROPIC_API_KEY` | Anthropic LLM (summarization) | — |
34
43
  | `MEMSTACK_OPENAI_BASE_URL` | Custom API endpoint (DeepSeek, etc) | `https://api.openai.com/v1` |
35
44
  | `MEMSTACK_LLM_MODEL` | Model override | `gpt-4o-mini` |
45
+ | `MEMSTACK_EMBED_ON_STORE` | Auto-embed on store | `true` |
36
46
  | `MEMSTACK_API_KEY` | Bearer token auth (optional) | — |
37
47
  | `MEMSTACK_RATE_LIMIT` | Requests/minute limit | 0 (disabled) |
38
48
  | `PORT` | HTTP port | 3000 |
@@ -56,10 +66,30 @@ All via environment variables.
56
66
  | `GET` | `/v1/memories/count` | Count with filters |
57
67
  | `GET` | `/v1/memories/export` | Export snapshot |
58
68
  | `POST` | `/v1/summarize` | Compress old memories |
69
+ | `GET` | `/v1/summarize/stream` | Stream summary via SSE |
59
70
  | `POST` | `/v1/prune` | Remove stale memories |
60
71
  | `POST` | `/v1/prune/dry-run` | Preview prune |
61
72
  | `GET` | `/v1/stats/:actorId` | Memory diagnostics |
62
73
  | `GET` | `/health` | Health check |
74
+ | `GET` | `/openapi.json` | OpenAPI 3.1 spec, generated from the request-validation schemas below |
75
+
76
+ ## Request validation
77
+
78
+ Every `POST` body is validated against a [zod](https://zod.dev) schema before it reaches MemStack. Invalid requests get a `400` with details instead of a generic `500`:
79
+
80
+ ```bash
81
+ curl -X POST http://localhost:3000/v1/memories \
82
+ -H "Content-Type: application/json" \
83
+ -d '{"actorId":"agent-1","importance":5}'
84
+ # 400 { "error": "Validation failed", "issues": [
85
+ # { "path": ["content"], "message": "Required" },
86
+ # { "path": ["importance"], "message": "Number must be less than or equal to 1" }
87
+ # ]}
88
+ ```
89
+
90
+ `GET /openapi.json` serves the generated OpenAPI 3.1 document — paste it into [Swagger UI](https://swagger.io/tools/swagger-ui/), [Redoc](https://redocly.com/redoc), or Postman, or run it through an OpenAPI code generator to get a typed client in any language. The request-body schemas in the spec come from the same zod schemas that validate incoming requests, so they can't drift apart.
91
+
92
+ Note: `POST /v1/prune` and `/v1/prune/dry-run` support every `PruneStrategy` type except `"custom"` — a custom prune strategy is a JavaScript predicate function, which can't be expressed in JSON. Use the `@memstack/core` library directly for custom prune logic.
63
93
 
64
94
  ## Usage Examples
65
95
 
@@ -81,6 +111,9 @@ curl -X POST http://localhost:3000/v1/memories/retrieve \
81
111
  curl -X POST http://localhost:3000/v1/memories/context \
82
112
  -H "Content-Type: application/json" \
83
113
  -d '{"actorId":"agent-1","maxTokens":500}'
114
+
115
+ # Stream summarization (SSE)
116
+ curl -N "http://localhost:3000/v1/summarize/stream?actorId=agent-1&olderThan=2026-01-01T00:00:00Z"
84
117
  ```
85
118
 
86
119
  ## Docker
@@ -90,7 +123,7 @@ docker run -p 3000:3000 \
90
123
  -e MEMSTACK_STORAGE=postgres \
91
124
  -e DATABASE_URL=postgresql://... \
92
125
  -e OPENAI_API_KEY=sk-... \
93
- ghcr.io/isiomac/memstack-server:v0.5.0
126
+ ghcr.io/isiomac/memstack-server:0.6.4
94
127
  ```
95
128
 
96
129
  ## License
package/package.json CHANGED
@@ -1,9 +1,12 @@
1
1
  {
2
2
  "name": "@memstack/server",
3
- "version": "0.5.0",
4
- "description": "REST API server for MemStack \u2014 self-hostable agent memory",
3
+ "version": "0.7.0",
4
+ "description": "REST API server for MemStack — self-hostable agent memory",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
+ "bin": {
8
+ "memstack-server": "dist/serve.js"
9
+ },
7
10
  "exports": {
8
11
  ".": {
9
12
  "types": "./dist/index.d.ts",
@@ -25,22 +28,19 @@
25
28
  "url": "https://github.com/isiomaC/memstack/issues"
26
29
  },
27
30
  "homepage": "https://github.com/isiomaC/memstack",
28
- "scripts": {
29
- "build": "tsup src/index.ts --format esm --clean",
30
- "dev": "tsup src/index.ts --format esm --watch",
31
- "check": "tsc --noEmit",
32
- "test": "vitest run",
33
- "prepublishOnly": "npx tsc --noEmit && npx vitest run"
34
- },
35
31
  "dependencies": {
36
- "@memstack/core": "workspace:*",
37
- "hono": "^4.0.0"
32
+ "@hono/node-server": "^1.13.0",
33
+ "hono": "^4.0.0",
34
+ "zod": "^3.23.8",
35
+ "zod-to-json-schema": "^3.25.2",
36
+ "@memstack/config-env": "0.7.0",
37
+ "@memstack/core": "0.7.0"
38
38
  },
39
39
  "devDependencies": {
40
+ "@types/node": "^22.0.0",
40
41
  "tsup": "^8.0.0",
41
42
  "typescript": "^5.7.0",
42
- "vitest": "^1.0.0",
43
- "@types/node": "^22.0.0"
43
+ "vitest": "^1.0.0"
44
44
  },
45
45
  "keywords": [
46
46
  "api",
@@ -49,5 +49,11 @@
49
49
  "agent",
50
50
  "rest"
51
51
  ],
52
- "license": "MIT"
53
- }
52
+ "license": "MIT",
53
+ "scripts": {
54
+ "build": "tsup src/index.ts src/serve.ts --format esm --dts --clean",
55
+ "dev": "tsup src/index.ts src/serve.ts --format esm --dts --watch",
56
+ "check": "tsc --noEmit",
57
+ "test": "vitest run"
58
+ }
59
+ }