@hasna/mementos 0.4.16 → 0.4.19

package/README.md

@@ -1,10 +1,10 @@
 # @hasna/mementos
 
-Universal memory system for AI agents. SQLite-backed with CLI, MCP server, and library API.
+Universal memory system for AI agents. SQLite-backed with CLI, MCP server, REST API, and TypeScript library.
 
-Agents can save, recall, search, and share memories across sessions. Memories are scoped (global, shared, private), categorized, importance-ranked, and automatically injected into agent context.
+Agents save, recall, search, and share memories across sessions. Memories are scoped (global/shared/private), categorized, importance-ranked, and injected into agent context on demand.
 
-## Installation
+## Install
 
 ```bash
 bun add -g @hasna/mementos
@@ -14,261 +14,222 @@ bun add -g @hasna/mementos
 
 ```bash
 # Save a memory
-mementos save "preferred-language" "TypeScript" --scope global --importance 8
+mementos save "project-stack" "Bun + TypeScript + SQLite" --scope shared --importance 8
 
 # Recall it
-mementos recall "preferred-language"
+mementos recall "project-stack"
 
-# Search across all memories
-mementos search "typescript"
+# Search
+mementos search "typescript stack"
 
-# List memories with filters
-mementos list --scope global --importance-min 5
+# Inject into agent context (compact = ~60% smaller)
+mementos inject --format compact --project-id <id>
 
 # Get stats
 mementos stats
 ```
 
-## Memory Scopes
-
-| Scope | Visibility | Use Case |
-|-------|-----------|----------|
-| `global` | All agents, all projects | Org-wide preferences, facts |
-| `shared` | All agents in a project | Project conventions, decisions |
-| `private` | Single agent only | Agent-specific context, history |
-
-## Memory Categories
-
-| Category | Description |
-|----------|------------|
-| `preference` | Settings, choices, style preferences |
-| `fact` | Verified truths, known information |
-| `knowledge` | Learned patterns, insights, techniques |
-| `history` | Session context, conversation summaries |
-
-## CLI Reference
+## MCP Server
 
-### Global Options
+### Install into Claude Code (recommended)
 
-```
---project <path>   Project context
---json             Output as JSON
---agent <name>     Agent identifier
---session <id>     Session context
+```bash
+mementos mcp --claude
+# Or manually:
+claude mcp add --transport stdio --scope user mementos -- mementos-mcp
 ```
 
-### Commands
+### Install into Codex / Gemini
 
 ```bash
-mementos save <key> <value>     # Save a memory
-  -s, --scope <scope>           # global|shared|private (default: private)
-  -c, --category <cat>          # preference|fact|knowledge|history
-  --importance <1-10>           # Importance score (default: 5)
-  --tags <t1,t2>                # Comma-separated tags
-  --summary <text>              # Brief summary
-  --ttl <ms>                    # Time-to-live in milliseconds
-  --source <src>                # user|agent|system|auto|imported
-
-mementos recall <key>           # Get memory by key
-mementos list                   # List memories (with filters)
-mementos update <id>            # Update memory fields
-mementos forget <key|id>        # Delete a memory
-mementos search <query>         # Full-text search
-mementos stats                  # Memory statistics
-mementos export                 # Export as JSON
-mementos import <file>          # Import from JSON
-mementos clean                  # Remove expired + enforce quotas
-mementos inject                 # Output injection context
-mementos init <name>            # Register agent
-mementos agents                 # List agents
-mementos projects               # Manage projects
-mementos bulk <action> <ids>    # Batch operations
+mementos mcp --codex
+mementos mcp --gemini
+mementos mcp --all        # all agents at once
 ```
 
-## MCP Server
+### Available Tools (40+)
 
-### Setup for Claude Code
+**Memory:** `memory_save`, `memory_recall`, `memory_get`, `memory_list`, `memory_update`, `memory_pin`, `memory_archive`, `memory_forget`, `memory_search`, `memory_stats`, `memory_export`, `memory_import`, `memory_inject`, `memory_context`, `session_extract`
 
