memorytrace 0.1.0__py3-none-any.whl

engram/__init__.py

@@ -0,0 +1,8 @@
+"""Engram — AI agent memory system with persistent, structured, trustworthy memory."""
+
+__version__ = "0.1.0"
+
+from engram.engine import MemoryEngine, StoreResult
+from engram.config import EngramConfig
+
+__all__ = ["MemoryEngine", "StoreResult", "EngramConfig", "__version__"]

engram/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m engram`."""
+
+from engram.cli.app import main
+
+if __name__ == "__main__":
+    main()

engram/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI interface for Engram."""

engram/cli/app.py

@@ -0,0 +1,291 @@
+"""CLI entry point for Engram."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from engram.config import EngramConfig
+from engram.engine import MemoryEngine
+from engram.models.entity import Tier
+from engram.models.search import SearchOptions
+from engram.models.source import Source, SourceType
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="engram",
+        description="Engram — AI agent memory system",
+    )
+    parser.add_argument("--db", default=None, help="Database path")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--quiet", action="store_true", help="Suppress non-essential output")
+    parser.add_argument("--verbose", action="store_true", help="Show detailed error info")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # init
+    sub.add_parser("init", help="Initialize memory database")
+
+    _source_choices = ["user_input", "direct_speech", "document", "api", "web", "agent_inference"]
+
+    # store
+    p = sub.add_parser("store", help="Extract and store information from text")
+    p.add_argument("text", nargs="?", help="Text to process (or read from stdin)")
+    p.add_argument("--source-type", default="user_input", choices=_source_choices, help="Source type")
+    p.add_argument("--confidence", type=float, default=1.0, help="Source confidence")
+    p.add_argument("--author", default="", help="Source author")
+
+    # search
+    p = sub.add_parser("search", help="Search memory")
+    p.add_argument("query", help="Search query")
+    p.add_argument("--max-results", type=int, default=10)
+    p.add_argument("--max-tokens", type=int, default=500)
+    p.add_argument("--min-confidence", type=float, default=0.0)
+    p.add_argument("--type", dest="entity_type", default="")
+    p.add_argument("--tier", default="")
+
+    # get
+    p = sub.add_parser("get", help="Get entity details")
+    p.add_argument("name", help="Entity name")
+
+    # list
+    p = sub.add_parser("list", help="List entities")
+    p.add_argument("--type", dest="entity_type", default="")
+    p.add_argument("--tier", default="")
+    p.add_argument("--limit", type=int, default=50)
+
+    # add-fact
+    p = sub.add_parser("add-fact", help="Add a fact to an entity")
+    p.add_argument("entity", help="Entity name")
+    p.add_argument("fact", help="Fact text")
+    p.add_argument("--predicate", default="attribute")
+    p.add_argument("--source-type", default="user_input", choices=_source_choices)
+    p.add_argument("--confidence", type=float, default=1.0)
+
+    # create
+    p = sub.add_parser("create", help="Create a new entity")
+    p.add_argument("name", help="Entity name")
+    p.add_argument("--type", dest="entity_type", default="person")
+    p.add_argument("--tier", default="recall")
+    p.add_argument("--summary", default="")
+
+    # conflicts
+    sub.add_parser("conflicts", help="Show pending conflicts")
+
+    # resolve
+    p = sub.add_parser("resolve", help="Resolve a conflict")
+    p.add_argument("conflict_id", help="Conflict ID")
+    p.add_argument("resolution", choices=["accept_new", "keep_old", "merge"])
+
+    # health
+    sub.add_parser("health", help="Run health checks")
+
+    # export
+    p = sub.add_parser("export", help="Export to Markdown")
+    p.add_argument("--dir", default=None, help="Export directory")
+
+    # reindex
+    sub.add_parser("reindex", help="Rebuild search index")
+
+    # serve
+    p = sub.add_parser("serve", help="Start MCP server")
+    p.add_argument("--transport", default="stdio", choices=["stdio", "sse"])
+    p.add_argument("--port", type=int, default=8080)
+
+    return parser
+
+
+def _make_engine(args) -> MemoryEngine:
+    """Create engine from CLI args."""
+    config = EngramConfig()
+    if args.db:
+        db_path = Path(args.db).expanduser().resolve()
+        config.base_dir = db_path.parent
+        config.db_name = db_path.name
+    return MemoryEngine(config)
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Main CLI entry point. Returns exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    from engram.cli.formatters import (
+        format_entity,
+        format_entity_list,
+        format_search_result,
+        format_store_result,
+        format_health,
+    )
+
+    engine = None
+    try:
+        engine = _make_engine(args)
+
+        if args.command == "init":
+            if not args.quiet:
+                print(f"Memory initialized at {engine.config.db_path}")
+            return 0
+
+        elif args.command == "store":
+            max_input = 1024 * 1024  # 1MB limit for stdin
+            text = args.text or sys.stdin.read(max_input)
+            source = Source(
+                type=SourceType(args.source_type),
+                confidence=args.confidence,
+                author=args.author,
+                channel="cli",
+            )
+            result = engine.store(text, source=source)
+            if args.json:
+                print(result.to_json())
+            else:
+                print(format_store_result(result))
+
+        elif args.command == "search":
+            options = SearchOptions(
+                query=args.query,
+                max_results=args.max_results,
+                max_tokens=args.max_tokens,
+                min_confidence=args.min_confidence,
+            )
+            if args.entity_type:
+                options.entity_types = [args.entity_type]
+            if args.tier:
+                options.tiers = [args.tier]
+            result = engine.search(args.query, options)
+            if args.json:
+                print(result.to_json())
+            else:
+                print(format_search_result(result))
+
+        elif args.command == "get":
+            entity = engine.get_entity(args.name)
+            if entity:
+                facts = engine.get_facts(args.name)
+                if args.json:
+                    print(json.dumps({
+                        "name": entity.name,
+                        "type": entity.entity_type,
+                        "tier": entity.tier.value,
+                        "summary": entity.summary,
+                        "facts": [{"text": f.raw_text, "confidence": f.confidence} for f in facts],
+                    }, ensure_ascii=False, indent=2))
+                else:
+                    print(format_entity(entity, facts))
+            else:
+                print(f"  Entity '{args.name}' not found.", file=sys.stderr)
+                engine.close()
+                return 1
+
+        elif args.command == "list":
+            tier = Tier(args.tier) if args.tier else None
+            entities = engine.list_entities(
+                tier=tier,
+                entity_type=args.entity_type or None,
+                limit=args.limit,
+            )
+            if args.json:
+                print(json.dumps([
+                    {"name": e.name, "type": e.entity_type, "tier": e.tier.value}
+                    for e in entities
+                ], ensure_ascii=False, indent=2))
+            else:
+                print(format_entity_list(entities))
+
+        elif args.command == "add-fact":
+            source = Source(
+                type=SourceType(args.source_type),
+                confidence=args.confidence,
+                channel="cli",
+            )
+            result = engine.add_fact(args.entity, args.fact, predicate=args.predicate, source=source)
+            if args.json:
+                print(json.dumps({"action": result.action.value, "confidence": result.confidence}, indent=2))
+            else:
+                print(f"  Result: {result.action.value} (confidence: {result.confidence:.2f})")
+
+        elif args.command == "create":
+            tier = Tier(args.tier)
+            entity = engine.create_entity(args.name, entity_type=args.entity_type, tier=tier, summary=args.summary)
+            if args.json:
+                print(json.dumps({"id": entity.id, "name": entity.name}, ensure_ascii=False, indent=2))
+            else:
+                print(f"  Created: {entity.name} ({entity.entity_type}, {entity.tier.value})")
+
+        elif args.command == "conflicts":
+            conflicts = engine.storage.get_pending_conflicts()
+            if args.json:
+                print(json.dumps(conflicts, ensure_ascii=False, indent=2))
+            else:
+                if not conflicts:
+                    print("  No pending conflicts.")
+                else:
+                    for c in conflicts:
+                        print(f"  [{c['id'][:8]}] {c['conflict_type']} — {c.get('suggested_resolution', 'N/A')}")
+
+        elif args.command == "resolve":
+            engine.resolve_conflict(args.conflict_id, args.resolution)
+            print(f"  Conflict {args.conflict_id[:8]} resolved: {args.resolution}")
+
+        elif args.command == "health":
+            health = engine.health_check()
+            if args.json:
+                print(json.dumps(health, indent=2))
+            else:
+                print(format_health(health))
+
+        elif args.command == "export":
+            if args.dir:
+                engine.config.export_dir_name = args.dir
+            count = engine.export_markdown()
+            print(f"  Exported {count} entities to {engine.config.export_dir}")
+
+        elif args.command == "reindex":
+            count = engine.reindex()
+            print(f"  Reindexed {count} entities.")
+
+        elif args.command == "serve":
+            _run_mcp_server(args)
+            return 0
+
+        return 0
+
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if hasattr(args, "verbose") and args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        if engine is not None:
+            engine.close()
+
+
+def _run_mcp_server(args) -> None:
+    """Start MCP server (requires mcp package)."""
+    try:
+        from engram.integrations.mcp_server import run_server
+        run_server(transport=args.transport, port=args.port)
+    except ImportError:
+        print("MCP server requires 'mcp' package. Install with: pip install engram[mcp]", file=sys.stderr)
+        sys.exit(1)
+
+
+def cli_entry() -> None:
+    """Entry point for setuptools console_scripts (expects no return value)."""
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    cli_entry()

engram/cli/formatters.py

@@ -0,0 +1,90 @@
+"""Human-readable output formatters for CLI."""
+
+from __future__ import annotations
+
+from engram.models.entity import Entity
+from engram.models.fact import Fact
+from engram.models.search import SearchResult
+from engram.engine import StoreResult
+
+
+def format_entity(entity: Entity, facts: list[Fact] = None) -> str:
+    """Format an entity for CLI display."""
+    lines = [f"  {entity.name} [{entity.entity_type}] (tier: {entity.tier.value})"]
+    if entity.state.role:
+        lines.append(f"    Role: {entity.state.role}")
+    if entity.state.affiliation:
+        lines.append(f"    Affiliation: {entity.state.affiliation}")
+    if entity.summary:
+        lines.append(f"    Summary: {entity.summary}")
+    if facts:
+        lines.append(f"    Facts: {len(facts)}")
+        for f in facts[:5]:
+            conf = f"[{f.confidence:.0%}]"
+            lines.append(f"      - {f.raw_text} {conf}")
+    return "\n".join(lines)
+
+
+def format_entity_list(entities: list[Entity]) -> str:
+    """Format a list of entities for CLI display."""
+    if not entities:
+        return "  No entities found."
+    lines = []
+    for e in entities:
+        tier_tag = f"[{e.tier.value}]"
+        type_tag = f"({e.entity_type})"
+        lines.append(f"  {e.name} {type_tag} {tier_tag}")
+    return "\n".join(lines)
+
+
+def format_search_result(result: SearchResult) -> str:
+    """Format search results for CLI display."""
+    if not result.hits:
+        return f"  No results for '{result.query}'."
+
+    lines = [f"  Found {result.total_count} result(s) for '{result.query}' ({result.search_time_ms:.1f}ms)"]
+    lines.append("")
+    for i, hit in enumerate(result.hits, 1):
+        score = f"[{hit.relevance_score:.2f}]"
+        lines.append(f"  {i}. {hit.entity.name} ({hit.entity.entity_type}) {score}")
+        if hit.snippet:
+            lines.append(f"     {hit.snippet[:120]}")
+        if hit.facts:
+            for f in hit.facts[:3]:
+                lines.append(f"     - {f.raw_text}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_store_result(result: StoreResult) -> str:
+    """Format store operation result for CLI display."""
+    parts = []
+    if result.entities_created:
+        names = ", ".join(e.name for e in result.entities_created)
+        parts.append(f"  Created {len(result.entities_created)} entity(s): {names}")
+    if result.entities_updated:
+        names = ", ".join(e.name for e in result.entities_updated)
+        parts.append(f"  Updated {len(result.entities_updated)} entity(s): {names}")
+    if result.facts_added:
+        parts.append(f"  Added {len(result.facts_added)} fact(s)")
+    if result.facts_quarantined:
+        parts.append(f"  Quarantined {len(result.facts_quarantined)} fact(s) (low confidence)")
+    if result.facts_conflicted:
+        parts.append(f"  Conflicted {len(result.facts_conflicted)} fact(s)")
+    if result.relations_added:
+        parts.append(f"  Added {len(result.relations_added)} relation(s)")
+
+    if not parts:
+        return "  No entities or facts extracted."
+    return "\n".join(parts)
+
+
+def format_health(health: dict) -> str:
+    """Format health check result."""
+    lines = [
+        f"  Entities: {health['entity_count']}",
+        f"  Facts: {health['fact_count']}",
+        f"  Pending conflicts: {health['pending_conflicts']}",
+        f"  Status: {health['status']}",
+    ]
+    return "\n".join(lines)

engram/cli/simple.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Engram — simple CLI interface.
+
+Usage:
+    engram init
+    engram save "Minseong Jeong is the Space King of Galaxy Corp"
+    engram find "Space King"
+    engram who "Minseong Jeong"
+    engram remember "Minseong Jeong" "Loves AI and space"
+    engram all
+    engram status
+    engram forget "Old Entity"
+    engram export
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from engram.config import EngramConfig
+from engram.engine import MemoryEngine
+
+_DB_DIR = Path.home() / ".engram"
+_engine = None
+
+
+def _get_engine() -> MemoryEngine:
+    global _engine
+    if _engine is None:
+        _engine = MemoryEngine(EngramConfig(base_dir=_DB_DIR))
+    return _engine
+
+
+def _print_help():
+    print("""
+  engram — AI agent memory system
+
+  Commands:
+    engram init                          Initialize memory
+    engram save "text"                   Extract & store information
+    engram find "query"                  Search memory
+    engram who "name"                    Look up entity
+    engram remember "name" "fact"        Manually add a fact
+    engram all                           List all entities
+    engram status                        Health check
+    engram forget "name"                 Delete entity
+    engram export                        Export to Markdown
+
+  Examples:
+    engram save "Minseong Jeong is the Space King of Galaxy Corp"
+    engram find "Space King"
+    engram who "Minseong Jeong"
+    engram remember "정민성" "AI 전문가이다"
+
+  Install:
+    pip install git+https://github.com/aop60003/default.git
+""")
+
+
+def main() -> int:
+    args = sys.argv[1:]
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        _print_help()
+        return 0
+
+    cmd = args[0]
+    rest = " ".join(args[1:]) if len(args) > 1 else ""
+
+    try:
+        engine = _get_engine()
+
+        # ── init ──
+        if cmd == "init":
+            print(f"  Memory initialized at {engine.config.db_path}")
+
+        # ── save ──
+        elif cmd == "save":
+            if not rest:
+                print("  Usage: engram save \"text to remember\"")
+                return 1
+            result = engine.store(rest)
+            created = [e.name for e in result.entities_created]
+            updated = [e.name for e in result.entities_updated]
+            if created:
+                print(f"  New: {', '.join(created)}")
+            if updated:
+                print(f"  Updated: {', '.join(updated)}")
+            if result.facts_added:
+                print(f"  Learned {len(result.facts_added)} fact(s)")
+            if not created and not updated and not result.facts_added:
+                print("  Saved (no entities auto-detected)")
+
+        # ── find ──
+        elif cmd in ("find", "search"):
+            if not rest:
+                print("  Usage: engram find \"search query\"")
+                return 1
+            result = engine.search(rest)
+            if not result.hits:
+                print(f"  Nothing found for \"{rest}\"")
+            else:
+                for h in result.hits:
+                    print(f"  {h.entity.name} ({h.entity.entity_type})")
+                    if h.entity.summary:
+                        print(f"    {h.entity.summary}")
+                    for f in h.facts[:3]:
+                        print(f"    - {f.raw_text}")
+
+        # ── who ──
+        elif cmd in ("who", "get"):
+            if not rest:
+                print("  Usage: engram who \"entity name\"")
+                return 1
+            entity = engine.get_entity(rest)
+            if not entity:
+                print(f"  \"{rest}\" not found.")
+                return 1
+            print(f"  {entity.name} [{entity.entity_type}]")
+            if entity.summary:
+                print(f"  {entity.summary}")
+            if entity.state.role:
+                print(f"  Role: {entity.state.role}")
+            if entity.state.affiliation:
+                print(f"  At: {entity.state.affiliation}")
+            if entity.aliases:
+                print(f"  Also known as: {', '.join(entity.aliases)}")
+            facts = engine.get_facts(rest)
+            if facts:
+                print(f"  Facts ({len(facts)}):")
+                for f in facts:
+                    print(f"    - {f.raw_text}")
+
+        # ── remember ──
+        elif cmd == "remember":
+            # Parse: remember "Name" "Fact"
+            parts = _parse_quoted_args(args[1:])
+            if len(parts) < 2:
+                print('  Usage: engram remember "Name" "Fact to remember"')
+                return 1
+            name, fact = parts[0], " ".join(parts[1:])
+            if not engine.get_entity(name):
+                engine.create_entity(name)
+                print(f"  Created: {name}")
+            result = engine.add_fact(name, fact)
+            print(f"  Remembered ({result.confidence:.0%} confidence)")
+
+        # ── all / list ──
+        elif cmd in ("all", "list"):
+            entities = engine.list_entities(limit=50)
+            if not entities:
+                print("  No memories yet. Try: engram save \"some info\"")
+            else:
+                print(f"  {len(entities)} entities:")
+                for e in entities:
+                    line = f"    {e.name} ({e.entity_type})"
+                    if e.summary:
+                        line += f" — {e.summary[:50]}"
+                    print(line)
+
+        # ── status ──
+        elif cmd == "status":
+            h = engine.health_check()
+            print(f"  Entities: {h['entity_count']}")
+            print(f"  Facts:    {h['fact_count']}")
+            print(f"  Conflicts: {h['pending_conflicts']}")
+            print(f"  Status:   {h['status']}")
+            print(f"  DB: {engine.config.db_path}")
+
+        # ── forget ──
+        elif cmd == "forget":
+            if not rest:
+                print("  Usage: engram forget \"entity name\"")
+                return 1
+            entity = engine.get_entity(rest)
+            if entity:
+                engine.storage.delete_entity(entity.id)
+                print(f"  Forgot: {rest}")
+            else:
+                print(f"  \"{rest}\" not found.")
+
+        # ── export ──
+        elif cmd == "export":
+            count = engine.export_markdown()
+            print(f"  Exported {count} entities to {engine.config.export_dir}")
+
+        # ── json ──
+        elif cmd == "json":
+            # engram json find "query" / engram json who "name"
+            if len(args) < 3:
+                print("  Usage: engram json find/who/all \"query\"")
+                return 1
+            subcmd = args[1]
+            subrest = " ".join(args[2:])
+            if subcmd == "find":
+                result = engine.search(subrest)
+                print(result.to_json())
+            elif subcmd == "who":
+                entity = engine.get_entity(subrest)
+                if entity:
+                    facts = engine.get_facts(subrest)
+                    print(json.dumps({
+                        "name": entity.name, "type": entity.entity_type,
+                        "tier": entity.tier.value, "summary": entity.summary,
+                        "role": entity.state.role, "affiliation": entity.state.affiliation,
+                        "facts": [{"text": f.raw_text, "confidence": f.confidence} for f in facts],
+                    }, ensure_ascii=False, indent=2))
+                else:
+                    print(json.dumps({"error": f"'{subrest}' not found"}, indent=2))
+            elif subcmd == "all":
+                entities = engine.list_entities(limit=100)
+                print(json.dumps([
+                    {"name": e.name, "type": e.entity_type, "tier": e.tier.value}
+                    for e in entities
+                ], ensure_ascii=False, indent=2))
+
+        else:
+            print(f"  Unknown command: {cmd}")
+            _print_help()
+            return 1
+
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        print(f"  Error: {e}", file=sys.stderr)
+        return 1
+    finally:
+        if _engine:
+            _engine.close()
+
+    return 0
+
+
+def _parse_quoted_args(args: list) -> list[str]:
+    """Parse arguments respecting quotes: 'Name' 'Fact here' → ['Name', 'Fact here']"""
+    joined = " ".join(args)
+    parts = []
+    current = ""
+    in_quote = False
+    quote_char = ""
+    for ch in joined:
+        if ch in ('"', "'") and not in_quote:
+            in_quote = True
+            quote_char = ch
+        elif ch == quote_char and in_quote:
+            in_quote = False
+            if current:
+                parts.append(current)
+                current = ""
+        elif ch == " " and not in_quote and current:
+            parts.append(current)
+            current = ""
+        elif ch != " " or in_quote:
+            current += ch
+    if current:
+        parts.append(current)
+    return parts
+
+
+def cli_entry():
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    cli_entry()