chip-memory 1.1.0__py3-none-any.whl

chip_memory/__init__.py

@@ -0,0 +1,31 @@
+"""
+chip_memory — local-first, self-organizing memory layer for AI agents.
+
+Inspired by how microchips work: isolated nodes (transistors) organized in
+layers, with a daemon (electricity) always running, become a CPU (a brain).
+
+Public API:
+  - chip_memory.search   — semantic search over the brain
+  - chip_memory.health   — brain health score + per-domain stats
+  - chip_memory.auto_write  — extract nodes from a transcript
+  - chip_memory.pending  — process pending/ → write nodes
+  - chip_memory.seed     — seed demo nodes for trying the system
+  - chip_memory.rebalance — adjust importance/heat of existing nodes
+  - chip_memory.daemon   — the always-on loop
+  - chip_memory.server   — tiny HTTP API (run separately)
+"""
+__version__ = "1.1.0"
+__all__ = [
+    "api",
+    "auto_write",
+    "daemon",
+    "dashboard",
+    "health",
+    "node",
+    "paths",
+    "pending",
+    "rebalance",
+    "search",
+    "seed",
+    "server",
+]

chip_memory/__main__.py

@@ -0,0 +1,83 @@
+"""CLI entry point: `python3 -m chip_memory <command> [args]`
+
+Examples:
+  python3 -m chip_memory search "what do I know about polish ecommerce"
+  python3 -m chip_memory health
+  python3 -m chip_memory health --json
+  python3 -m chip_memory seed
+  python3 -m chip_memory auto-write --input examples/example_session.md
+  python3 -m chip_memory daemon
+  python3 -m chip_memory server --port 7331
+  python3 -m chip_memory rebalance --tags "portfolio,career"
+"""
+import argparse
+import sys
+
+from . import __version__
+
+
+COMMANDS = {
+    "absorb": ("chip_memory.collect.absorb", "Absorb knowledge from shell history, git, and Claude Code sessions"),
+    "audit": ("chip_memory.contradiction", "Detect contradictions and anomalies in the brain"),
+    "auto-write": ("chip_memory.auto_write", "Extract memory nodes from a session transcript"),
+    "autowrite": ("chip_memory.auto_write", "Extract memory nodes from a session transcript"),
+    "connect": ("chip_memory.connect_cmd", "Find the path connecting two entities through typed edges"),
+    "consolidate": ("chip_memory.consolidation", "Run consolidation pass — cluster related knowledge"),
+    "daemon": ("chip_memory.daemon", "Start the always-on daemon loop"),
+    "dashboard": ("chip_memory.dashboard_cmd", "Launch the web dashboard"),
+    "doctor": ("chip_memory.doctor", "Run diagnostic checks on the brain"),
+    "eval": ("chip_memory.eval", "Run evaluation benchmarks"),
+    "export": ("chip_memory.export", "Export the brain as Markdown"),
+    "export-wiki": ("chip_memory.export_wiki", "Export a Karpathy-style LLM wiki"),
+    "health": ("chip_memory.health", "Show brain health score and per-domain stats"),
+    "hermes": ("chip_memory.hermes", "Hermes bridge — quick context queries"),
+    "hubs": ("chip_memory.map_cmd", "List hub nodes (highly-connected)"),
+    "map": ("chip_memory.map_cmd", "Explore the knowledge graph structure"),
+    "mcp": ("chip_memory.mcp_server", "Start MCP server for Claude Desktop/Code"),
+    "pending": ("chip_memory.pending", "Process pending items into memory nodes"),
+    "rebalance": ("chip_memory.rebalance", "Adjust importance and heat of existing nodes"),
+    "recall": ("chip_memory.recall", "Query episodic memory from the timeline"),
+    "remember": ("chip_memory.api", "Remember a fact (CLI wrapper for the API)"),
+    "review": ("chip_memory.collect.review_cli", "Review collected items before absorbing"),
+    "search": ("chip_memory.search", "Semantic search over the brain"),
+    "seed": ("chip_memory.seed", "Seed demo nodes for testing"),
+    "think": ("chip_memory.synthesis.think", "Think mode — answer a query with cited evidence and knowledge gaps"),
+    "server": ("chip_memory.server", "Start the HTTP API server"),
+    "signal": ("chip_memory.collect.signal_detector", "Signal detector — auto-ingest knowledge from agent messages"),
+    "telegram": ("chip_memory.telegram_watch", "Start Telegram watch daemon"),
+    "timeline": ("chip_memory.timeline_cmd", "Show the brain timeline diary"),
+    "tui": ("chip_memory.tui", "Launch the curses TUI"),
+    "uninstall": ("chip_memory.uninstall", "Safely remove chip-memory data"),
+    "watch-context": ("chip_memory.watch_context", "Watch and log context queries"),
+    "why": ("chip_memory.why", "Show detailed provenance and usage info for a node"),
+}
+
+
+def main():
+    # Handle --version before any command dispatch
+    if "--version" in sys.argv:
+        ap = argparse.ArgumentParser(add_help=False)
+        ap.add_argument("--version", action="version", version=f"chip-memory {__version__}")
+        ap.parse_args(["--version"])  # exits after printing version
+
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help", "help"):
+        print(__doc__)
+        print("\nAvailable commands:")
+        for cmd in sorted(COMMANDS):
+            module, desc = COMMANDS[cmd]
+            print(f"  {cmd:20s} {desc}")
+        sys.exit(0 if len(sys.argv) >= 2 else 1)
+
+    cmd = sys.argv[1]
+    if cmd not in COMMANDS:
+        print(f"unknown command: {cmd!r}\navailable: {', '.join(sorted(COMMANDS))}")
+        sys.exit(2)
+
+    # Re-exec as `python3 -m <module>` with the rest of argv
+    import runpy
+    sys.argv = [sys.argv[0]] + sys.argv[2:]
+    runpy.run_module(COMMANDS[cmd][0], run_name="__main__", alter_sys=True)
+
+
+if __name__ == "__main__":
+    main()

