cognova 0.1.0

package/.env.example

@@ -0,0 +1,58 @@
+# Cognova Environment Variables
+# Copy this file to .env and fill in your values
+
+# =============================================================================
+# REQUIRED
+# =============================================================================
+
+# Path to your vault directory (where markdown files are stored)
+VAULT_PATH=~/vault
+
+# Auth secret - generate with: openssl rand -base64 32
+BETTER_AUTH_SECRET=your-secret-here-generate-with-openssl
+
+# Base URL of your application (used for callbacks)
+BETTER_AUTH_URL=http://localhost:3000
+
+# =============================================================================
+# OPTIONAL - Database
+# =============================================================================
+
+# Local dev (pnpm dev + pnpm db:up) - uses localhost
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/cognova
+
+# For Neon PostgreSQL (production), replace with your connection string:
+# DATABASE_URL=postgres://user:password@ep-xxx.us-east-2.aws.neon.tech/cognova?sslmode=require
+
+# =============================================================================
+# OPTIONAL - Initial Admin User
+# =============================================================================
+
+# On first startup with an empty database, a default user is created automatically.
+# Customize the default user with these variables:
+# ADMIN_EMAIL=admin@example.com
+# ADMIN_PASSWORD=changeme
+# ADMIN_NAME=Admin
+#
+# Default credentials if not set: admin@example.com / changeme123
+
+# =============================================================================
+# OPTIONAL - CLI/Skill API Access
+# =============================================================================
+
+# API token for CLI tools and skills to access the API without browser auth.
+# A token is AUTO-GENERATED on server startup and written to .api-token file.
+# Only set this if you want to use a fixed token instead:
+# COGNOVA_API_TOKEN=your-token-here
+
+# =============================================================================
+# DOCKER ONLY - Claude Code Integration
+# =============================================================================
+
+# Claude Code CLI is pre-installed in the container.
+# To authenticate, open the terminal in the app and run: claude auth
+#
+# Optional: If you already have Claude Code configured on your host,
+# docker-compose.yml will mount your existing config:
+# - ~/.claude:/home/node/.claude (Claude Code config)
+# - ~/.anthropic:/home/node/.anthropic (API key)

package/Claude/CLAUDE.md

