kyp-mem 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adhithya-Karthikeyan
+
+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,147 @@
+# KYP-MEM — Know Your Project Memory
+
+**Headless Obsidian for AI agents.** A markdown knowledge base with wikilinks, backlinks, tags, related notes, and a neon web UI — all powered by an MCP server so Claude (or any AI) can read and write your project knowledge directly.
+
+## Install
+
+```bash
+pip install kyp-mem
+```
+
+## Setup (3 commands)
+
+```bash
+# 1. Choose where your vault (knowledge base) lives
+kyp-mem init
+
+# 2. Connect to Claude Code — auto-configures MCP
+kyp-mem setup-claude
+
+# 3. Restart Claude Code — done!
+#    kyp-mem now runs headlessly every session.
+#    Claude can read/write/search your knowledge base.
+```
+
+That's it. Claude now has `kyp_read`, `kyp_write`, `kyp_search`, and 7 other tools available in every session.
+
+## Optional: Web UI
+
+```bash
+kyp-mem ui
+```
+
+Opens an Obsidian-like interface at `localhost:3333` with:
+- Collapsible folder tree
+- Rendered markdown with syntax highlighting
+- Clickable `[[wikilinks]]`
+- Backlinks and related notes panel
+- Interactive D3 graph view (toggleable)
+- Full-text search (`Cmd+K`)
+- Draggable resizable panels
+
+## How It Works
+
+```
+┌─────────────┐          ┌─────────────┐          ┌──────────────┐
+│  Claude Code │──stdio──▶│  kyp-mem    │──read/──▶│  ~/.kyp-mem/ │
+│  (any AI)    │◀─────────│  MCP server │  write   │  vault/      │
+└─────────────┘          └─────────────┘          │    *.md files │
+                                                   └──────────────┘
+```
+
+- **Headless by default** — runs as an MCP server (stdio), no GUI needed
+- **Markdown files on disk** — same format as Obsidian, no database
+- **In-memory index** — links, backlinks, tags, search, similarity scoring
+- **Web UI optional** — `kyp-mem ui` when you want to browse visually
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `kyp-mem init` | First-time setup — choose vault location |
+| `kyp-mem setup-claude` | Auto-configure Claude Code MCP settings |
+| `kyp-mem setup-claude --global` | Configure globally (all projects) |
+| `kyp-mem serve` | Start MCP server (used by Claude, not you) |
+| `kyp-mem ui` | Open web UI at localhost:3333 |
+| `kyp-mem stats` | Print vault statistics |
+| `kyp-mem tree` | Print vault tree |
+| `kyp-mem doctor` | Check installation health |
+
+## MCP Tools (what Claude gets)
+
+| Tool | Description |
+|------|-------------|
+| `kyp_list` | Browse vault folders and notes |
+| `kyp_read` | Read a note — content + tags + backlinks + related |
+| `kyp_write` | Create or update a note with tags and properties |
+| `kyp_delete` | Delete a note |
+| `kyp_search` | Full-text search across all notes |
+| `kyp_tags` | List all tags or filter notes by tag |
+| `kyp_related` | Find related notes by links, tags, proximity |
+| `kyp_recent` | Recently modified notes |
+| `kyp_stats` | Vault statistics |
+
+## Note Format
+
+Standard markdown with YAML frontmatter — same as Obsidian:
+
+```markdown
+---
+tags: [project, trading, config]
+source: config.py
+created: 2026-05-12
+updated: 2026-05-12
+---
+
+# Configuration
+
+Settings are defined in `HedgeConfig`. See [[Risk Management]] for safety checks.
+```
+
+`[[Wikilinks]]` are automatically parsed, indexed, and turned into navigable backlinks.
+
+## Manual Claude Code Config
+
+If you prefer to configure manually instead of using `setup-claude`:
+
+```json
+{
+  "mcpServers": {
+    "kyp-mem": {
+      "command": "kyp-mem",
+      "args": ["serve"],
+      "env": {
+        "KYP_VAULT": "~/.kyp-mem/vault"
+      }
+    }
+  }
+}
+```
+
+Add to `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project).
+
+## Architecture
+
+```
+~/.kyp-mem/
+├── config.json       # vault path + settings
+└── vault/            # your knowledge base
+    ├── Project A/
+    │   ├── Architecture.md
+    │   ├── Configuration.md
+    │   └── Bugs.md
+    └── Project B/
+        └── ...
+```
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python3 -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { execFileSync, execSync } from "child_process";
+
+const args = process.argv.slice(2);
+
+function tryRun(cmd, cmdArgs) {
+  try {
+    execFileSync(cmd, cmdArgs, { stdio: "inherit" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Try the installed kyp-mem binary first
+if (tryRun("kyp-mem", args)) process.exit(0);
+
+// Fallback: python3 -m kyp_mem.cli
+if (tryRun("python3", ["-m", "kyp_mem.cli", ...args])) process.exit(0);
+
+// Fallback: python -m kyp_mem.cli
+if (tryRun("python", ["-m", "kyp_mem.cli", ...args])) process.exit(0);
+
+console.error("");
+console.error("  \x1b[31mError:\x1b[0m kyp-mem Python package not found.");
+console.error("");
+console.error("  Install it:");
+console.error("    \x1b[33mpip install kyp-mem\x1b[0m");
+console.error("  Or from source:");
+console.error("    \x1b[33mpip install git+https://github.com/Adhithya-Karthikeyan/KYP-MEM.git\x1b[0m");
+console.error("");
+process.exit(1);

package/bin/install.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+function tryInstall(cmd) {
+  try {
+    execSync(cmd, { cwd: root, stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Check if already installed
+try {
+  execSync("kyp-mem --help", { stdio: "pipe" });
+  process.exit(0);
+} catch {}
+
+console.log("  Installing kyp-mem Python package...");
+
+if (tryInstall("pip install --user .")) {
+  console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
+} else if (tryInstall("pip3 install --user .")) {
+  console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
+} else if (tryInstall("python3 -m pip install --user .")) {
+  console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
+} else {
+  console.log("  \x1b[33m!\x1b[0m Could not auto-install Python package.");
+  console.log("  \x1b[33m!\x1b[0m Run manually: pip install kyp-mem");
+}

package/kyp_mem/__init__.py

@@ -0,0 +1,3 @@
+"""KYP-MEM — Know Your Project Memory. Headless Obsidian for AI agents."""
+
+__version__ = "0.2.0"

package/kyp_mem/cli.py

@@ -0,0 +1,263 @@
+"""KYP-MEM CLI — Know Your Project Memory."""
+
+import os
+import json
+import shutil
+import argparse
+from pathlib import Path
+
+C = "\033[36m"  # cyan
+G = "\033[32m"  # green
+Y = "\033[33m"  # yellow
+D = "\033[90m"  # dim
+R = "\033[0m"   # reset
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="kyp-mem",
+        description="KYP-MEM — Know Your Project Memory. Headless Obsidian for AI agents.",
+    )
+    parser.add_argument("--vault", default=None, help="Override vault path")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("init", help="Set up vault location (first-time setup)")
+    subparsers.add_parser("serve", help="Start MCP server (stdio)")
+
+    sc = subparsers.add_parser("setup-claude", help="Auto-configure Claude Code to use KYP-MEM")
+    sc.add_argument("--global", dest="global_config", action="store_true",
+                    help="Add to global ~/.claude/settings.json (default: project .claude/settings.json)")
+
+    ui_parser = subparsers.add_parser("ui", help="Open web UI in browser")
+    ui_parser.add_argument("--port", type=int, default=3333, help="Port (default: 3333)")
+    ui_parser.add_argument("--no-open", action="store_true", help="Don't auto-open browser")
+
+    subparsers.add_parser("stats", help="Print vault statistics")
+    subparsers.add_parser("tree", help="Print vault tree")
+    subparsers.add_parser("doctor", help="Check installation and config health")
+
+    args = parser.parse_args()
+
+    if args.vault:
+        os.environ["KYP_VAULT"] = args.vault
+
+    if args.command == "init":
+        _run_init()
+    elif args.command == "serve":
+        from .server import mcp
+        mcp.run()
+    elif args.command == "setup-claude":
+        _run_setup_claude(global_config=args.global_config)
+    elif args.command == "ui":
+        from .ui import start_ui
+        start_ui(port=args.port, open_browser=not args.no_open)
+    elif args.command == "stats":
+        _run_stats()
+    elif args.command == "tree":
+        _run_tree()
+    elif args.command == "doctor":
+        _run_doctor()
+    else:
+        _print_banner()
+        parser.print_help()
+
+
+def _run_init():
+    from .config import CONFIG_FILE, save_config, load_config, DEFAULT_VAULT
+
+    print()
+    print(f"{C}  ██╗  ██╗██╗   ██╗██████╗       ███╗   ███╗███████╗███╗   ███╗{R}")
+    print(f"{C}  ██║ ██╔╝╚██╗ ██╔╝██╔══██╗      ████╗ ████║██╔════╝████╗ ████║{R}")
+    print(f"{C}  █████╔╝  ╚████╔╝ ██████╔╝█████╗██╔████╔██║█████╗  ██╔████╔██║{R}")
+    print(f"{C}  ██╔═██╗   ╚██╔╝  ██╔═══╝ ╚════╝██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║{R}")
+    print(f"{C}  ██║  ██╗   ██║   ██║           ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║{R}")
+    print(f"{C}  ╚═╝  ╚═╝   ╚═╝   ╚═╝           ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝{R}")
+    print()
+    print(f"  {D}Know Your Project — Headless Obsidian for AI agents{R}")
+    print()
+    print(f"  {Y}>> First-time setup{R}")
+    print()
+
+    current = load_config()
+    current_path = current.get("vault_path", DEFAULT_VAULT)
+
+    print(f"  Where should your vault live?")
+    print(f"  {D}This is where all your notes/knowledge will be stored.{R}")
+    print(f"  {D}Default: {current_path}{R}")
+    print()
+
+    vault_input = input(f"  Vault path [{current_path}]: ").strip()
+    vault_path = vault_input or current_path
+    vault_path = str(Path(vault_path).expanduser().resolve())
+
+    Path(vault_path).mkdir(parents=True, exist_ok=True)
+    save_config({"vault_path": vault_path})
+
+    print()
+    print(f"  {G}✓{R} Vault:  {vault_path}")
+    print(f"  {G}✓{R} Config: {CONFIG_FILE}")
+    print()
+    print(f"  {Y}Next step:{R} Connect to Claude Code:")
+    print(f"    {Y}kyp-mem setup-claude{R}")
+    print()
+
+
+def _run_setup_claude(global_config: bool = False):
+    from .config import get_vault_path
+
+    vault_path = get_vault_path()
+    kyp_mem_bin = shutil.which("kyp-mem")
+
+    if not kyp_mem_bin:
+        print(f"  {Y}Warning:{R} 'kyp-mem' not found in PATH.")
+        print(f"  {D}Make sure you installed with: pip install kyp-mem{R}")
+        print()
+        kyp_mem_bin = "kyp-mem"
+
+    if global_config:
+        settings_path = Path.home() / ".claude" / "settings.json"
+        scope = "global"
+    else:
+        settings_path = Path.cwd() / ".claude" / "settings.json"
+        scope = "project"
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    settings = {}
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            settings = {}
+
+    mcp_servers = settings.setdefault("mcpServers", {})
+
+    mcp_servers["kyp-mem"] = {
+        "command": kyp_mem_bin,
+        "args": ["serve"],
+        "env": {
+            "KYP_VAULT": vault_path,
+        },
+    }
+
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+
+    print()
+    print(f"  {C}KYP-MEM{R} — Claude Code Setup")
+    print()
+    print(f"  {G}✓{R} MCP server added to {scope} settings")
+    print(f"  {D}  File:    {settings_path}{R}")
+    print(f"  {D}  Command: {kyp_mem_bin} serve{R}")
+    print(f"  {D}  Vault:   {vault_path}{R}")
+    print()
+    print(f"  {C}Done!{R} Restart Claude Code and kyp-mem will run automatically.")
+    print(f"  Claude gets these tools: kyp_list, kyp_read, kyp_write, kyp_delete,")
+    print(f"  kyp_search, kyp_tags, kyp_related, kyp_recent, kyp_stats")
+    print()
+    print(f"  {D}To open the web UI anytime:{R} {Y}kyp-mem ui{R}")
+    print()
+
+
+def _run_stats():
+    from .config import get_vault_path
+    from .vault import Vault
+    vault_path = get_vault_path()
+    v = Vault(vault_path)
+    s = v.get_stats()
+    print(f"{C}KYP-MEM{R} vault: {vault_path}")
+    print(f"  Notes:     {G}{s['notes']}{R}")
+    print(f"  Folders:   {G}{s['folders']}{R}")
+    print(f"  Tags:      {G}{s['tags']}{R}")
+    print(f"  Links:     {G}{s['links']}{R}")
+    print(f"  Backlinks: {G}{s['backlinks']}{R}")
+
+
+def _run_tree():
+    from .config import get_vault_path
+    from .vault import Vault
+    vault_path = get_vault_path()
+    v = Vault(vault_path)
+    print(f"{C}KYP-MEM{R} vault: {vault_path}\n")
+    _print_tree(v.get_full_tree(), "")
+
+
+def _run_doctor():
+    from .config import CONFIG_FILE, load_config, get_vault_path
+
+    print()
+    print(f"  {C}KYP-MEM{R} — Health Check")
+    print()
+
+    # Config
+    if CONFIG_FILE.exists():
+        print(f"  {G}✓{R} Config exists: {CONFIG_FILE}")
+    else:
+        print(f"  {Y}✗{R} No config file. Run: kyp-mem init")
+
+    # Vault
+    vault_path = get_vault_path()
+    vault_dir = Path(vault_path)
+    if vault_dir.exists():
+        md_count = len(list(vault_dir.rglob("*.md")))
+        print(f"  {G}✓{R} Vault exists: {vault_path} ({md_count} notes)")
+    else:
+        print(f"  {Y}✗{R} Vault not found: {vault_path}")
+
+    # Claude Code config
+    for label, path in [
+        ("project", Path.cwd() / ".claude" / "settings.json"),
+        ("global", Path.home() / ".claude" / "settings.json"),
+    ]:
+        if path.exists():
+            try:
+                s = json.loads(path.read_text())
+                if "kyp-mem" in s.get("mcpServers", {}):
+                    print(f"  {G}✓{R} Claude Code ({label}): kyp-mem configured")
+                else:
+                    print(f"  {D}·{R} Claude Code ({label}): exists but kyp-mem not configured")
+            except json.JSONDecodeError:
+                print(f"  {Y}✗{R} Claude Code ({label}): invalid JSON")
+        else:
+            print(f"  {D}·{R} Claude Code ({label}): no settings file")
+
+    # Binary
+    kyp_bin = shutil.which("kyp-mem")
+    if kyp_bin:
+        print(f"  {G}✓{R} Binary in PATH: {kyp_bin}")
+    else:
+        print(f"  {Y}✗{R} 'kyp-mem' not found in PATH")
+
+    # MCP dependency
+    try:
+        import mcp
+        print(f"  {G}✓{R} MCP SDK installed: {mcp.__version__}")
+    except ImportError:
+        print(f"  {Y}✗{R} MCP SDK not installed")
+    except AttributeError:
+        print(f"  {G}✓{R} MCP SDK installed")
+
+    print()
+
+
+def _print_banner():
+    print()
+    print(f"{C}  KYP-MEM{R} — Know Your Project Memory")
+    print(f"  {D}Headless Obsidian for AI agents{R}")
+    print()
+
+
+def _print_tree(node: dict, prefix: str):
+    if node["type"] == "folder":
+        if node["name"] != "vault":
+            print(f"{prefix}{C}{node['name']}/{R}")
+            prefix += "  "
+        for child in node.get("children", []):
+            _print_tree(child, prefix)
+    else:
+        name = node["name"].replace(".md", "")
+        print(f"{prefix}{name}")
+
+
+if __name__ == "__main__":
+    main()

package/kyp_mem/config.py

@@ -0,0 +1,31 @@
+"""KYP-MEM configuration — stored at ~/.kyp-mem/config.json"""
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".kyp-mem"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_VAULT = str(CONFIG_DIR / "vault")
+
+
+def load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except json.JSONDecodeError:
+            return {"vault_path": DEFAULT_VAULT}
+    return {"vault_path": DEFAULT_VAULT}
+
+
+def save_config(config: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
+
+
+def get_vault_path() -> str:
+    env = os.environ.get("KYP_VAULT")
+    if env:
+        return env
+    config = load_config()
+    return config.get("vault_path", DEFAULT_VAULT)