superlocalmemory 3.4.16 → 3.4.18

package/docs/mcp-tools.md

@@ -1,220 +0,0 @@
-# MCP Tools Reference
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-SuperLocalMemory exposes 24 tools and 6 resources via the Model Context Protocol (MCP). Any MCP-compatible AI assistant can use these automatically.
-
----
-
-## Core Tools
-
-### `remember`
-
-Store a new memory.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `content` | string | Yes | The text to remember |
-| `tags` | string | No | Comma-separated tags |
-| `metadata` | object | No | Additional key-value metadata |
-
-### `recall`
-
-Search memories by natural language query.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Natural language search query |
-| `limit` | number | No | Max results (default: 10) |
-
-### `search`
-
-Search memories with filters. More control than `recall`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Search query |
-| `limit` | number | No | Max results (default: 10) |
-| `tags` | string | No | Filter by tags |
-| `before` | string | No | Filter by date (ISO format) |
-| `after` | string | No | Filter by date (ISO format) |
-
-### `fetch`
-
-Retrieve a specific memory by ID.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `id` | number | Yes | Memory ID |
-
-### `list_recent`
-
-List the most recently stored memories.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max results (default: 20) |
-
-### `get_status`
-
-Returns system status: mode, profile, memory count, health, database path.
-
-*No parameters.*
-
-### `build_graph`
-
-Rebuild the entity relationship graph from stored memories. Useful after bulk imports.
-
-*No parameters.*
-
-### `switch_profile`
-
-Switch to a different memory profile.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `profile` | string | Yes | Profile name to switch to |
-
-### `backup_status`
-
-Check the status of automatic backups.
-
-*No parameters.*
-
-### `memory_used`
-
-Return memory usage statistics: total memories, database size, per-profile counts.
-
-*No parameters.*
-
-### `get_learned_patterns`
-
-Return patterns the system has learned from your usage (e.g., preferred technologies, coding conventions).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max patterns to return (default: 10) |
-
-### `correct_pattern`
-
-Correct a learned pattern that is wrong or outdated.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `pattern_id` | number | Yes | ID of the pattern to correct |
-| `correction` | string | Yes | The corrected pattern text |
-
-### `get_attribution`
-
-Return attribution and provenance information for a specific memory.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `id` | number | Yes | Memory ID |
-
-## V2.8 Tools
-
-### `report_outcome`
-
-Report the outcome of using a memory (was it helpful?). Feeds the learning system.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `memory_id` | number | Yes | ID of the memory used |
-| `outcome` | string | Yes | `"helpful"`, `"wrong"`, or `"outdated"` |
-| `context` | string | No | Additional context about the outcome |
-
-### `get_lifecycle_status`
-
-Return lifecycle status for memories (Active, Warm, Cold, Archived).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max results (default: 20) |
-| `status` | string | No | Filter by lifecycle stage |
-
-### `set_retention_policy`
-
-Apply a retention policy to the current profile.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `policy` | string | Yes | Policy name: `"indefinite"`, `"gdpr-30d"`, `"hipaa-7y"`, or `"custom"` |
-| `days` | number | No | Days for custom policy |
-
-### `compact_memories`
-
-Merge redundant memories and optimize storage.
-
-*No parameters.*
-
-### `get_behavioral_patterns`
-
-Return behavioral patterns observed across your usage (e.g., you always check docs before coding).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max patterns to return (default: 10) |
-
-### `audit_trail`
-
-Return audit log entries. Each entry is hash-chained for tamper detection.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max entries (default: 50) |
-| `action` | string | No | Filter by action type: `"store"`, `"recall"`, `"delete"` |
-
-## V3 Tools
-
-### `set_mode`
-
-Switch the operating mode.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `mode` | string | Yes | `"a"`, `"b"`, or `"c"` |
-
-### `get_mode`
-
-Return the current operating mode and its configuration.
-
-*No parameters.*
-
-### `health`
-
-Return health diagnostics for mathematical layers (Fisher-Rao, Sheaf, Langevin), embedding model, and database.
-
-*No parameters.*
-
-### `consistency_check`
-
-Run contradiction detection across stored memories. Returns pairs of memories that may conflict.
-
-*No parameters.*
-
-### `recall_trace`
-
-Recall with a full breakdown of how each retrieval channel scored each result.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Search query |
-| `limit` | number | No | Max results (default: 10) |
-
-## Resources
-
-MCP resources provide read-only data that AI assistants can access passively.
-
-| Resource URI | Description |
-|-------------|-------------|
-| `slm://recent` | The 20 most recently stored memories |
-| `slm://stats` | Memory count, database size, mode, profile |
-| `slm://clusters` | Topic clusters detected across memories |
-| `slm://identity` | Learned user preferences and patterns |
-| `slm://learning` | Current state of the adaptive learning system |
-| `slm://engagement` | Usage statistics and interaction patterns |
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