@@ -0,0 +1,92 @@
+# Cognova
+
+You are an AI assistant running through **Cognova**, a self-hosted personal knowledge management and productivity system. You run directly on the user's machine via the Claude Agent SDK — you are not sandboxed.
+
+## What You Are
+
+You are a Claude-powered agent embedded in a Cognova installation. The user has granted you full system access: file system, shell, local services, and the Cognova API. You can read and write files, execute commands, manage processes, and interact with all Cognova features.
+
+You run as a persistent service managed by PM2. Your conversations are streamed to the user through the Cognova web dashboard.
+
+## What Cognova Is
+
+Cognova is a self-hosted Nuxt 4 web application for personal knowledge management:
+
+- **Vault** — A folder of markdown documents organized using the PARA method (Projects, Areas, Resources, Archive, Inbox)
+- **Tasks & Projects** — Structured task tracking with project association, priorities, due dates, and tags
+- **Memory** — Persistent memory extracted from conversations that survives across sessions
+- **Dashboard** — Web UI for browsing documents, managing tasks, viewing memory, and chatting with you
+- **Cron Agents** — Background agents that run on schedules for maintenance and analysis
+- **API** — RESTful API powering all data operations
+
+## Skills
+
+| Skill | Command | Purpose |
+|-------|---------|---------|
+| Task Management | `/task` | Create, list, update, complete tasks |
+| Project Management | `/project` | Organize tasks into projects |
+| Memory | `/memory` | Search past decisions, store insights, recall context |
+| Environment | `/environment` | Check system status, troubleshoot issues |
+| Skill Creator | `/skill-creator` | Create new Claude Code skills |
+
+## Environment
+
+Key paths and services (actual values come from environment variables):
+
+| Resource | Variable / Location |
+|----------|---------------------|
+| Install Directory | `$COGNOVA_PROJECT_DIR` |
+| Vault | `$VAULT_PATH` |
+| API | `$COGNOVA_API_URL` (default: `http://localhost:3000`) |
+| Skills | `~/.claude/skills/` |
+| Process Manager | PM2 — `pm2 status`, `pm2 logs cognova` |
+| Database | PostgreSQL via Drizzle ORM (`$DATABASE_URL`) |
+
+## API Access
+
+All Python skills use the shared client at `~/.claude/skills/_lib/api.py`. Authentication is automatic via `.api-token` file or `COGNOVA_API_TOKEN` env var.
+
+```bash
+# Quick health check
+curl -s $COGNOVA_API_URL/api/health
+
+# Or use the environment skill
+python3 ~/.claude/skills/environment/environment.py health
+```
+
+## Vault Documents
+
+Documents are markdown files with YAML frontmatter:
+
+```yaml
+---
+tags: []
+shared: false
+---
+```
+
+Organized in PARA folders: `inbox/`, `projects/`, `areas/`, `resources/`, `archive/`. Use lowercase-hyphenated filenames (`project-ideas.md`). Documentation standards are in `~/.claude/rules/`.
+
+## Behaviors
+
+### Task Management
+- Offer to create tasks for action items mentioned in conversation
+- Use `/task create` with appropriate priority and project association
+- Always search for existing projects before creating new ones
+
+### Memory
+- Store key decisions: `/memory store --type decision "chose X because Y"`
+- Check history before major changes: `/memory about "topic"`
+- Memory types: decision, fact, solution, pattern, preference, summary
+- Memories are also auto-extracted from conversations via hooks
+
+### Troubleshooting
+- Use `/environment status` or `/environment health` to diagnose issues
+- Check logs: `pm2 logs cognova --lines 50`
+- Restart: `pm2 restart cognova`
+
+### Self-Modification
+- You MAY update `~/.claude/CLAUDE.md` to refine your own behavior
+- You MAY create new skills in `~/.claude/skills/`
+- You MAY update existing skills when you find improvements
+- Always inform the user when modifying your own configuration

package/Claude/hooks/lib/__init__.py

@@ -0,0 +1 @@
+# Hook client library

