@danielzfliu/memory 2.0.0 → 2.2.0

package/dist/types.d.ts

@@ -4,12 +4,15 @@ export interface Piece {
     title?: string;
     tags: string[];
 }
+export type RequestLoggingMode = "off" | "metadata" | "body";
 export interface MemoryConfig {
     chromaUrl?: string;
     ollamaUrl?: string;
     embeddingModel?: string;
     generationModel?: string;
     collectionName?: string;
+    requestLogging?: RequestLoggingMode;
+    corsOrigins?: string[];
 }
 export interface QueryOptions {
     tags?: string[];

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,EAAE,CAAC;CAC1B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,YAAY;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,EAAE,CAAC;CAC1B"}

package/docs/README.md

@@ -0,0 +1,9 @@
+# Documentation
+
+Use this index to find the authoritative guide for each topic:
+
+- [Getting Started](./getting-started.md): local clone setup, Ollama, ChromaDB, and how to choose a mode
+- [MCP Server](./mcp-server.md): stdio usage and available MCP tools
+- [npm Package](./npm-package.md): programmatic usage and public exports
+- [REST API](./rest-api.md): HTTP server startup and endpoint contract
+- [Configuration](./configuration.md): runtime options and environment variable overrides

package/docs/configuration.md

@@ -0,0 +1,55 @@
+# Configuration
+
+All `MemoryConfig` fields are optional. Defaults are applied automatically.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `chromaUrl` | `http://localhost:8000` | ChromaDB server URL |
+| `ollamaUrl` | `http://localhost:11434` | Ollama server URL |
+| `embeddingModel` | `nomic-embed-text-v2-moe:latest` | Ollama model for embeddings |
+| `generationModel` | `gemma3:latest` | Ollama model for RAG generation |
+| `collectionName` | `pieces` | Default ChromaDB collection name |
+| `requestLogging` | `off` | REST request logging mode: `off`, `metadata`, or `body` |
+| `corsOrigins` | `[]` | Optional allowlist of browser origins permitted to receive CORS headers |
+
+`generationModel` is used by `createServer` and `MemoryMcpServer`. When constructing `RagPipeline` directly, pass the model name to its constructor.
+
+`requestLogging: "metadata"` logs method, URL, status, duration, and collection when present.
+
+`requestLogging: "body"` additionally logs the JSON request body. This should stay opt-in because queries and stored content may be sensitive.
+
+`corsOrigins` enables CORS only for the listed origins. When empty, the REST API does not emit CORS headers.
+
+For safety, keep `corsOrigins` explicit and avoid permissive wildcards for non-local use.
+
+## Environment variable overrides
+
+Runtime configuration can be overridden with either `MEMORY_*` or non-prefixed environment variable names:
+
+| Config field | Supported environment variables |
+|-------------|----------------------------------|
+| `chromaUrl` | `MEMORY_CHROMA_URL`, `CHROMA_URL` |
+| `ollamaUrl` | `MEMORY_OLLAMA_URL`, `OLLAMA_URL` |
+| `embeddingModel` | `MEMORY_EMBEDDING_MODEL`, `EMBEDDING_MODEL` |
+| `generationModel` | `MEMORY_GENERATION_MODEL`, `GENERATION_MODEL` |
+| `collectionName` | `MEMORY_COLLECTION_NAME`, `COLLECTION_NAME` |
+| `requestLogging` | `MEMORY_REQUEST_LOGGING`, `REQUEST_LOGGING` |
+| `corsOrigins` | `MEMORY_CORS_ORIGINS`, `CORS_ORIGINS` |
+
+For `requestLogging`, supported values are `off`, `metadata`, and `body`.
+
+For `corsOrigins`, provide a comma-separated list such as `http://localhost:5173,https://notes.example.com`.
+
+## Example
+
+```typescript
+import { createServer } from "@danielzfliu/memory";
+
+const app = createServer({
+    chromaUrl: process.env.MEMORY_CHROMA_URL,
+    ollamaUrl: process.env.MEMORY_OLLAMA_URL,
+    collectionName: "agent-alice",
+    requestLogging: "metadata",
+    corsOrigins: ["http://localhost:5173"],
+});
+```

package/docs/getting-started.md

@@ -0,0 +1,71 @@
+# Getting Started
+
+## Prerequisites
+
+- **Node.js** `>= 18`
+- **Ollama** running locally
+- **ChromaDB** server running locally
+
+## Clone and install
+
+```bash
+git clone https://github.com/DanielZFLiu/memory.git
+cd memory
+npm install
+```
+
+## Set up Ollama
+
+Install Ollama from [ollama.com](https://ollama.com), then pull the default models:
+
+```bash
+ollama pull nomic-embed-text-v2-moe:latest
+ollama pull gemma3:latest
+```
+
+Start Ollama:
+
+```bash
+npm run ollama               # start Ollama on port 11434
+npm run ollama:port -- 11435 # start Ollama on a custom port
+```
+
+## Set up ChromaDB
+
+### Option 1: Docker
+
+The repository includes `docker-compose.yml` for running ChromaDB and persisting data in `./chroma/`.
+
+```bash
+npm run docker:up
+npm run docker:logs
+npm run docker:down
+```
+
+This exposes ChromaDB on `http://localhost:8000`.
+
+### Option 2: pip
+
+```bash
+pip install chromadb
+chroma run --port 8000
+```
+
+You may need to add Python's Scripts directory to your `PATH` after installation.
+
+### Option 3: npm helper script
+
+If `chroma` is already available on your machine, you can also run:
+
+```bash
+npm run db               # start ChromaDB on port 8000
+npm run db:port -- 8001  # start ChromaDB on a custom port
+```
+
+## Choose a usage mode
+
+- [MCP Server](./mcp-server.md)
+- [npm Package](./npm-package.md)
+- [REST API](./rest-api.md)
+
+See [Configuration](./configuration.md) for runtime options and supported environment variables.

package/docs/mcp-server.md

@@ -0,0 +1,61 @@
+# MCP Server
+
+Use Memory as a standalone Model Context Protocol server over stdio.
+
+After completing [Getting Started](./getting-started.md), run the MCP server from a local clone with:
+
+```bash
+npm run build
+node ./dist/main.js
+```
+
+Memory MCP communicates over stdio, so it does not open an HTTP port.
+
+## Run via `npx`
+
+In an MCP client configuration, you can run the published package directly:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@danielzfliu/memory"]
+    }
+  }
+}
+```
+
+If you are running from a local clone instead:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["c:/path/to/memory/dist/main.js"]
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `add_piece` | Add a new piece with optional title, tags, and collection |
+| `get_piece` | Retrieve a piece by id |
+| `update_piece` | Update piece content, title, and/or tags; `title: null` clears the title |
+| `delete_piece` | Delete a piece by id |
+| `query_pieces` | Semantic search over stored pieces; supports optional hybrid search |
+| `rag_query` | Retrieve relevant pieces and generate a grounded answer with citations |
+| `list_collections` | List all collection names in the memory store |
+| `delete_collection` | Delete an entire collection and all its pieces |
+
+All piece-level tools accept an optional `collection` parameter to target a specific collection instead of the default collection.
+
+There is no separate `create_collection` MCP tool. Collections are created implicitly the first time an agent writes to a new collection.
+
+## Configuration
+
+The MCP server uses the same runtime configuration as the library and REST API. See [Configuration](./configuration.md).

package/docs/npm-package.md

@@ -0,0 +1,100 @@
+# npm Package
+
+Install Memory into your own Node.js or TypeScript project:
+
+```bash
+npm install @danielzfliu/memory
+```
+
+## Programmatic usage
+
+The examples below are written in TypeScript.
+
+### Use `PieceStore` and `RagPipeline`
+
+```typescript
+import { PieceStore, RagPipeline, MemoryConfig } from "@danielzfliu/memory";
+
+async function main() {
+    const config: MemoryConfig = {
+        chromaUrl: "http://localhost:8000",
+        ollamaUrl: "http://localhost:11434",
+        embeddingModel: "nomic-embed-text-v2-moe:latest",
+    };
+
+    const store = new PieceStore(config);
+    await store.init();
+
+    await store.addPiece(
+        "TypeScript is a typed superset of JavaScript.",
+        ["typescript", "programming"],
+        "TypeScript overview",
+    );
+
+    const results = await store.queryPieces("typed languages", { topK: 5 });
+    console.log("results", results);
+
+    const filtered = await store.queryPieces("typed languages", {
+        tags: ["typescript"],
+        topK: 5,
+    });
+    console.log("filtered", filtered);
+
+    const hybrid = await store.queryPieces("typed languages", {
+        topK: 5,
+        useHybridSearch: true,
+    });
+    console.log("hybrid", hybrid);
+
+    const rag = new RagPipeline(store, config.ollamaUrl!, "gemma3:latest");
+    const answer = await rag.query("What is TypeScript?", {
+        tags: ["programming"],
+    });
+    console.log("answer", answer);
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+```
+
+### Embed the REST API in your own Express app
+
+`createServer` returns a configured Express app you can mount or extend:
+
+```typescript
+import { createServer } from "@danielzfliu/memory";
+
+const app = createServer({
+    chromaUrl: "http://localhost:8000",
+    ollamaUrl: "http://localhost:11434",
+});
+
+app.listen(4000, () => console.log("Running on :4000"));
+```
+
+`createServer` exposes the full REST surface.
+
+If you are building your own app or dashboard directly on the library, `PieceStore` also exposes lower-level collection and listing helpers such as `createCollection`, `listCollections`, `listPieces`, and `listTags`.
+
+## Public exports
+
+| Export | Description |
+|--------|-------------|
+| `PieceStore` | CRUD and semantic search over tagged text pieces |
+| `RagPipeline` | Retrieve-then-generate pipeline using `PieceStore` and Ollama |
+| `EmbeddingClient` | Low-level Ollama embedding wrapper |
+| `MemoryMcpServer` | MCP server class for stdio transport |
+| `createServer` | Express app factory with REST endpoints pre-configured |
+| `MemoryConfig` | Configuration interface |
+| `DEFAULT_MEMORY_CONFIG` | Default resolved configuration values |
+| `RequestLoggingMode` | REST request logging mode: `off`, `metadata`, or `body` |
+| `Piece` | `{ id, content, title?, tags }` |
+| `QueryOptions` | `{ tags?, topK?, useHybridSearch? }` |
+| `QueryResult` | `{ piece, score }` |
+| `RagResult` | `{ answer, sources }` |
+
+## Configuration
+
+See [Configuration](./configuration.md) for defaults and environment variable overrides.