package/docs/migration-from-v2.md

@@ -1,170 +0,0 @@
-# Migration from V2
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Upgrade from SuperLocalMemory V2 to V3. Zero data loss, one command, rollback available.
-
----
-
-## What Changed in V3
-
-| Area | V2 | V3 |
-|------|----|----|
-| **Retrieval** | Single-channel semantic search | 4-channel: Semantic + BM25 + Entity Graph + Temporal |
-| **Modes** | One mode (cloud required for smart features) | Three modes: A (zero-cloud), B (local LLM), C (cloud LLM) |
-| **Math layer** | None | Fisher-Rao similarity, Sheaf consistency, Langevin lifecycle |
-| **Ingestion** | Basic text storage | 11-step pipeline: entities, facts, emotions, beliefs, graph, and more |
-| **Data directory** | `~/.superlocalmemory/` | `~/.superlocalmemory/` (symlink preserves old path) |
-| **Consistency** | Manual | Automatic contradiction detection |
-| **Recall quality** | Good | Significantly better on complex queries (multi-hop, temporal) |
-
-**What stays the same:** All CLI commands, MCP tools, IDE integrations, profiles, trust scores, and learned patterns carry forward.
-
-## Before You Migrate
-
-1. **Update to the latest version:**
-
-```bash
-npm update -g superlocalmemory
-```
-
-2. **Check your current version:**
-
-```bash
-slm --version
-# Should show 3.x.x
-```
-
-3. **(Optional) Preview changes:**
-
-```bash
-slm migrate --dry-run
-```
-
-This shows exactly what will change without modifying anything.
-
-## Run the Migration
-
-```bash
-slm migrate
-```
-
-The migration:
-
-1. Creates a full backup of your V2 database
-2. Moves data from `~/.superlocalmemory/` to `~/.superlocalmemory/`
-3. Creates a symlink (`~/.superlocalmemory/ -> ~/.superlocalmemory/`) so old IDE configs still work
-4. Extends the database schema with V3 tables (15 new tables)
-5. Re-indexes existing memories for 4-channel retrieval
-6. Sets Mode A as default (zero breaking changes)
-7. Verifies integrity
-
-**Duration:** Under 30 seconds for most databases. Large databases (10,000+ memories) may take 1-2 minutes.
-
-## What Gets Preserved
-
-Everything:
-
-- All stored memories (content, timestamps, metadata)
-- All profiles and their isolation boundaries
-- Trust scores and provenance data
-- Learned patterns and behavioral data
-- Compliance settings and retention policies
-- Audit trail (hash-chain intact)
-- IDE configurations (via symlink)
-
-## What Gets Added
-
-The migration adds V3 capabilities to your existing data:
-
-- BM25 token index for keyword search
-- Entity graph nodes and edges
-- Temporal event entries
-- Fisher-Rao similarity metadata
-- Sheaf consistency sections
-- Langevin lifecycle state
-
-These are computed from your existing memories during migration.
-
-## After Migration
-
-### Verify
-
-```bash
-slm status
-```
-
-Confirm:
-- Mode shows `A` (default after migration)
-- Memory count matches your V2 count
-- Health shows all green
-- Profile is your previous active profile
-
-### Try a recall
-
-```bash
-slm recall "something you stored in V2"
-```
-
-Results should match or exceed V2 quality. V3's 4-channel retrieval finds memories that V2's single-channel search might have missed.
-
-### Explore V3 features
-
-```bash
-slm trace "your query"       # See channel-by-channel breakdown
-slm health                   # Check math layer status
-slm consistency              # Run contradiction detection
-slm mode b                   # Try local LLM mode (if Ollama installed)
-```
-
-## Rollback
-
-If anything goes wrong, roll back within 30 days:
-
-```bash
-slm migrate --rollback
-```
-
-This restores your V2 database from the backup created during migration. The symlink is removed and the original `~/.superlocalmemory/` directory is restored.
-
-**After 30 days:** The backup is automatically cleaned up. If you need to roll back after 30 days, restore from your own backups.
-
-## IDE Configuration Updates
-
-### Automatic (recommended)
-
-The migration preserves your IDE configs via symlink. No IDE reconfiguration needed.
-
-### Manual (optional)
-
-If you want to update your IDE configs to use the new path directly:
-
-```bash
-slm connect
-```
-
-This updates all detected IDE configs to point to `~/.superlocalmemory/` instead of relying on the symlink.
-
-## FAQ
-
-**Q: Will my IDE break during migration?**
-No. The symlink ensures old paths still work. Your IDE will not notice the change.
-
-**Q: Do I need to reconfigure my API keys?**
-No. API keys are migrated to the new config location automatically.
-
-**Q: Can I run V2 and V3 side by side?**
-No. The migration converts your database in place (with backup). Use `--rollback` if you want to return to V2.
-
-**Q: What if migration fails halfway?**
-The migration is transactional. If any step fails, everything is rolled back automatically. Your V2 data remains untouched.
-
-**Q: I have multiple profiles. Are they all migrated?**
-Yes. All profiles are migrated together. Profile isolation is preserved.
-
-**Q: How big will my database get after migration?**
-The V3 schema adds approximately 20-40% to database size due to the entity graph, BM25 index, and math layer metadata. A 50MB V2 database becomes roughly 60-70MB.
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