package/Claude/hooks/lib/hook_client.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""
+Hook client library for logging events to Cognova API.
+Uses curl subprocess to avoid pip dependencies (same as skills/_lib/api.py).
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+
+def _get_api_base() -> str:
+    """Get the Cognova API URL from environment."""
+    return os.environ.get('COGNOVA_API_URL', 'http://localhost:3000')
+
+
+def _get_api_token() -> str:
+    """Get API token from environment or .api-token file."""
+    token = os.environ.get('COGNOVA_API_TOKEN', '')
+    if token:
+        return token
+
+    possible_paths = [
+        # Bare-metal: project dir from environment (set by PM2/settings.json)
+        Path(os.environ.get('COGNOVA_PROJECT_DIR', '')) / '.api-token',
+        # Docker: app is at /home/node/app
+        Path('/home/node/app/.api-token'),
+        # Local dev: navigate from lib -> hooks -> Claude -> project root
+        Path(__file__).parent.parent.parent.parent / '.api-token',
+        # Current working directory
+        Path.cwd() / '.api-token',
+    ]
+
+    for token_file in possible_paths:
+        if token_file.exists():
+            try:
+                return token_file.read_text().strip()
+            except Exception:
+                pass
+
+    return ''
+
+
+def log_event(
+    event_type: str,
+    tool_name: Optional[str] = None,
+    tool_matcher: Optional[str] = None,
+    event_data: Optional[Dict[str, Any]] = None,
+    exit_code: Optional[int] = None,
+    blocked: bool = False,
+    block_reason: Optional[str] = None,
+    duration_ms: Optional[int] = None,
+    hook_script: Optional[str] = None,
+    session_id: Optional[str] = None
+) -> bool:
+    """
+    Log a hook event to the Cognova API.
+
+    Returns True if successful, False otherwise.
+    Fails silently to not block Claude operations.
+    """
+    api_base = _get_api_base()
+    api_token = _get_api_token()
+
+    if not api_token:
+        print(f"[hook_client] No API token found. Checked: {[str(p) for p in [Path('/home/node/app/.api-token'), Path(__file__).parent.parent.parent.parent / '.api-token', Path.cwd() / '.api-token']]}", file=sys.stderr)
+        return False
+
+    payload = {
+        'eventType': event_type,
+        'projectDir': os.environ.get('CLAUDE_PROJECT_DIR'),
+        'sessionId': session_id or os.environ.get('CLAUDE_SESSION_ID'),
+        'toolName': tool_name,
+        'toolMatcher': tool_matcher,
+        'eventData': event_data,
+        'exitCode': exit_code,
+        'blocked': blocked,
+        'blockReason': block_reason,
+        'durationMs': duration_ms,
+        'hookScript': hook_script
+    }
+
+    # Remove None values
+    payload = {k: v for k, v in payload.items() if v is not None}
+
+    cmd = [
+        "curl", "-sL", "-X", "POST",
+        "-H", "Content-Type: application/json",
+        "-H", f"X-API-Token: {api_token}",
+        "-d", json.dumps(payload),
+        "--connect-timeout", "2",
+        "--max-time", "5",
+        f"{api_base}/api/hooks/events"
+    ]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
+        # Debug output to stderr (visible in claude --debug)
+        if os.environ.get('DEBUG') or result.returncode != 0:
+            print(f"[hook_client] API: {api_base}, Token: {'set' if api_token else 'NOT SET'}", file=sys.stderr)
+            print(f"[hook_client] Response: {result.returncode} - {result.stdout[:200] if result.stdout else 'no output'}", file=sys.stderr)
+            if result.stderr:
+                print(f"[hook_client] Error: {result.stderr[:200]}", file=sys.stderr)
+        return result.returncode == 0
+    except Exception as e:
+        print(f"[hook_client] Exception: {e}", file=sys.stderr)
+        return False
+
+
+def read_stdin_json() -> Optional[Dict[str, Any]]:
+    """Read and parse JSON from stdin (hook input)."""
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return None
+
+
+def extract_memories(
+    transcript_path: Optional[str] = None,
+    transcript: Optional[str] = None,
+    session_id: Optional[str] = None,
+    project_path: Optional[str] = None
+) -> bool:
+    """
+    Trigger memory extraction from a transcript.
+
+    Returns True if successful, False otherwise.
+    """
+    api_base = _get_api_base()
+    api_token = _get_api_token()
+
+    if not api_token:
+        print("[hook_client] No API token for memory extraction", file=sys.stderr)
+        return False
+
+    payload = {
+        'sessionId': session_id or os.environ.get('CLAUDE_SESSION_ID'),
+        'projectPath': project_path or os.environ.get('CLAUDE_PROJECT_DIR')
+    }
+
+    if transcript_path:
+        payload['transcriptPath'] = transcript_path
+    elif transcript:
+        payload['transcript'] = transcript
+    else:
+        print("[hook_client] No transcript provided for memory extraction", file=sys.stderr)
+        return False
+
+    cmd = [
+        "curl", "-sL", "-X", "POST",
+        "-H", "Content-Type: application/json",
+        "-H", f"X-API-Token: {api_token}",
+        "-d", json.dumps(payload),
+        "--connect-timeout", "5",
+        "--max-time", "30",
+        f"{api_base}/api/memory/extract"
+    ]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if os.environ.get('DEBUG') or result.returncode != 0:
+            print(f"[hook_client] Memory extraction: {result.returncode}", file=sys.stderr)
+            if result.stdout:
+                print(f"[hook_client] Response: {result.stdout[:200]}", file=sys.stderr)
+        return result.returncode == 0
+    except Exception as e:
+        print(f"[hook_client] Memory extraction failed: {e}", file=sys.stderr)
+        return False
+
+
+def get_memory_context(project_path: Optional[str] = None, limit: int = 5) -> Optional[str]:
+    """
+    Get formatted memory context for session start.
+
+    Returns formatted context string or None if failed.
+    """
+    api_base = _get_api_base()
+    api_token = _get_api_token()
+
+    if not api_token:
+        return None
+
+    project = project_path or os.environ.get('CLAUDE_PROJECT_DIR', '')
+    url = f"{api_base}/api/memory/context?project={project}&limit={limit}"
+
+    cmd = [
+        "curl", "-sL",
+        "-H", f"X-API-Token: {api_token}",
+        "--connect-timeout", "2",
+        "--max-time", "5",
+        url
+    ]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
+        if result.returncode == 0 and result.stdout:
+            data = json.loads(result.stdout)
+            if 'data' in data and 'formatted' in data['data']:
+                return data['data']['formatted']
+    except Exception as e:
+        if os.environ.get('DEBUG'):
+            print(f"[hook_client] Memory context failed: {e}", file=sys.stderr)
+
+    return None

