memshell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 justedv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+<div align="center">
+
+<h1>mem.sh</h1>
+
+<p><strong>Persistent memory for AI agents.</strong><br>One line to save. One line to recall.</p>
+
+[![npm version](https://img.shields.io/npm/v/mem.sh.svg?style=flat-square)](https://www.npmjs.com/package/mem.sh)
+[![license](https://img.shields.io/npm/l/mem.sh.svg?style=flat-square)](https://github.com/justedv/mem.sh/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/mem.sh.svg?style=flat-square)](https://www.npmjs.com/package/mem.sh)
+[![GitHub stars](https://img.shields.io/github/stars/justedv/mem.sh?style=flat-square)](https://github.com/justedv/mem.sh)
+
+<br>
+
+[Quick Start](#quick-start) · [SDK](#sdk) · [API Server](#api-server) · [Architecture](#how-it-works) · [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## Why mem.sh?
+
+Agents forget everything between sessions. **mem.sh** gives them a brain.
+
+| | mem.sh | LangChain Memory | Roll your own |
+|---|---|---|---|
+| **Setup** | `npx mem.sh set "..."` | 47 dependencies + config | Hours of boilerplate |
+| **External APIs** | None | OpenAI key required | Depends |
+| **Semantic search** | Built-in TF-IDF | Embedding models | You build it |
+| **Storage** | SQLite (local) | Varies | You choose |
+| **Lines of code** | ~1 | ~50+ | ~200+ |
+
+## Features
+
+- **Fast** — TF-IDF vectorization with cosine similarity, instant results
+- **Local-first** — SQLite storage at `~/.mem/mem.db`, no data leaves your machine
+- **Semantic** — Recall by meaning, not exact match
+- **Zero config** — `npx` and go. No API keys, no setup, no dependencies
+
+## Quick Start
+
+### CLI
+
+```bash
+# Store a memory
+npx mem.sh set "user prefers dark mode"
+
+# Recall semantically
+npx mem.sh recall "what theme does the user like?"
+# → user prefers dark mode (score: 0.87)
+
+# List all memories
+npx mem.sh list
+
+# Forget a specific memory
+npx mem.sh forget <id>
+
+# Wipe everything
+npx mem.sh clear
+```
+
+### SDK
+
+```js
+const mem = require('mem.sh');
+
+// Store
+await mem.set('user prefers dark mode');
+await mem.set('favorite language is rust', { agent: 'coder-bot' });
+
+// Recall (semantic search)
+const results = await mem.recall('what does the user like?');
+// [{ id, text, score, created_at }]
+
+// List all
+const all = await mem.list();
+
+// Delete
+await mem.forget(id);
+
+// Clear everything
+await mem.clear();
+```
+
+## How It Works
+
+mem.sh uses **TF-IDF vectorization** with **cosine similarity** for semantic search. No OpenAI key needed. No external APIs. Everything runs locally.
+
+Memories are stored in `~/.mem/mem.db` (SQLite). Each memory is tokenized and vectorized on write. Queries are vectorized at recall time and ranked by cosine similarity against stored vectors.
+
+→ [Full architecture docs](docs/ARCHITECTURE.md)
+
+## API Server
+
+Run a shared memory server for multiple agents:
+
+```bash
+npx mem.sh serve --port 3456 --key my-secret-key
+```
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/mem` | Store a memory |
+| `GET` | `/mem/recall?q=` | Semantic recall |
+| `GET` | `/mem/list` | List all memories |
+| `DELETE` | `/mem/:id` | Delete a memory |
+| `DELETE` | `/mem` | Clear all memories |
+
+### Headers
+
+- `X-Mem-Key` — API key (required if `--key` is set)
+- `X-Mem-Agent` — Agent namespace (optional, isolates memories per agent)
+
+### Example
+
+```bash
+# Store
+curl -X POST http://localhost:3456/mem \
+  -H "Content-Type: application/json" \
+  -H "X-Mem-Key: my-secret-key" \
+  -d '{"text": "user prefers dark mode"}'
+
+# Recall
+curl "http://localhost:3456/mem/recall?q=theme+preference" \
+  -H "X-Mem-Key: my-secret-key"
+```
+
+### SDK with API Mode
+
+```js
+const mem = require('mem.sh');
+
+mem.configure({
+  api: 'http://localhost:3456',
+  key: 'my-secret-key',
+  agent: 'my-bot'
+});
+
+await mem.set('user prefers dark mode');
+const results = await mem.recall('theme preference');
+```
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[ISC](LICENSE)
+
+---
+
+<div align="center">
+<sub>Built for agents that need to remember.</sub><br>
+<a href="https://www.npmjs.com/package/mem.sh">npm</a> · <a href="https://github.com/justedv/mem.sh">GitHub</a> · <a href="https://github.com/justedv/mem.sh/issues">Issues</a>
+</div>

package/bin/mem.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const mem = require('../src/index');
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const rest = args.slice(1).join(' ');
+
+const HELP = `
+  mem.sh — persistent memory for AI agents
+
+  Usage:
+    mem set <text>          Store a memory
+    mem recall <query>      Semantic recall
+    mem list                List all memories
+    mem forget <id>         Delete a memory by ID
+    mem clear               Wipe all memories
+    mem serve [--port N]    Start API server
+
+  Options:
+    --agent <name>          Agent namespace
+    --api <url>             Use remote API instead of local
+    --key <key>             API key for remote server
+
+  Examples:
+    mem set "user prefers dark mode"
+    mem recall "what theme?"
+    mem list
+    mem forget 3
+`;
+
+// Parse flags
+function flag(name) {
+  const i = args.indexOf('--' + name);
+  if (i === -1) return null;
+  return args[i + 1] || true;
+}
+
+async function main() {
+  const agent = flag('agent') || 'default';
+  const api = flag('api');
+  const key = flag('key');
+
+  if (api) mem.configure({ api, key, agent });
+  else mem.configure({ agent });
+
+  const opts = { agent };
+
+  switch (cmd) {
+    case 'set': case 's': case 'save': case 'remember': {
+      const text = args.slice(1).filter(a => !a.startsWith('--')).join(' ').replace(/^["']|["']$/g, '');
+      if (!text) return console.log('Usage: mem set <text>');
+      const r = await mem.set(text, opts);
+      console.log(`✓ Stored (id: ${r.id})`);
+      break;
+    }
+    case 'recall': case 'r': case 'search': case 'q': {
+      const query = args.slice(1).filter(a => !a.startsWith('--')).join(' ').replace(/^["']|["']$/g, '');
+      if (!query) return console.log('Usage: mem recall <query>');
+      const results = await mem.recall(query, opts);
+      if (!results.length) return console.log('No memories found.');
+      for (const r of results) {
+        console.log(`  [${r.id}] ${r.text} (score: ${r.score})`);
+      }
+      break;
+    }
+    case 'list': case 'ls': case 'l': {
+      const all = await mem.list(opts);
+      if (!all.length) return console.log('No memories stored.');
+      for (const r of all) {
+        console.log(`  [${r.id}] ${r.text}  (${r.created_at})`);
+      }
+      console.log(`\n  ${all.length} memor${all.length === 1 ? 'y' : 'ies'}`);
+      break;
+    }
+    case 'forget': case 'delete': case 'rm': {
+      const id = args[1];
+      if (!id) return console.log('Usage: mem forget <id>');
+      await mem.forget(id);
+      console.log(`✓ Forgotten (id: ${id})`);
+      break;
+    }
+    case 'clear': case 'wipe': case 'reset': {
+      await mem.clear(opts);
+      console.log('✓ All memories cleared');
+      break;
+    }
+    case 'serve': case 'server': {
+      const port = flag('port') || 3456;
+      const authKey = flag('key') || process.env.MEM_KEY || '';
+      process.env.MEM_PORT = port;
+      if (authKey) process.env.MEM_KEY = authKey;
+      require('../server');
+      break;
+    }
+    default:
+      console.log(HELP);
+  }
+}
+
+main().catch(e => { console.error('Error:', e.message); process.exit(1); });

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "memshell",
+  "version": "0.1.0",
+  "description": "Persistent memory for AI agents. Like localStorage but for LLMs.",
+  "main": "src/index.js",
+  "bin": {
+    "mem": "./bin/mem.js",
+    "mem.sh": "./bin/mem.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "memory",
+    "llm",
+    "semantic-search",
+    "embeddings",
+    "chatgpt",
+    "langchain",
+    "vector",
+    "recall"
+  ],
+  "author": "justedv",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "express": "^4.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justedv/mem.sh"
+  },
+  "homepage": "https://justedv.github.io/mem.sh"
+}

package/server.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const express = require('express');
+const { LocalStore } = require('./src/index');
+
+const app = express();
+app.use(express.json());
+
+const store = new LocalStore();
+const PORT = process.env.MEM_PORT || 3456;
+const AUTH_KEY = process.env.MEM_KEY || '';
+
+// Auth middleware
+app.use('/mem', (req, res, next) => {
+  if (AUTH_KEY && req.headers['x-mem-key'] !== AUTH_KEY) {
+    return res.status(401).json({ error: 'Invalid API key' });
+  }
+  req.agent = req.headers['x-mem-agent'] || 'default';
+  next();
+});
+
+// Store a memory
+app.post('/mem', (req, res) => {
+  const { text, metadata } = req.body;
+  if (!text) return res.status(400).json({ error: 'text is required' });
+  const result = store.set(text, { agent: req.agent, metadata });
+  res.json(result);
+});
+
+// Semantic recall
+app.get('/mem/recall', (req, res) => {
+  const q = req.query.q;
+  if (!q) return res.status(400).json({ error: 'q parameter is required' });
+  const limit = parseInt(req.query.limit) || 10;
+  const results = store.recall(q, { agent: req.agent, limit });
+  res.json(results);
+});
+
+// List all
+app.get('/mem/list', (req, res) => {
+  const results = store.list({ agent: req.agent });
+  res.json(results);
+});
+
+// Delete by id
+app.delete('/mem/:id', (req, res) => {
+  store.forget(req.params.id);
+  res.json({ ok: true, id: req.params.id });
+});
+
+// Clear all for agent
+app.delete('/mem', (req, res) => {
+  store.clear({ agent: req.agent });
+  res.json({ ok: true });
+});
+
+app.listen(PORT, () => {
+  console.log(`\n  🧠 mem.sh server running on http://localhost:${PORT}`);
+  console.log(`  Auth: ${AUTH_KEY ? 'enabled' : 'disabled'}`);
+  console.log();
+});
+
+module.exports = app;

package/src/index.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+
+// ── TF-IDF Engine ──────────────────────────────────────────────
+class TfIdf {
+  tokenize(text) {
+    return text.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter(Boolean);
+  }
+
+  tf(tokens) {
+    const freq = {};
+    for (const t of tokens) freq[t] = (freq[t] || 0) + 1;
+    const len = tokens.length || 1;
+    for (const t in freq) freq[t] /= len;
+    return freq;
+  }
+
+  idf(docs) {
+    const df = {};
+    const n = docs.length || 1;
+    for (const doc of docs) {
+      const seen = new Set(doc);
+      for (const t of seen) df[t] = (df[t] || 0) + 1;
+    }
+    const idf = {};
+    for (const t in df) idf[t] = Math.log((n + 1) / (df[t] + 1)) + 1;
+    return idf;
+  }
+
+  vectorize(tf, idf) {
+    const vec = {};
+    for (const t in tf) vec[t] = tf[t] * (idf[t] || Math.log(2));
+    return vec;
+  }
+
+  cosine(a, b) {
+    let dot = 0, magA = 0, magB = 0;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys) {
+      const va = a[k] || 0, vb = b[k] || 0;
+      dot += va * vb;
+      magA += va * va;
+      magB += vb * vb;
+    }
+    if (!magA || !magB) return 0;
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  }
+
+  rank(query, documents) {
+    const qTokens = this.tokenize(query);
+    const docTokens = documents.map(d => this.tokenize(d.text));
+    const allTokens = [qTokens, ...docTokens];
+    const idfScores = this.idf(allTokens);
+    const qVec = this.vectorize(this.tf(qTokens), idfScores);
+    return documents.map((doc, i) => {
+      const dVec = this.vectorize(this.tf(docTokens[i]), idfScores);
+      return { ...doc, score: Math.round(this.cosine(qVec, dVec) * 1000) / 1000 };
+    }).filter(d => d.score > 0.01).sort((a, b) => b.score - a.score);
+  }
+}
+
+// ── Local Store ────────────────────────────────────────────────
+class LocalStore {
+  constructor(dir) {
+    this.dir = dir || path.join(os.homedir(), '.mem');
+    this.dbPath = path.join(this.dir, 'mem.db');
+    this.tfidf = new TfIdf();
+    this._db = null;
+  }
+
+  get db() {
+    if (!this._db) {
+      fs.mkdirSync(this.dir, { recursive: true });
+      const Database = require('better-sqlite3');
+      this._db = new Database(this.dbPath);
+      this._db.pragma('journal_mode = WAL');
+      this._db.exec(`
+        CREATE TABLE IF NOT EXISTS memories (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          text TEXT NOT NULL,
+          agent TEXT DEFAULT 'default',
+          created_at TEXT DEFAULT (datetime('now')),
+          metadata TEXT DEFAULT '{}'
+        )
+      `);
+    }
+    return this._db;
+  }
+
+  set(text, opts = {}) {
+    const agent = opts.agent || 'default';
+    const meta = JSON.stringify(opts.metadata || {});
+    const info = this.db.prepare('INSERT INTO memories (text, agent, metadata) VALUES (?, ?, ?)').run(text, agent, meta);
+    return { id: info.lastInsertRowid, text, agent };
+  }
+
+  recall(query, opts = {}) {
+    const agent = opts.agent || 'default';
+    const limit = opts.limit || 10;
+    const rows = this.db.prepare('SELECT * FROM memories WHERE agent = ?').all(agent);
+    return this.tfidf.rank(query, rows).slice(0, limit);
+  }
+
+  list(opts = {}) {
+    const agent = opts.agent || 'default';
+    return this.db.prepare('SELECT * FROM memories WHERE agent = ? ORDER BY created_at DESC').all(agent);
+  }
+
+  forget(id) {
+    return this.db.prepare('DELETE FROM memories WHERE id = ?').run(id);
+  }
+
+  clear(opts = {}) {
+    const agent = opts.agent || 'default';
+    return this.db.prepare('DELETE FROM memories WHERE agent = ?').run(agent);
+  }
+}
+
+// ── API Client ─────────────────────────────────────────────────
+class ApiClient {
+  constructor(opts) {
+    this.base = opts.api.replace(/\/$/, '');
+    this.key = opts.key || '';
+    this.agent = opts.agent || 'default';
+  }
+
+  _req(method, path, body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.base + path);
+      const mod = url.protocol === 'https:' ? https : http;
+      const headers = { 'Content-Type': 'application/json' };
+      if (this.key) headers['X-Mem-Key'] = this.key;
+      headers['X-Mem-Agent'] = this.agent;
+      const req = mod.request(url, { method, headers }, res => {
+        let d = '';
+        res.on('data', c => d += c);
+        res.on('end', () => {
+          try { resolve(JSON.parse(d)); } catch { resolve(d); }
+        });
+      });
+      req.on('error', reject);
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+
+  set(text, opts = {}) { return this._req('POST', '/mem', { text, metadata: opts.metadata }); }
+  recall(query, opts = {}) { return this._req('GET', `/mem/recall?q=${encodeURIComponent(query)}&limit=${opts.limit || 10}`); }
+  list() { return this._req('GET', '/mem/list'); }
+  forget(id) { return this._req('DELETE', `/mem/${id}`); }
+  clear() { return this._req('DELETE', '/mem'); }
+}
+
+// ── Exports ────────────────────────────────────────────────────
+let _config = {};
+let _store = null;
+
+function getStore() {
+  if (!_store) {
+    _store = _config.api ? new ApiClient(_config) : new LocalStore(_config.dir);
+  }
+  return _store;
+}
+
+module.exports = {
+  configure(opts) { _config = opts; _store = null; },
+  set(text, opts) { return Promise.resolve(getStore().set(text, opts)); },
+  recall(query, opts) { return Promise.resolve(getStore().recall(query, opts)); },
+  list(opts) { return Promise.resolve(getStore().list(opts)); },
+  forget(id) { return Promise.resolve(getStore().forget(id)); },
+  clear(opts) { return Promise.resolve(getStore().clear(opts)); },
+  TfIdf,
+  LocalStore,
+  ApiClient
+};