memcord 4.0.0__tar.gz

memcord-4.0.0/.gitignore

@@ -0,0 +1,148 @@
+# Claude Code internal files (not for repository)
+OPTIMIZE_PLAN.md
+SMART_SAVE.md
+
+# Release sync configuration (dev repo only)
+CLAUDE-RECOVERY-PROMPT.md
+SESSION-RECOVERY.md
+TASK-MATRIX.md
+DRY_MAINTAINABILITY_ANALYSIS.md
+TESTING_METHODOLOGY_VALIDATION.md
+PR-DESCRIPTION*.md
+PR-READINESS*.md
+TODO.md
+.claude/agents/
+.claude/utils/
+.claude/skills/
+.claude/settings.json
+.claude/settings.local.json
+.claude-plugin/
+commands/
+docs/superpowers/
+hooks/
+tmpclaude-*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs and editors
+.idea/
+*.swp
+*.swo
+*~
+
+# Generated MCP configuration files (templates are in config-templates/)
+.mcp.json
+claude_desktop_config.json
+.vscode/mcp.json
+.antigravity/
+.memcord
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+nul
+*.txt
+
+# Project specific
+memory_slots/
+shared_memories/
+archives/
+cache/
+logs/
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+.tmp/
+.temp/
+
+# Development
+.env.local
+.env.development
+.env.test
+.env.production
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Jupyter Notebooks
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# UV
+.uv/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+.idea/
+
+# Ruff
+.ruff_cache/
+
+# Dev-only scripts
+scripts/publish-to-main.sh
+scripts/publish-to-main.ps1

memcord-4.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neeraj Tikku
+
+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.

