@danielzfliu/memory 1.0.0 → 1.0.2

package/README.md

@@ -1,51 +1,55 @@
+[![npm version](https://img.shields.io/npm/v/@danielzfliu/memory.svg)](https://www.npmjs.com/package/@danielzfliu/memory)
+
 # Memory
+
 A fully local Node.js library and REST API for storing, searching, and querying tagged text pieces using ChromaDB for vector storage and Ollama for embeddings + generation.
 
-## Prerequisites
+Two ways to use Memory:
 
-- **Node.js** ≥ 18
-- **Ollama** running locally ([install](https://ollama.com))
-- **ChromaDB** server running locally
+- REST API Server — Clone the repo and run a standalone HTTP server with CRUD, semantic search, and RAG endpoints.
+- npm Package — Install `@danielzfliu/memory` in your own project and use the classes directly, or embed the Express server in your app.
 
-### Start Ollama & pull models
+---
 
+## Prerequisites
+
+- Node.js ≥ 18
+- Ollama running locally ([install](https://ollama.com))
+- ChromaDB server running locally
+
+Pull the required models:
 ```bash
 ollama pull nomic-embed-text-v2-moe
 ollama pull llama3.2
-npm run ollama
 ```
 
-or on a specific port:
+---
 
-```bash
-npm run ollama:port 11435
-```
+## Option A: REST API Server
 
-### Start ChromaDB
-```bash
-npm run db
-```
+Use this option to run Memory as a standalone HTTP service.
 
-or on a specific port:
+### 1. Setup
 
 ```bash
-npm run db:port 9000
+git clone https://github.com/DanielZFLiu/memory.git
+cd memory
+npm install
 ```
 
-**Windows note:** If `chroma` is not recognized, the `Scripts` directory may not be on your PATH. Either add it (e.g. `%APPDATA%\Python\Python3xx\Scripts`) or run the executable directly:
-```powershell
-& "$env:APPDATA\Python\Python313\Scripts\chroma.exe" run --port 8000
-```
+### 2. Start external services
 
-## Install
+The repo includes convenience scripts for starting Ollama and ChromaDB:
 
 ```bash
-npm install
-```
+npm run ollama                     # start Ollama on default port 11434
+npm run ollama:port -- 11435       # start Ollama on a custom port
 
-## Usage
+npm run db                         # start ChromaDB on default port 8000
+npm run db:port -- 9000            # start ChromaDB on a custom port
+```
 
-### REST API Server
+### 3. Start the server
 
 ```bash
 npm run dev
@@ -113,10 +117,38 @@ Returns:
 }
 ```
 
-### Programmatic Usage (Library)
+---
+
+## Option B: npm Package
+
+Use this option to integrate Memory into your own Node.js/TypeScript project.
+
+### 1. Install
+
+```bash
+npm install @danielzfliu/memory
+```
+
+### 2. Start external services
+
+You are responsible for running Ollama and ChromaDB yourself:
+
+```bash
+ollama serve                       # default port 11434
+chroma run --port 8000             # default port 8000
+```
+
+**Windows note:** If `chroma` is not recognized, the `Scripts` directory may not be on your PATH. Either add it (e.g. `%APPDATA%\Python\Python3xx\Scripts`) or run the executable directly:
+```powershell
+& "$env:APPDATA\Python\Python313\Scripts\chroma.exe" run --port 8000
+```
+
+### 3. Programmatic usage
+
+#### Using PieceStore and RagPipeline directly
 
 ```typescript
-import { PieceStore, RagPipeline, MemoryConfig } from "memory";
+import { PieceStore, RagPipeline, MemoryConfig } from "@danielzfliu/memory";
 
 async function main() {
     const config: MemoryConfig = {
@@ -125,6 +157,7 @@ async function main() {
         embeddingModel: "nomic-embed-text-v2-moe",
     };
 
+    // Store: CRUD + semantic search
     const store = new PieceStore(config);
     await store.init();
 
@@ -146,7 +179,8 @@ async function main() {
     });
     console.log("filtered", filtered);
 
-    const rag = new RagPipeline(store, "http://localhost:11434", "llama3.2");
+    // RAG: retrieve relevant pieces → generate an answer via Ollama
+    const rag = new RagPipeline(store, config.ollamaUrl!, "llama3.2");
     const answer = await rag.query("What is TypeScript?", {
         tags: ["programming"],
     });
@@ -159,16 +193,52 @@ main().catch((err) => {
 });
 ```
 
+#### Embedding 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"));
+```
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `PieceStore` | CRUD + semantic search over tagged text pieces |
+| `RagPipeline` | Retrieve-then-generate pipeline using `PieceStore` + Ollama |
+| `EmbeddingClient` | Low-level Ollama embedding wrapper |
+| `createServer` | Express app factory with all REST endpoints pre-configured |
+| `MemoryConfig` | Configuration interface (all fields optional with defaults) |
+| `DEFAULT_MEMORY_CONFIG` | The default values for `MemoryConfig` |
+| `Piece` | `{ id, content, tags }` |
+| `QueryOptions` | `{ tags?, topK? }` |
+| `QueryResult` | `{ piece, score }` |
+| `RagResult` | `{ answer, sources }` |
+
+---
+
 ## Configuration (`MemoryConfig`)
 
+All 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` | Ollama model for embeddings |
-| `generationModel` | `llama3.2` | Ollama model for RAG generation |
+| `generationModel` | `llama3.2` | Ollama model for RAG generation (used by `createServer`) |
 | `collectionName` | `pieces` | ChromaDB collection name |
 
+> **Note:** `generationModel` is only used by `createServer`. When constructing `RagPipeline` directly, you pass the model name to its constructor.
+
 ## Testing
 
 ```bash
@@ -191,5 +261,6 @@ src/
 tests/
 ├── helpers/        # Shared test fixtures (in-memory ChromaDB mock, etc.)
 ├── unit/           # Unit tests (embeddings, store, rag)
+├── manual/         # Manual api tests (used by ai agents with access to terminal)
 └── integration/    # API integration tests (supertest)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@danielzfliu/memory",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "A local RAG system for storing, searching, and querying tagged text pieces using ChromaDB and Ollama",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -13,8 +13,7 @@
     "files": [
         "dist",
         "README.md",
-        "LICENSE",
-        "package_scripts"
+        "LICENSE"
     ],
     "repository": {
         "type": "git",

package/package_scripts/serve-chroma.js

@@ -1,17 +0,0 @@
-const { spawn } = require("child_process");
-
-// Get port from argument or default to 8000
-const port = process.argv[2] || "8000";
-
-console.log(`🚀 Starting ChromaDB on port ${port}`);
-
-const command = `chroma run --port ${port}`;
-
-const child = spawn(command, [], {
-    stdio: "inherit",
-    shell: true,
-});
-
-child.on("close", (code) => {
-    process.exit(code);
-});

package/package_scripts/serve-ollama.js

@@ -1,20 +0,0 @@
-const { spawn } = require("child_process");
-
-// Get the port from the command line argument, or default to 11434
-const port = process.argv[2] || "11434";
-
-console.log(`🚀 Starting Ollama on 127.0.0.1:${port}`);
-
-// Run the command with the modified environment variable
-const child = spawn("ollama serve", [], {
-    stdio: "inherit", // Show Ollama's output in your terminal
-    shell: true, // Ensure compatibility across OS
-    env: {
-        ...process.env, // Keep existing environment variables
-        OLLAMA_HOST: `127.0.0.1:${port}`,
-    },
-});
-
-child.on("close", (code) => {
-    process.exit(code);
-});