chip_memory/_stopwords.py

@@ -0,0 +1,52 @@
+"""
+Shared stopword set used by both BM25 search and the linker.
+
+Single source of truth — if you need to add or remove a stopword,
+do it here and both modules pick up the change automatically.
+"""
+STOPWORDS = frozenset({
+    # Articles & basic determiners
+    "the", "a", "an", "and", "or", "but", "if", "then", "so", "that",
+    "this", "these", "those", "each", "every", "other", "another",
+    "some", "any", "no", "none", "both", "either", "neither",
+
+    # Prepositions
+    "to", "of", "in", "on", "at", "by", "for", "with", "from",
+    "into", "about", "since", "though", "although", "whether",
+    "rather", "instead", "therefore", "thus", "hence", "whereas",
+    "whereby",
+
+    # Verbs (common)
+    "is", "are", "was", "were", "be", "been", "being", "have",
+    "has", "had", "do", "does", "done", "doing", "make", "made",
+    "makes", "using", "used", "uses", "get", "got", "gets",
+    "getting", "set", "sets", "put", "puts", "take", "takes",
+    "took", "taken", "give", "gave", "given", "find", "found",
+    "finds", "keep", "kept", "keeps", "tell", "tells", "told",
+    "ask", "asks", "asked", "seem", "seems", "seemed", "show",
+    "shows", "showed", "shown", "know", "knew", "known", "need",
+    "needs", "want", "wanted", "wants", "going", "goes",
+
+    # Modals & auxiliaries
+    "will", "would", "could", "should", "can", "may", "might",
+    "must", "shall",
+
+    # Pronouns & possessives
+    "they", "them", "their", "there", "your", "yours", "our",
+    "ours", "my", "mine", "its", "who", "whom", "whose",
+    "which", "where", "when", "what", "while",
+
+    # Common adverbs
+    "also", "just", "like", "such", "only", "very", "more",
+    "most", "much", "many", "really", "actually", "probably",
+    "maybe", "perhaps", "always", "never", "often", "sometimes",
+    "usually", "however", "because",
+
+    # Quantifiers / indefinite
+    "thing", "things", "kind", "sort", "way", "ways",
+    "anyone", "anywhere", "something", "nothing", "everything",
+    "someone", "everyone",
+
+    # Extra high-frequency noise
+    "than", "then", "also", "upon", "versus", "via",
+})

chip_memory/_utils.py

@@ -0,0 +1,38 @@
+"""
+chip_memory._utils — shared utility functions.
+
+Centralizing common patterns (ISO date parsing, text truncation, word
+extraction) to eliminate duplication across the codebase.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime
+
+
+_WORD_RE = re.compile(r"[\w_]+")
+
+
+def parse_iso_datetime(s: str) -> datetime:
+    """Parse an ISO 8601 datetime string, handling 'Z' suffix."""
+    return datetime.fromisoformat(s.replace("Z", "+00:00"))
+
+
+def truncate_preview(text: str, max_len: int = 120) -> str:
+    """Truncate text to max_len with ellipsis if needed."""
+    if len(text) > max_len:
+        return text[:max_len] + "..."
+    return text
+
+
+def extract_words(text: str) -> list[str]:
+    """Extract lowercase word tokens from text using regex.
+
+    Returns all word-like tokens (letters, digits, underscore).
+    Returns empty list for None or empty input.
+    """
+    if not text:
+        return []
+    return _WORD_RE.findall(text.lower())
+
+