memcord-4.0.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: memcord
+Version: 4.0.0
+Summary: privacy-first, self-hosted MCP server helps you organize chat history, summarize messages, search across past chats with AI — and keeps everything secure and fully under your control.
+Project-URL: Homepage, https://github.com/ukkit/memcord
+Project-URL: Repository, https://github.com/ukkit/memcord
+Project-URL: Bug Tracker, https://github.com/ukkit/memcord/issues
+Author-email: MemCord <memcord@ultrafastidio.us>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: mcp<2,>=1.27.1
+Requires-Dist: nltk>=3.8
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pdfplumber>=0.10.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pypdfium2>=5.0.0
+Requires-Dist: python-magic>=0.4.27
+Requires-Dist: requests>=2.31.0
+Requires-Dist: sumy>=0.11.0
+Requires-Dist: trafilatura>=1.8.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: factory-boy>=3.3.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: psutil>=5.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: selenium>=4.15.0; extra == 'dev'
+Requires-Dist: webdriver-manager>=4.0.0; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=3.0.0; extra == 'semantic'
+Provides-Extra: transformers
+Requires-Dist: torch>=2.0.0; extra == 'transformers'
+Requires-Dist: transformers>=4.40.0; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="assets/image/memcord_1024.png" width="256">
+  <h3>MEMCORD v4.0.0 (mcp server)</h3>
+  <p>This privacy-first, self-hosted MCP server helps you organize chat history, summarize messages, search across past chats with AI — and keeps everything secure and fully under your control.</p>
+</div>
+
+<p align="center">
+  <a href="https://github.com/modelcontextprotocol"><img src="https://img.shields.io/badge/MCP-Server-blue" alt="MCP Server"></a>
+  <a href="https://docs.anthropic.com/claude/docs/claude-code"><img src="https://img.shields.io/badge/Claude-Code-purple" alt="Claude Code"></a>
+  <a href="https://claude.ai/desktop"><img src="https://img.shields.io/badge/Claude-Desktop-orange" alt="Claude Desktop"></a>
+  <a href="https://code.visualstudio.com/"><img src="https://img.shields.io/badge/Visual_Studio-Code-orange" alt="VSCode"></a>
+  <a href="https://antigravity.google"><img src="https://img.shields.io/badge/Google-Antigravity-4285F4" alt="Google Antigravity"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-green" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow" alt="License"></a>
+  <a href="https://buymeacoffee.com/ukkit"><img src="https://img.shields.io/badge/Buy%20Me%20A-Coffee-white" alt="Buy Me a Coffee"></a>
+</p>
+
+<h2 align="center">Never Lose Context Again</h2>
+<p align="center"><em>Transform your Claude conversations into a searchable, organized knowledge base that grows with you</em></p>
+
+> **[What's new in v4.0.0](docs/versions.md#v400---openclaw--clawhub-compatibility)** — OpenClaw / ClaWHub compatibility: new `memcord_auto_save` tool for zero-setup gateway integrations, `MEMCORD_DEFAULT_SLOT` env var fallback in slot resolution, and `SKILL.md` for ClaWHub discovery.
+
+## Table of Contents
+
+- [Core Benefits](#core-benefits)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Demo](#demo)
+- [IDE Configuration](#ide-configuration)
+- [Keeping Memcord Updated](#keeping-memcord-updated)
+- [Using Memcord in a Project](#using-memcord-in-a-project)
+- [Basic Usage](#basic-usage)
+- [Summarizer Backends](#summarizer-backends)
+- [Documentation](#documentation)
+
+## Core Benefits
+
+* **Infinite Memory** - Claude remembers everything across unlimited conversations with intelligent auto-summarization
+* **Your Data, Your Control** - 100% local storage with zero cloud dependencies or privacy concerns
+* **Effortless Organization** - Per-project memory slots with timeline navigation and smart tagging
+* **Intelligent Merging** - Automatically combines related conversations while eliminating duplicates
+
+## Prerequisites
+
+<details>
+<summary>Python 3.10+ and uv are required. The installer handles both — click to expand manual instructions.</summary>
+
+- **Python 3.10+** — [python.org](https://python.org)
+- **uv** (Python package manager) — install with:
+
+  **macOS / Linux:**
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+  **Windows (PowerShell):**
+  ```powershell
+  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+  ```
+
+</details>
+
+## Quick Start
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://github.com/ukkit/memcord/raw/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://github.com/ukkit/memcord/raw/main/install.ps1 | iex
+```
+
+This will:
+- ✅ Download and setup **memcord**
+- ✅ Set up Python virtual environment using uv
+- ✅ Generate platform-specific MCP configuration files
+- ✅ Configure Claude Desktop, Claude Code, VSCode, and Antigravity IDE
+
+## Demo
+
+_A demo GIF or terminal recording will be added here. Contributions welcome!_
+
+## IDE Configuration
+
+The installer auto-configures all supported IDEs. For manual setup or troubleshooting, see the detailed guides:
+
+| IDE / Client | Guide |
+|---|---|
+| Claude Code CLI | [Installation Guide — Claude Code](docs/installation.md#claude-code-cli-recommended-) |
+| Claude Desktop | [Installation Guide — Claude Desktop](docs/installation.md#claude-desktop) |
+| VSCode + GitHub Copilot | [VSCode Setup Guide](docs/vscode-setup.md) |
+| Google Antigravity | [Installation Guide — Other MCP Apps](docs/installation.md#other-mcp-applications) |
+| Configuration templates | [`config-templates/`](config-templates/) ([README](config-templates/README.md)) |
+
+### Manual Installation
+
+```bash
+git clone https://github.com/ukkit/memcord.git
+cd memcord
+uv venv && uv pip install -e .
+uv run python scripts/generate-config.py
+```
+
+See the **[Complete Installation Guide](docs/installation.md)** for updating, advanced options, and custom commands.
+
+## Keeping Memcord Updated
+
+```bash
+cd /path/to/memcord
+git pull
+uv pip install -e .
+uv run python scripts/generate-config.py  # Regenerate configs
+
+# Optional: Enable auto-save hooks (new in v2.5.0)
+uv run python scripts/generate-config.py --install-hooks
+```
+
+The `--install-hooks` flag is idempotent — it merges into existing `.claude/settings.json` without overwriting other settings or hooks.
+
+<a id="using-memcord-in-a-project"></a>
+
+## Using Memcord in a Project
+
+### First-Time Setup (New Project)
+
+```bash
+# 1. Once you are in claude code, initialize the project with a memory slot (one-time setup)
+memcord_init "." "my-project-name"
+# OR
+memcord_init "my_project_name"
+# Creates .memcord file containing "my-project-name"
+
+# 2. Start saving your conversations
+/memcord-save-progress  # Auto-detects slot from .memcord file
+```
+
+### Subsequent Sessions (Returning to Project)
+
+```bash
+# Just use slash commands - no slot name needed!
+/memcord-read           # Reads from bound slot automatically
+
+/memcord-save           # Saves to bound slot automatically
+/memcord-save-progress  # Summarizes and saves automatically
+```
+
+### Enable Auto-Save (Optional)
+
+```bash
+uv run python scripts/generate-config.py --install-hooks
+```
+
+Automatically saves conversation progress before context compaction and on session end. See [config-templates/README.md](config-templates/README.md#auto-save-hooks-optional) for details.
+
+### How Auto-Detection Works
+
+All read **and write** operations follow the same slot resolution priority:
+
+1. Explicit `slot_name` argument (always wins)
+2. Currently active slot (set by `memcord_use` or `memcord_name`)
+3. `.memcord` binding file in the current working directory
+
+When the `.memcord` binding is used and the slot already exists, it is also **auto-activated** for the rest of the session — so subsequent operations skip re-detection automatically.
+
+This means after `memcord_init`, a fresh session (no `memcord_use` call needed) will correctly route `memcord_save`, `memcord_save_progress`, `memcord_configure`, and `memcord_read` to the bound slot.
+
+## Basic Usage
+
+### Saving & Retrieving
+
+```bash
+memcord_name "project_meeting"          # Create or select a slot
+memcord_save "Our discussion about..."  # Save exact text
+memcord_save_progress                   # Save a compressed summary
+memcord_read                            # Read the slot
+```
+
+### Navigating & Searching
+
+```bash
+memcord_select_entry "2 hours ago"    # Jump to a point in the timeline
+memcord_list                          # List all slots
+memcord_search "API design"           # Full-text search
+memcord_query "What did we decide?"   # Natural language query
+```
+
+### Project & Privacy
+
+```bash
+memcord_init "." "my-project"  # Bind a memory slot to this directory
+memcord_zero                   # Privacy mode — nothing gets saved
+```
+
+See **[Complete Tools Reference](docs/tools-reference.md)** for all 23 tools with full parameters and examples.
+
+## Summarizer Backends
+
+Memcord supports four summarizer backends. New slots default to **sumy** (graph-based, no downloads required). Existing slots keep **nltk** to preserve prior behavior.
+
+| Backend | Type | Speed | Quality | Extra install |
+|---|---|---|---|---|
+| `nltk` | Extractive | Fast | Good | None (built-in) |
+| `sumy` | Extractive (graph) | Fast | Better | None (built-in) |
+| `semantic` | Extractive (embeddings) | Medium | Best extractive | `uv pip install "memcord[semantic]"` (~80 MB) |
+| `transformers` | Abstractive (BART) | Slow | Best overall | `uv pip install "memcord[transformers]"` (~400 MB) |
+
+### Switching Backends
+
+Use `memcord_configure` to change the backend for any slot — no restart required:
+
+```bash
+# Check current config
+memcord_configure action="get"
+
+# Switch to the BART abstractive summarizer (best for conversations)
+memcord_configure action="set" key="summarizer_backend" value="transformers"
+
+# Switch to embedding-based semantic summarizer
+memcord_configure action="set" key="summarizer_backend" value="semantic"
+
+# Switch sumy algorithm (lexrank / lsa / edmundson)
+memcord_configure action="set" key="sumy_algorithm" value="lsa"
+
+# Reset to defaults
+memcord_configure action="reset"
+```
+
+To apply one backend to **all slots** (e.g. in Docker or CI), set the environment variable:
+
+```bash
+export MEMCORD_SUMMARIZER=transformers
+```
+
+See **[Tools Reference — memcord_configure](docs/tools-reference.md)** for the full parameter list.
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| **[Installation Guide](docs/installation.md)** | Complete setup instructions for all MCP applications |
+| **[Feature Guide](docs/features-guide.md)** | Complete list of features |
+| **[Tools Reference](docs/tools-reference.md)** | Detailed documentation for all 23 tools |
+| **[Import & Merge Guide](docs/import-and-merge.md)** | Comprehensive guide for Phase 3 features |
+| **[Search & Query Guide](docs/search-and-query.md)** | Advanced search features and natural language queries |
+| **[Usage Examples](docs/examples.md)** | Real-world workflows and practical use cases |
+| **[Data Format Specification](docs/data-format.md)** | Technical details and file formats |
+| **[Troubleshooting](docs/troubleshooting.md)** | Common issues and solutions |
+| **[Version History](docs/versions.md)** | Changelog for all releases |
+
+---
+
+If you find this project helpful, consider:
+
+ - ⭐ Starring the repository on GitHub
+ - ☕ [Support Development](https://buymeacoffee.com/ukkit)
+ - 🐛 Reporting bugs and suggesting features
+
+---
+
+**MIT License** - see LICENSE file for details.
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=ukkit/memcord&type=date&legend=top-left)](https://www.star-history.com/#ukkit/memcord&type=date&legend=top-left)