-Add to `~/.claude/.mcp.json`:
+**Bulk:** `bulk_forget`, `bulk_update`
 
-```json
-{
-  "mcpServers": {
-    "mementos": {
-      "command": "mementos-mcp",
-      "args": []
-    }
-  }
-}
-```
+**Agents:** `register_agent`, `list_agents`, `list_agents_by_project`, `get_agent`, `update_agent`
 
-### Setup for Codex
+**Projects:** `register_project`, `list_projects`, `get_project`
 
-Add to `.codex/mcp.json`:
+**Knowledge Graph:** `entity_create`, `entity_get`, `entity_list`, `entity_delete`, `entity_merge`, `entity_link`, `relation_create`, `relation_delete`, `relation_list`, `graph_query`, `graph_path`, `graph_stats`
 
-```json
-{
-  "mcpServers": {
-    "mementos": {
-      "command": "mementos-mcp"
-    }
-  }
-}
+**Meta:** `search_tools`, `describe_tools` (lean stubs — full docs on demand)
+
+**Utility:** `clean_expired`
+
+## CLI Reference
+
+```bash
+mementos save <key> <value>        # Save/upsert a memory
+mementos recall <key>              # Get memory by key
+mementos list                      # List memories (with filters)
+mementos update <id>               # Update memory fields
+mementos pin <key|id>              # Pin a memory
+mementos forget <key|id>           # Delete a memory
+mementos search <query>            # Full-text + fuzzy search
+mementos stats                     # Memory statistics
+mementos export                    # Export as JSON
+mementos import <file>             # Import from JSON
+mementos clean                     # Remove expired + enforce quotas
+mementos inject                    # Output injection context
+mementos init <name>               # Register agent
+mementos agents                    # List agents
+mementos projects                  # Manage projects
+mementos bulk forget <ids>         # Batch delete
+mementos bulk update <ids>         # Batch update
+mementos diff <id>                 # Show memory version history
+mementos doctor                    # Diagnose DB health
+
+# Profiles — isolated DBs per context
+mementos profile set work          # Switch to work profile
+mementos profile list              # List all profiles
+mementos profile get               # Show active profile
+mementos profile unset             # Back to default
 ```
 
-### Available Tools (19)
+## Profiles
 
-**Memory:** `memory_save`, `memory_recall`, `memory_list`, `memory_update`, `memory_forget`, `memory_search`, `memory_stats`, `memory_export`, `memory_import`, `memory_inject`
+```bash
+# Each profile is an isolated DB: ~/.mementos/profiles/<name>.db
+mementos profile set work
+MEMENTOS_PROFILE=work mementos list   # per-command
+```
 
-**Agents:** `register_agent`, `list_agents`, `get_agent`
+## REST API
 
-**Projects:** `register_project`, `list_projects`
+```bash
+mementos-serve --port 19428
+```
 
-**Bulk:** `bulk_forget`, `bulk_update`
+Default port: **19428**. Binds to `127.0.0.1` (localhost only). Override with `MEMENTOS_HOST=0.0.0.0`.
 
-**Utility:** `clean_expired`, `memory_context`
+### Key Endpoints
 
-### Resources
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/memories?fields=key,value` | List memories (?fields, ?scope, ?session_id, ?status) |
+| POST | `/api/memories` | Create/upsert memory |
+| PATCH | `/api/memories/:id` | Update (version optional — auto-fetched) |
+| DELETE | `/api/memories/:id` | Delete |
+| POST | `/api/memories/search` | Full-text search |
+| POST | `/api/memories/extract` | Auto-extract memories from session summary |
+| POST | `/api/memories/bulk-forget` | Delete multiple |
+| POST | `/api/memories/bulk-update` | Update multiple |
+| GET | `/api/memories/stats` | Statistics |
+| POST | `/api/memories/export` | Export with filters |
+| GET | `/api/inject?format=compact` | Context injection (compact/markdown/json/xml) |
+| GET/POST | `/api/agents` | Agent registry |
+| PATCH | `/api/agents/:id` | Update agent (including active_project_id) |
+| GET/POST | `/api/projects` | Project registry |
+| GET | `/api/projects/:id/agents` | Agents active on a project |
+| GET | `/api/profile` | Active profile info |
+| GET | `/api/health` | Health check (includes profile, hostname) |
 