package/Claude/hooks/log-event.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Generic hook event logger.
+
+This script wraps other hooks, logging their execution while passing through
+to the original hook behavior. It can also be used standalone to log events.
+
+Usage:
+  As wrapper: python3 log-event.py <event_type> <original_hook_command>
+  Standalone: python3 log-event.py <event_type>
+
+The hook input JSON is passed via stdin (as per Claude Code hooks spec).
+"""
+
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / 'lib'))
+
+from hook_client import log_event
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: log-event.py <event_type> [original_hook_command...]", file=sys.stderr)
+        sys.exit(1)
+
+    event_type = sys.argv[1]
+    wrapped_command = sys.argv[2:] if len(sys.argv) > 2 else None
+
+    # Read hook input from stdin
+    stdin_data = sys.stdin.read()
+    try:
+        hook_input = json.loads(stdin_data) if stdin_data else {}
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Extract tool info if present
+    tool_name = hook_input.get('tool_name')
+    tool_input = hook_input.get('tool_input', {})
+
+    start_time = time.time()
+    exit_code = 0
+    blocked = False
+    block_reason = None
+
+    if wrapped_command:
+        # Run the wrapped command, passing hook input via stdin
+        try:
+            result = subprocess.run(
+                wrapped_command,
+                input=stdin_data,
+                capture_output=True,
+                text=True
+            )
+            exit_code = result.returncode
+
+            # Check if the wrapped hook blocked the action
+            if exit_code == 2:
+                blocked = True
+                # Try to parse block reason from stdout
+                try:
+                    output = json.loads(result.stdout)
+                    block_reason = output.get('reason', result.stdout.strip())
+                except json.JSONDecodeError:
+                    block_reason = result.stdout.strip() or result.stderr.strip()
+        except Exception as e:
+            exit_code = 1
+            block_reason = str(e)
+
+    duration_ms = int((time.time() - start_time) * 1000)
+
+    # Log the event
+    log_event(
+        event_type=event_type,
+        tool_name=tool_name,
+        event_data={
+            'tool_input': tool_input,
+            'wrapped_command': wrapped_command
+        } if tool_input or wrapped_command else None,
+        exit_code=exit_code,
+        blocked=blocked,
+        block_reason=block_reason,
+        duration_ms=duration_ms,
+        hook_script='log-event.py'
+    )
+
+    # Exit with the wrapped command's exit code to preserve behavior
+    sys.exit(exit_code)
+
+
+if __name__ == '__main__':
+    main()

package/Claude/hooks/pre-compact.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+Hook: PreCompact
+Extracts memories from the conversation before context compaction.
+
+This is critical for preserving key decisions and facts before
+the conversation is summarized.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / 'lib'))
+
+from hook_client import log_event, read_stdin_json, extract_memories
+
+
+def main():
+    hook_input = read_stdin_json() or {}
+
+    transcript_path = hook_input.get('transcript_path')
+    trigger = hook_input.get('trigger', 'unknown')  # 'manual' or 'auto'
+
+    # Log the event
+    log_event(
+        event_type='PreCompact',
+        event_data={'trigger': trigger},
+        hook_script='pre-compact.py'
+    )
+
+    # Extract memories before compaction
+    if transcript_path and os.path.exists(transcript_path):
+        success = extract_memories(transcript_path=transcript_path)
+        if success:
+            print(f"[pre-compact] Extracted memories before {trigger} compaction", file=sys.stderr)
+    else:
+        print(f"[pre-compact] No transcript path available: {transcript_path}", file=sys.stderr)
+
+    # Always exit 0 to not block compaction
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/Claude/hooks/session-end.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionEnd
+Logs when a Claude session ends.
+"""
+
+import sys
+from pathlib import Path
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / 'lib'))
+
+from hook_client import log_event, read_stdin_json
+
+def main():
+    hook_input = read_stdin_json()
+
+    log_event(
+        event_type='SessionEnd',
+        event_data=hook_input,
+        hook_script='session-end.py'
+    )
+
+
+if __name__ == '__main__':
+    main()