package/docs/profiles.md

@@ -1,173 +0,0 @@
-# Profiles
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Profiles let you maintain completely isolated memory contexts. Work memories never mix with personal memories. Client A never sees Client B's data.
-
----
-
-## What Profiles Are
-
-A profile is an isolated memory namespace. Each profile has its own:
-
-- Memories and knowledge graph
-- Learned patterns and behavioral data
-- Trust scores and provenance records
-- Retention policies
-- Audit trail
-
-There is zero data leakage between profiles. Searching in one profile never returns results from another.
-
-## Default Profile
-
-After installation, you have one profile called `default`. All memories go here unless you create and switch to another profile.
-
-## Managing Profiles
-
-### List profiles
-
-```bash
-slm profile list
-```
-
-Output:
-
-```
-Profiles:
-  * default     (142 memories, active)
-    work        (89 memories)
-    personal    (34 memories)
-    client-acme (67 memories)
-```
-
-The `*` marks the active profile.
-
-### Create a profile
-
-```bash
-slm profile create work
-slm profile create client-acme
-slm profile create personal
-```
-
-### Switch profiles
-
-```bash
-slm profile switch work
-```
-
-All subsequent `remember`, `recall`, and auto-memory operations use this profile until you switch again.
-
-### Delete a profile
-
-```bash
-slm profile delete old-project
-```
-
-This permanently deletes all memories in that profile. You will be prompted for confirmation.
-
-### Export a profile
-
-```bash
-slm profile export work > work-backup.json
-```
-
-### Import a profile
-
-```bash
-slm profile import < work-backup.json
-```
-
-## Use Cases
-
-### Work vs Personal
-
-```bash
-# Morning: switch to work
-slm profile switch work
-# Work memories are captured and recalled all day
-
-# Evening: switch to personal
-slm profile switch personal
-# Personal project memories are now active
-```
-
-### Per-Client Isolation
-
-For consultants and agencies working across multiple clients:
-
-```bash
-slm profile create client-alpha
-slm profile create client-beta
-
-# Working on Alpha's project
-slm profile switch client-alpha
-# Only Alpha's architecture, decisions, and context are available
-
-# Switch to Beta
-slm profile switch client-beta
-# Alpha's data is completely invisible
-```
-
-### Per-Project Isolation
-
-```bash
-slm profile create mobile-app
-slm profile create backend-api
-slm profile create infrastructure
-```
-
-### Temporary Profiles
-
-For experiments or short-term work:
-
-```bash
-slm profile create experiment-graphql
-slm profile switch experiment-graphql
-# ... do your experiment ...
-
-# Done — delete it
-slm profile switch default
-slm profile delete experiment-graphql
-```
-
-## Profile-Specific Settings
-
-Each profile can have its own retention policy:
-
-```bash
-slm profile switch client-acme
-slm retention set gdpr-30d        # GDPR compliance for this client
-
-slm profile switch internal
-slm retention set indefinite       # Keep internal memories forever
-```
-
-## Using Profiles With CLI Commands
-
-Most commands operate on the active profile. You can override this per-command:
-
-```bash
-# Recall from a specific profile without switching
-slm recall "database config" --profile client-acme
-
-# Store to a specific profile without switching
-slm remember "Acme uses Aurora PostgreSQL" --profile client-acme
-```
-
-## How Profiles Work Internally
-
-Each profile stores memories in the same SQLite database but with a profile identifier on every row. Queries are filtered by profile at the database level, ensuring complete isolation.
-
-The entity graph, BM25 index, and all math layer state are also per-profile. Building the graph for one profile does not affect another.
-
-## Limits
-
-- No hard limit on the number of profiles
-- Each profile adds minimal overhead (a few KB for metadata)
-- Performance is determined by per-profile memory count, not total profiles
-- Switching profiles is instant (no data loading required)
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*