-- `mementos://memories` — All active memories
-- `mementos://agents` — Registered agents
-- `mementos://projects` — Registered projects
+## SDK
 
-## Library API
+```bash
+bun add @hasna/mementos-sdk
+```
 
 ```typescript
-import {
-  createMemory,
-  getMemoryByKey,
-  listMemories,
-  searchMemories,
-  MemoryInjector,
-} from "@hasna/mementos";
+import { MementosClient } from "@hasna/mementos-sdk";
 
-// Save a memory
-const memory = createMemory({
-  key: "db-convention",
-  value: "Always use snake_case for column names",
-  scope: "shared",
-  category: "preference",
-  importance: 8,
-  tags: ["database", "conventions"],
-});
+const client = new MementosClient({ baseUrl: "http://localhost:19428" });
 
-// Recall
-const recalled = getMemoryByKey("db-convention", "shared");
+// Save memory
+await client.saveMemory({ key: "db-convention", value: "snake_case", scope: "shared" });
 
 // Search
-const results = searchMemories("database");
-
-// List with filters
-const memories = listMemories({
-  scope: "global",
-  category: "fact",
-  min_importance: 5,
-  limit: 20,
-});
+const { results } = await client.searchMemories("database conventions");
+
+// Context injection (compact format — 60% smaller)
+const { context } = await client.getContext({ project_id: "...", format: "compact" });
 
-// Inject into agent context
-const injector = new MemoryInjector();
-const context = injector.getInjectionContext({
-  agent_id: "my-agent",
-  project_id: "my-project",
-  max_tokens: 500,
+// Sessions → mementos integration
+await client.extractFromSession({
+  session_id: "abc123",
+  title: "Fix auth middleware",
+  key_topics: ["jwt", "compliance"],
+  project_id: "...",
 });
 ```
 
-## REST API
+## Agent-Project Binding
+
+Track which agent is working on which project:
 
-Start the server:
+```typescript
+// On session start
+await client.updateAgent("my-agent", { active_project_id: "project-uuid" });
+
+// Query: who's on this project?
+const { agents } = await client.getProjectAgents("open-mementos");
+```
+
+## Context Injection
 
 ```bash
-mementos-serve --port 19428
+# 60% smaller with compact format
+mementos inject --format compact --project-id <id> --max-tokens 400
 ```
 
-### Endpoints
+MCP: `memory_inject(project_id="...", format="compact", max_tokens=400)`
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/memories` | List memories |
-| POST | `/api/memories` | Create memory |
-| GET | `/api/memories/:id` | Get memory |
-| PATCH | `/api/memories/:id` | Update memory |
-| DELETE | `/api/memories/:id` | Delete memory |
-| POST | `/api/memories/search` | Search |
-| GET | `/api/memories/stats` | Statistics |
-| POST | `/api/memories/export` | Export |
-| POST | `/api/memories/import` | Import |
-| POST | `/api/memories/clean` | Cleanup |
-| GET/POST | `/api/agents` | Agents |
-| GET/POST | `/api/projects` | Projects |
-| GET | `/api/inject` | Injection context |
+## Sessions Integration
 
-## Configuration
+After ingesting a session (open-sessions):
 
-Config file: `~/.mementos/config.json`
+```bash
+sessions remember <session-id> --mementos-url http://localhost:19428
+# Creates: session-summary (history), session-topics (knowledge), session-notes (knowledge)
+```
 
+REST:
 ```json
