SessionAnchor 0.1.0__py3-none-any.whl

sessionanchor/__init__.py

@@ -0,0 +1,3 @@
+"""SessionAnchor: One-command context memory for Claude Code sessions."""
+
+__version__ = "0.1.0"

sessionanchor/__main__.py

@@ -0,0 +1,5 @@
+"""Support for `python -m sessionanchor`."""
+
+from .cli import main
+
+main()

sessionanchor/boot.py

@@ -0,0 +1,90 @@
+"""Boot script — outputs a compact context briefing at session start.
+
+Replaces loading large markdown files with a ~2000-token structured briefing.
+Runs automatic compaction before loading to prevent L1 bloat.
+"""
+
+import os
+import sys
+
+from .compact import compact_l1
+from .store import (
+    detect_project_name,
+    expire_stale_entries,
+    format_boot_context,
+    get_connection,
+    get_db_path,
+    get_l0,
+    get_l1,
+    get_last_session,
+    get_stats,
+    init_db,
+)
+
+
+def boot(project: str | None = None, full: bool = False,
+         db_path: str | None = None) -> str:
+    """Generate the boot briefing. Returns the formatted string."""
+    db = db_path or get_db_path()
+    if not os.path.exists(db):
+        return (
+            "# No memory database found.\n"
+            "# Run `sessionanchor init` to set up context memory for this project."
+        )
+
+    conn = get_connection(db)
+    init_db(conn)
+
+    # Housekeeping
+    expire_stale_entries(conn)
+    compact_l1(conn, project=project)
+
+    # Auto-detect project if not specified
+    if not project:
+        project = detect_project_name()
+
+    # Retrieve tiered context
+    l0 = get_l0(conn, project=project)
+    l1 = get_l1(conn, project=project)
+
+    briefing = format_boot_context(l0, l1, project=project)
+
+    if full:
+        stats = get_stats(conn, project=project)
+        lines = [
+            briefing,
+            "## Memory Store Stats",
+            f"  Entries by tier: {stats.get('by_tier', {})}",
+            f"  Entries by status: {stats.get('by_status', {})}",
+            f"  DB size: {stats.get('db_size_kb', '?')} KB",
+            f"  Total sessions: {stats.get('total_sessions', 0)}",
+        ]
+        last = get_last_session(conn, project=project)
+        if last:
+            lines.append(f"\n## Last Session")
+            lines.append(f"  Date: {last.get('ended_at', '?')}")
+            lines.append(f"  Summary: {last.get('summary', 'No summary')}")
+            lines.append(
+                f"  Tokens loaded: L0={last.get('l0_tokens', 0)} "
+                f"L1={last.get('l1_tokens', 0)} total={last.get('total_tokens', 0)}"
+            )
+        briefing = "\n".join(lines)
+
+    conn.close()
+    return briefing
+
+
+def main(args=None):
+    """CLI entry point for boot command."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Boot context briefing")
+    parser.add_argument("--project", "-p", default=None)
+    parser.add_argument("--full", action="store_true", help="Include stats and last session")
+    parser.add_argument("--db", default=None)
+    parsed = parser.parse_args(args)
+
+    output = boot(project=parsed.project, full=parsed.full, db_path=parsed.db)
+    sys.stdout.buffer.write(output.encode("utf-8"))
+    sys.stdout.buffer.write(b"\n")
+    sys.stdout.buffer.flush()

sessionanchor/cli.py

@@ -0,0 +1,86 @@
+"""Unified CLI entry point for SessionAnchor.
+
+Usage:
+    sessionanchor init              # Bootstrap memory for current repo
+    sessionanchor boot              # Print session briefing
+    sessionanchor save add ...      # Save a context entry
+    sessionanchor save complete ... # Mark entry completed
+    sessionanchor save session-end  # Record session summary
+    sessionanchor query "search"    # Deep search
+    sessionanchor index             # Re-index codebase
+    sessionanchor index find "X"    # Search codebase
+    sessionanchor index map         # Show structure
+    sessionanchor compact           # Manual compaction
+    sessionanchor stats             # Show memory stats
+"""
+
+import sys
+
+
+def main():
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        _print_help()
+        return
+
+    command = sys.argv[1]
+    rest = sys.argv[2:]
+
+    if command == "init":
+        from .init import main as init_main
+        init_main(rest)
+
+    elif command == "boot":
+        from .boot import main as boot_main
+        boot_main(rest)
+
+    elif command == "save":
+        from .save import main as save_main
+        save_main(rest)
+
+    elif command == "query":
+        from .query import main as query_main
+        query_main(rest)
+
+    elif command == "index":
+        from .index import main as index_main
+        index_main(rest)
+
+    elif command == "compact":
+        from .compact import main as compact_main
+        compact_main(rest)
+
+    elif command == "stats":
+        from .query import main as query_main
+        query_main(["--stats"] + rest)
+
+    elif command == "version":
+        from . import __version__
+        print(f"sessionanchor {__version__}")
+
+    else:
+        print(f"Unknown command: {command}")
+        print()
+        _print_help()
+        sys.exit(1)
+
+
+def _print_help():
+    print("SessionAnchor - One-command context memory for Claude Code")
+    print()
+    print("Commands:")
+    print("  init              Bootstrap memory for the current repo")
+    print("  boot              Print session briefing (~2000 tokens)")
+    print("  save add ...      Save a context entry")
+    print("  save complete ... Mark an entry as completed")
+    print("  save session-end  Record end-of-session summary")
+    print('  query "search"    Search memory (full-text)')
+    print("  index             Re-index the codebase")
+    print('  index find "X"    Search codebase files')
+    print("  index map         Show structural overview")
+    print("  compact           Run L1 compaction manually")
+    print("  stats             Show memory store statistics")
+    print("  version           Show version")
+    print()
+    print("Quick start:")
+    print("  sessionanchor init    # Run once per project")
+    print("  sessionanchor boot    # Run at start of every session")

sessionanchor/compact.py

@@ -0,0 +1,126 @@
+"""L1 compaction — prevents memory bloat over time.
+
+Strategies:
+- Time-based: L1 entries older than 14 days → demote to L2
+- Count cap: Keep max 20 active L1 entries; excess → L2
+- Completed: L1 entries completed > 3 days ago → L2
+- Superseded: Archive entries that have been superseded
+
+Runs automatically at boot, can also be triggered manually.
+"""
+
+import sqlite3
+from datetime import datetime, timedelta, timezone
+
+
+def compact_l1(
+    conn: sqlite3.Connection,
+    project: str | None = None,
+    max_age_days: int = 14,
+    max_entries: int = 20,
+    completed_grace_days: int = 3,
+) -> dict:
+    """Run all compaction strategies. Returns counts of demoted entries."""
+    now = datetime.now(timezone.utc).isoformat()
+    results = {"time_demoted": 0, "count_demoted": 0, "completed_demoted": 0, "superseded_archived": 0}
+
+    project_clause = ""
+    project_params: list = []
+    if project:
+        project_clause = " AND (project = ? OR project = 'global')"
+        project_params = [project]
+
+    # 1. Time-based: L1 entries older than max_age_days → L2
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=max_age_days)).isoformat()
+    cursor = conn.execute(
+        f"UPDATE entries SET tier = 'L2', updated_at = ? "
+        f"WHERE tier = 'L1' AND updated_at < ? AND status = 'active'{project_clause}",
+        [now, cutoff] + project_params,
+    )
+    results["time_demoted"] = cursor.rowcount
+
+    # 2. Completed items older than grace period → L2
+    comp_cutoff = (datetime.now(timezone.utc) - timedelta(days=completed_grace_days)).isoformat()
+    cursor = conn.execute(
+        f"UPDATE entries SET tier = 'L2', updated_at = ? "
+        f"WHERE tier = 'L1' AND status = 'completed' AND updated_at < ?{project_clause}",
+        [now, comp_cutoff] + project_params,
+    )
+    results["completed_demoted"] = cursor.rowcount
+
+    # 3. Superseded entries → archive
+    superseded_rows = conn.execute(
+        f"SELECT supersedes FROM entries "
+        f"WHERE supersedes IS NOT NULL AND TRIM(supersedes) != '' AND status = 'active'{project_clause}",
+        project_params,
+    ).fetchall()
+    superseded_ids: list[str] = []
+    for row in superseded_rows:
+        raw_value = row["supersedes"] if not isinstance(row, tuple) else row[0]
+        superseded_ids.extend(
+            entry_id.strip() for entry_id in raw_value.split(",") if entry_id.strip()
+        )
+    if superseded_ids:
+        placeholders = ",".join("?" * len(superseded_ids))
+        cursor = conn.execute(
+            f"UPDATE entries SET status = 'archived', updated_at = ? "
+            f"WHERE id IN ({placeholders}) AND status != 'archived'",
+            [now] + superseded_ids,
+        )
+        results["superseded_archived"] = cursor.rowcount
+
+    # 4. Count cap: if more than max_entries active L1, demote oldest
+    rows = conn.execute(
+        f"SELECT id FROM entries WHERE tier = 'L1' AND status = 'active'{project_clause} "
+        f"ORDER BY updated_at DESC",
+        project_params,
+    ).fetchall()
+
+    if len(rows) > max_entries:
+        excess_ids = [r["id"] for r in rows[max_entries:]]
+        placeholders = ",".join("?" * len(excess_ids))
+        cursor = conn.execute(
+            f"UPDATE entries SET tier = 'L2', updated_at = ? WHERE id IN ({placeholders})",
+            [now] + excess_ids,
+        )
+        results["count_demoted"] = cursor.rowcount
+
+    conn.commit()
+    return results
+
+
+def main(args=None):
+    """CLI entry point for compact command."""
+    import argparse
+    import os
+
+    from .store import get_connection, get_db_path, init_db, detect_project_name
+
+    parser = argparse.ArgumentParser(description="Compact L1 memory")
+    parser.add_argument("--project", "-p", default=None)
+    parser.add_argument("--max-age", type=int, default=14, help="Max age in days for L1 entries")
+    parser.add_argument("--max-entries", type=int, default=20, help="Max active L1 entries")
+    parser.add_argument("--db", default=None)
+    parsed = parser.parse_args(args)
+
+    db_path = parsed.db or get_db_path()
+    if not os.path.exists(db_path):
+        print("No memory database found.")
+        return
+
+    conn = get_connection(db_path)
+    init_db(conn)
+
+    project = parsed.project or detect_project_name()
+    results = compact_l1(conn, project=project,
+                         max_age_days=parsed.max_age, max_entries=parsed.max_entries)
+    conn.close()
+
+    total = sum(results.values())
+    if total == 0:
+        print("Nothing to compact.")
+    else:
+        print(f"Compacted {total} entries:")
+        for key, count in results.items():
+            if count:
+                print(f"  {key}: {count}")

sessionanchor/ignore.py

@@ -0,0 +1,97 @@
+"""Parser for .contextignore files.
+
+Gitignore-style pattern matching to exclude sensitive files from indexing
+and redact secret-like content from stored entries.
+"""
+
+import os
+import re
+from fnmatch import fnmatch
+from pathlib import Path
+
+# Patterns that indicate secrets in file content
+SECRET_PATTERNS = re.compile(
+    r"(?:"
+    r"AKIA[0-9A-Z]{16}"          # AWS access key
+    r"|sk-[a-zA-Z0-9]{20,}"      # OpenAI / Stripe secret key
+    r"|ghp_[a-zA-Z0-9]{36}"      # GitHub personal access token
+    r"|gho_[a-zA-Z0-9]{36}"      # GitHub OAuth token
+    r"|glpat-[a-zA-Z0-9\-]{20}"  # GitLab PAT
+    r"|xox[bsarp]-[a-zA-Z0-9\-]+" # Slack token
+    r"|Bearer\s+[a-zA-Z0-9\-._~+/]+=*"  # Bearer token
+    r"|eyJ[a-zA-Z0-9\-_]+\.eyJ"  # JWT
+    r")",
+    re.ASCII,
+)
+
+DEFAULT_PATTERNS = """\
+# Secrets & credentials
+.env
+.env.*
+*.key
+*.pem
+*.p12
+*.pfx
+
+# Build artifacts
+node_modules/
+dist/
+build/
+.next/
+__pycache__/
+*.pyc
+coverage/
+.vercel/
+vendor/
+
+# Large/binary files
+*.sqlite
+*.db
+*.wasm
+*.zip
+*.tar.gz
+*.jar
+
+# Claude's own memory
+.claude/memory/
+"""
+
+
+def load_patterns(repo_root: str) -> list[str]:
+    """Load ignore patterns from .contextignore, falling back to defaults."""
+    ignore_path = os.path.join(repo_root, ".contextignore")
+    if os.path.isfile(ignore_path):
+        with open(ignore_path, "r", encoding="utf-8", errors="replace") as f:
+            raw = f.read()
+    else:
+        raw = DEFAULT_PATTERNS
+
+    patterns = []
+    for line in raw.splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            patterns.append(line)
+    return patterns
+
+
+def should_ignore(rel_path: str, patterns: list[str]) -> bool:
+    """Check if a relative path matches any ignore pattern."""
+    parts = Path(rel_path).parts
+    for pattern in patterns:
+        # Directory pattern (ends with /)
+        if pattern.endswith("/"):
+            dir_name = pattern.rstrip("/")
+            if dir_name in parts:
+                return True
+        # File/glob pattern
+        else:
+            if fnmatch(os.path.basename(rel_path), pattern):
+                return True
+            if fnmatch(rel_path, pattern):
+                return True
+    return False
+
+
+def redact_secrets(text: str) -> str:
+    """Replace detected secret patterns with [REDACTED]."""
+    return SECRET_PATTERNS.sub("[REDACTED]", text)