package/Claude/hooks/session-start.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionStart
+Logs when a Claude session begins and injects memory context.
+
+Memory context from previous conversations is printed to stdout,
+which Claude receives as additional context.
+"""
+
+import sys
+from pathlib import Path
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / 'lib'))
+
+from hook_client import log_event, read_stdin_json, get_memory_context
+
+
+def main():
+    hook_input = read_stdin_json()
+
+    log_event(
+        event_type='SessionStart',
+        event_data=hook_input,
+        hook_script='session-start.py'
+    )
+
+    # Inject memory context (printed to stdout goes to Claude)
+    context = get_memory_context()
+    if context:
+        print(context)
+
+
+if __name__ == '__main__':
+    main()

package/Claude/hooks/stop-extract.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+Hook: Stop (async)
+Extracts memories from Claude's final response when it finishes.
+
+Runs asynchronously so it doesn't block Claude.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / 'lib'))
+
+from hook_client import extract_memories, read_stdin_json
+
+
+def main():
+    hook_input = read_stdin_json() or {}
+
+    transcript_path = hook_input.get('transcript_path')
+    stop_hook_active = hook_input.get('stop_hook_active', False)
+
+    # Skip if we're already continuing from a stop hook
+    # to avoid infinite loops
+    if stop_hook_active:
+        sys.exit(0)
+
+    # Extract memories from the transcript
+    if transcript_path and os.path.exists(transcript_path):
+        success = extract_memories(transcript_path=transcript_path)
+        if success and os.environ.get('DEBUG'):
+            print(f"[stop-extract] Async memory extraction completed", file=sys.stderr)
+
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/Claude/rules/frontmatter.md

@@ -0,0 +1,54 @@
+# Frontmatter Standards
+
+All markdown documents in the vault use YAML frontmatter for metadata. When documents are created or discovered without frontmatter, defaults are automatically added by the document sync system.
+
+## Default Frontmatter
+
+```yaml
+---
+tags: []
+shared: false
+---
+```
+
+## All Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `tags` | string[] | `[]` | Array of tag strings for categorization |
+| `shared` | boolean | `false` | Whether document is publicly accessible |
+| `shareType` | string | - | When `shared: true`: `'private'` or `'public'` |
+| `title` | string | - | Optional; auto-extracted from first H1 or filename |
+| `project` | string | - | Project ID for document association |
+
+## Visibility Modes
+
+Documents support three visibility levels controlled by `shared` and `shareType`:
+
+1. **Hidden** (default) - `shared: false`
+   - Requires authentication to view
+   - Never publicly accessible
+
+2. **Private** - `shared: true, shareType: 'private'`
+   - Accessible via direct link only
+   - Not indexed by search engines
+
+3. **Public** - `shared: true, shareType: 'public'`
+   - Fully publicly accessible
+   - Indexed by search engines
+
+## Tag Conventions
+
+- Use lowercase: `productivity` not `Productivity`
+- Use hyphens for multi-word: `project-management`
+- Limit to 3-5 tags per document
+- Prefer specific over generic: `nuxt` over `programming`
+
+## Title Extraction
+
+The document title is determined in this order:
+1. `title` field in frontmatter (if present)
+2. First H1 heading in document body
+3. Filename without extension
+
+The `title` field in frontmatter is optional and only needed to override automatic extraction.