-{
-  "default_scope": "private",
-  "default_category": "knowledge",
-  "default_importance": 5,
-  "max_entries": 1000,
-  "max_entries_per_scope": {
-    "global": 500,
-    "shared": 300,
-    "private": 200
-  },
-  "injection": {
-    "max_tokens": 500,
-    "min_importance": 5,
-    "categories": ["preference", "fact"],
-    "refresh_interval": 5
-  },
-  "sync_agents": ["claude", "codex", "gemini"],
-  "auto_cleanup": {
-    "enabled": true,
-    "expired_check_interval": 3600
-  }
-}
+POST /api/memories/extract
+{ "session_id": "abc", "title": "Fix auth", "key_topics": ["jwt"] }
 ```
 
-### Environment Variables
+## Environment Variables
 
-| Variable | Description |
-|----------|------------|
-| `MEMENTOS_DB_PATH` | Override database path |
-| `MEMENTOS_DB_SCOPE` | Set to `project` for project-level DB |
-| `MEMENTOS_DEFAULT_SCOPE` | Default memory scope |
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `MEMENTOS_DB_PATH` | Override DB path (bypasses profiles) | `~/.mementos/mementos.db` |
+| `MEMENTOS_PROFILE` | Named profile → `~/.mementos/profiles/<name>.db` | none |
+| `MEMENTOS_DB_SCOPE` | `project` = git root `.mementos/mementos.db` | global |
+| `MEMENTOS_HOST` | Server bind address | `127.0.0.1` |
+| `PORT` | Server port | `19428` |
 
-## Database
+## Library
 
-SQLite with WAL mode. Path resolution:
-
-1. `MEMENTOS_DB_PATH` environment variable
-2. Nearest `.mementos/mementos.db` (walking up from cwd)
-3. `~/.mementos/mementos.db` (global fallback)
+```typescript
+import {
+  createMemory, getMemoryByKey, listMemories, searchMemories,
+  registerAgent, updateAgent, listAgentsByProject,
+  registerProject, getProject,
+  getActiveProfile, setActiveProfile,
+  MemoryInjector,
+} from "@hasna/mementos";
+```
 
 ## Architecture
 
 ```
 src/
-├── types/index.ts      # Type definitions, enums, errors
-├── db/
-│   ├── database.ts     # SQLite setup, migrations, utilities
-│   ├── memories.ts     # Memory CRUD with optimistic locking
-│   ├── agents.ts       # Agent registration (8-char UUIDs)
-│   └── projects.ts     # Project registry
-├── lib/
-│   ├── config.ts       # Configuration loading
-│   ├── search.ts       # Full-text search engine
-│   ├── injector.ts     # Context injection system
-│   ├── retention.ts    # Auto-cleanup & quota enforcement
-│   └── sync.ts         # Multi-agent memory sync
-├── cli/index.tsx       # CLI (Commander.js + chalk)
-├── mcp/index.ts        # MCP server (19 tools, 3 resources)
-├── server/index.ts     # REST API server
-└── index.ts            # Library exports
+  cli/         Commander.js + Ink TUI — 20+ commands
+  mcp/         MCP server — 40+ tools (lean stubs)
+  server/      REST API — 37+ endpoints (Bun.serve)
+  db/          SQLite (bun:sqlite) — memories, agents, projects, entities, relations
+  lib/         FTS5 search, injection, extraction, retention, config, profiles
+  types/       TypeScript interfaces and errors
+sdk/           @hasna/mementos-sdk — zero-dep fetch client
+dashboard/     React+Vite web UI
 ```
 
 ## License

package/dist/mcp/index.js

@@ -6357,6 +6357,49 @@ server.tool("memory_stats", "Get aggregate statistics about stored memories", {}
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+server.tool("memory_activity", "Get daily memory creation activity over N days.", {
+  days: exports_external.coerce.number().optional(),
+  scope: exports_external.enum(["global", "shared", "private"]).optional(),
+  agent_id: exports_external.string().optional(),
+  project_id: exports_external.string().optional()
+}, async (args) => {
+  try {
+    const days = Math.min(args.days || 30, 365);
+    const db = getDatabase();
+    const conditions = ["status = 'active'"];
+    const params = [];
+    if (args.scope) {
+      conditions.push("scope = ?");
+      params.push(args.scope);
+    }
+    if (args.agent_id) {
+      conditions.push("agent_id = ?");
+      params.push(args.agent_id);
+    }
+    if (args.project_id) {
+      conditions.push("project_id = ?");
+      params.push(args.project_id);
+    }
+    const where = conditions.slice(1).map((c) => `AND ${c}`).join(" ");
+    const rows = db.query(`
+        SELECT date(created_at) AS date, COUNT(*) AS memories_created
+        FROM memories
+        WHERE status = 'active' AND date(created_at) >= date('now', '-${days} days') ${where}
+        GROUP BY date(created_at)
+        ORDER BY date ASC
+      `).all(...params);
+    if (rows.length === 0) {
+      return { content: [{ type: "text", text: `No memory activity in last ${days} days.` }] };
+    }
+    const total = rows.reduce((s, r) => s + r.memories_created, 0);
+    const lines = rows.map((r) => `${r.date}: ${r.memories_created} memor${r.memories_created === 1 ? "y" : "ies"}`);
+    return { content: [{ type: "text", text: `Memory activity (last ${days} days \u2014 ${total} total):
+${lines.join(`
+`)}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
 server.tool("memory_export", "Export memories as JSON", {
   scope: exports_external.enum(["global", "shared", "private"]).optional(),
   category: exports_external.enum(["preference", "fact", "knowledge", "history"]).optional(),
@@ -7146,6 +7189,17 @@ var FULL_SCHEMAS = {
     },
     example: '{"query":"typescript","scope":"global","limit":10}'
   },
+  memory_activity: {
+    description: "Get daily memory creation counts over N days (max 365). Like 'git log --stat' for memories.",
+    category: "memory",
+    params: {
+      days: { type: "number", description: "Number of days to look back (default 30)" },
+      scope: { type: "string", description: "Filter by scope", enum: ["global", "shared", "private"] },
+      agent_id: { type: "string", description: "Filter by agent" },
+      project_id: { type: "string", description: "Filter by project" }
+    },
+    example: '{"days":14,"project_id":"proj-uuid"}'
+  },
   memory_stats: {
     description: "Aggregate statistics: total, by scope, by category, pinned, expired counts.",
     category: "memory",

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAulCH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkH9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAynCH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkH9C"}

package/dist/server/index.js

@@ -2217,6 +2217,43 @@ addRoute("GET", "/api/memories/stats", (_req) => {
     stats.by_agent[row.agent_id] = row.c;
   return json(stats);
 });
+addRoute("GET", "/api/activity", (_req, url) => {
+  const q = getSearchParams(url);
+  const days = Math.min(parseInt(q["days"] || "30", 10), 365);
+  const scope = q["scope"];
+  const agentId = q["agent_id"];
+  const projectId = q["project_id"];
+  const db = getDatabase();
+  const conditions = ["status = 'active'"];
+  const params = [];
+  if (scope) {
+    conditions.push("scope = ?");
+    params.push(scope);
+  }
+  if (agentId) {
+    conditions.push("agent_id = ?");
+    params.push(agentId);
+  }
+  if (projectId) {
+    conditions.push("project_id = ?");
+    params.push(projectId);
+  }
+  const where = conditions.map((c) => `AND ${c}`).join(" ");
+  const rows = db.query(`
+    SELECT
+      date(created_at) AS date,
+      COUNT(*) AS memories_created,
+      SUM(CASE WHEN scope = 'global' THEN 1 ELSE 0 END) AS global_count,
+      SUM(CASE WHEN scope = 'shared' THEN 1 ELSE 0 END) AS shared_count,
+      SUM(CASE WHEN scope = 'private' THEN 1 ELSE 0 END) AS private_count,
+      AVG(importance) AS avg_importance
+    FROM memories
+    WHERE date(created_at) >= date('now', '-${days} days') ${where}
+    GROUP BY date(created_at)
+    ORDER BY date ASC
+  `).all(...params);
+  return json({ activity: rows, days, total: rows.reduce((s, r) => s + r.memories_created, 0) });
+});
 addRoute("POST", "/api/memories/search", async (req) => {
   const body = await readJson(req);
   if (!body || typeof body["query"] !== "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.4.16",
+  "version": "0.4.19",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",