memograph 0.0.2__py3-none-any.whl

memograph/__init__.py

@@ -0,0 +1,5 @@
+from .core.enums import MemoryType
+from .core.kernel import MemoryKernel
+
+__version__ = "0.0.2"
+__all__ = ["MemoryKernel", "MemoryType"]

memograph/cli.py

@@ -0,0 +1,192 @@
+import argparse
+import json
+import os
+from urllib import error, request
+
+from .core.assistant import build_answer_prompt, retrieve_cited_context, run_answer
+from .core.enums import MemoryType
+from .core.kernel import MemoryKernel
+
+
+def _run_ask(kernel: MemoryKernel, args) -> None:
+    if args.provider == "claude" and not os.environ.get("ANTHROPIC_API_KEY"):
+        raise RuntimeError("Set ANTHROPIC_API_KEY or use --provider ollama.")
+
+    def ask_once(query_text: str) -> None:
+        context, sources = retrieve_cited_context(
+            kernel=kernel,
+            query=query_text,
+            tags=args.tags,
+            depth=args.depth,
+            top_k=args.top_k,
+            token_limit=args.token_limit,
+        )
+        prompt = build_answer_prompt(context=context, query=query_text)
+        try:
+            answer = run_answer(
+                provider=args.provider,
+                prompt=prompt,
+                model=args.model,
+                max_tokens=args.max_tokens,
+                temperature=args.temperature,
+                base_url=args.base_url,
+            )
+        except Exception as exc:
+            print(f"LLM error: {exc}")
+            return
+
+        if args.show_context:
+            print("=== Retrieved Context ===")
+            print(context)
+            print()
+
+        print("=== Answer ===")
+        print(answer)
+
+        if sources and not args.no_citations:
+            print("\n=== Sources ===")
+            for src in sources:
+                tags = ", ".join(src.tags) if src.tags else "-"
+                print(
+                    f"[{src.source_id}] {src.title} (id={src.node_id}, type={src.memory_type}, tags={tags})"
+                )
+
+    if args.chat:
+        print("Interactive chat mode. Type 'exit' or 'quit' to stop.")
+        while True:
+            query_text = input("you> ").strip()
+            if not query_text:
+                continue
+            if query_text.lower() in {"exit", "quit"}:
+                print("bye")
+                break
+            ask_once(query_text)
+            print()
+        return
+
+    if not args.query:
+        raise RuntimeError("Provide --query for non-chat mode.")
+    ask_once(args.query)
+
+
+def _run_doctor(args) -> None:
+    print("=== Mnemo Doctor ===")
+    vault = MemoryKernel(args.vault)
+    stats = vault.ingest(force=False)
+    print(f"vault: {vault.vault_path}")
+    print(f"indexed: {stats['indexed']} | skipped: {stats['skipped']} | total: {stats['total']}")
+
+    anth_key = os.environ.get("ANTHROPIC_API_KEY")
+    print(f"claude_api_key: {'present' if anth_key else 'missing'}")
+
+    ollama_url = (
+        args.ollama_url or os.environ.get("OLLAMA_BASE_URL") or "http://localhost:11434"
+    ).rstrip("/")
+    tags_url = f"{ollama_url}/api/tags"
+    try:
+        req = request.Request(tags_url, method="GET")
+        with request.urlopen(req, timeout=5) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+        models = payload.get("models", [])
+        print(f"ollama: reachable ({len(models)} models) @ {ollama_url}")
+    except error.URLError as exc:
+        print(f"ollama: unreachable @ {ollama_url} ({exc})")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Mnemo CLI")
+    parser.add_argument("--vault", default="~/my-vault", help="Path to memory vault")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    ingest_parser = subparsers.add_parser("ingest", help="Index all markdown memories")
+    ingest_parser.add_argument("--force", action="store_true", help="Reindex all files")
+
+    remember_parser = subparsers.add_parser("remember", help="Create a new memory note")
+    remember_parser.add_argument("--title", required=True, help="Memory title")
+    remember_parser.add_argument("--content", required=True, help="Memory content")
+    remember_parser.add_argument(
+        "--type",
+        choices=[member.value for member in MemoryType],
+        default=MemoryType.FACT.value,
+        help="Memory type",
+    )
+    remember_parser.add_argument(
+        "--tags",
+        nargs="*",
+        default=[],
+        help="Tags (with or without # prefix)",
+    )
+
+    context_parser = subparsers.add_parser("context", help="Build context window for a query")
+    context_parser.add_argument("--query", required=True, help="Query text")
+    context_parser.add_argument("--tags", nargs="*", default=[], help="Optional tag filter")
+    context_parser.add_argument("--depth", type=int, default=2, help="Graph traversal depth")
+    context_parser.add_argument("--top-k", type=int, default=8, help="Max memories to return")
+    context_parser.add_argument(
+        "--token-limit", type=int, default=2048, help="Compression token limit"
+    )
+
+    ask_parser = subparsers.add_parser("ask", help="Ask an LLM with retrieved memory context")
+    ask_parser.add_argument(
+        "--provider", choices=["claude", "ollama"], default="ollama", help="LLM provider"
+    )
+    ask_parser.add_argument("--query", help="Question text (omit in --chat mode)")
+    ask_parser.add_argument("--chat", action="store_true", help="Interactive chat mode")
+    ask_parser.add_argument("--tags", nargs="*", default=[], help="Optional tag filter")
+    ask_parser.add_argument("--depth", type=int, default=2, help="Graph traversal depth")
+    ask_parser.add_argument("--top-k", type=int, default=8, help="Max memories to retrieve")
+    ask_parser.add_argument(
+        "--token-limit", type=int, default=2048, help="Context compression budget"
+    )
+    ask_parser.add_argument("--model", default=None, help="Provider-specific model")
+    ask_parser.add_argument("--base-url", default=None, help="Provider base URL override")
+    ask_parser.add_argument("--max-tokens", type=int, default=1024, help="Max generated tokens")
+    ask_parser.add_argument("--temperature", type=float, default=0.1, help="Sampling temperature")
+    ask_parser.add_argument("--show-context", action="store_true", help="Print context sent to LLM")
+    ask_parser.add_argument("--no-citations", action="store_true", help="Hide source list output")
+
+    doctor_parser = subparsers.add_parser(
+        "doctor", help="Run environment and integration diagnostics"
+    )
+    doctor_parser.add_argument("--ollama-url", default=None, help="Override Ollama base URL")
+
+    args = parser.parse_args()
+    kernel = MemoryKernel(args.vault)
+
+    if args.command == "ingest":
+        print(kernel.ingest(force=args.force))
+        return
+
+    if args.command == "remember":
+        path = kernel.remember(
+            title=args.title,
+            content=args.content,
+            memory_type=MemoryType(args.type),
+            tags=args.tags,
+        )
+        print(f"Created memory: {path}")
+        return
+
+    if args.command == "context":
+        context = kernel.context_window(
+            query=args.query,
+            tags=args.tags,
+            depth=args.depth,
+            top_k=args.top_k,
+            token_limit=args.token_limit,
+        )
+        print(context)
+        return
+
+    if args.command == "ask":
+        _run_ask(kernel, args)
+        return
+
+    if args.command == "doctor":
+        _run_doctor(args)
+        return
+
+
+if __name__ == "__main__":
+    main()

memograph/core/__init__.py

@@ -0,0 +1,5 @@
+from .enums import MemoryType
+from .kernel import MemoryKernel
+from .node import MemoryNode
+
+__all__ = ["MemoryKernel", "MemoryNode", "MemoryType"]

memograph/core/assistant.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .kernel import MemoryKernel
+from .node import MemoryNode
+
+
+@dataclass
+class SourceRef:
+    source_id: str
+    node_id: str
+    title: str
+    memory_type: str
+    tags: list[str]
+
+
+def build_cited_context(
+    nodes: list[MemoryNode],
+    token_limit: int = 2048,
+    chars_per_token: float = 3.8,
+) -> tuple[str, list[SourceRef]]:
+    char_limit = int(token_limit * chars_per_token)
+    sections: list[str] = []
+    sources: list[SourceRef] = []
+    total = 0
+    separator = "\n\n---\n\n"
+
+    for index, node in enumerate(nodes, start=1):
+        sid = f"S{index}"
+        tags = ", ".join(node.tags) if node.tags else "-"
+        header = f"[{sid}] {node.title} | type={node.memory_type.value} | tags={tags}"
+        chunk = f"{header}\n{node.content}"
+
+        projected = total + len(chunk) + (len(separator) if sections else 0)
+        if projected > char_limit:
+            remaining = char_limit - total
+            if remaining > 120:
+                truncated = chunk[:remaining].rstrip() + "…"
+                sections.append(truncated)
+                sources.append(
+                    SourceRef(
+                        source_id=sid,
+                        node_id=node.id,
+                        title=node.title,
+                        memory_type=node.memory_type.value,
+                        tags=node.tags,
+                    )
+                )
+            break
+
+        sections.append(chunk)
+        sources.append(
+            SourceRef(
+                source_id=sid,
+                node_id=node.id,
+                title=node.title,
+                memory_type=node.memory_type.value,
+                tags=node.tags,
+            )
+        )
+        total = projected
+
+    return separator.join(sections), sources
+
+
+def build_answer_prompt(context: str, query: str) -> str:
+    return (
+        "You are a helpful assistant. Use memory context only when relevant. "
+        "If context is insufficient, say what is missing. "
+        "When you use evidence, cite source markers like [S1], [S2].\n\n"
+        f"<memory>\n{context}\n</memory>\n\n"
+        f"User question: {query}"
+    )
+
+
+def run_answer(
+    provider: str,
+    prompt: str,
+    model: str | None = None,
+    max_tokens: int = 1024,
+    temperature: float = 0.1,
+    base_url: str | None = None,
+) -> str:
+    if provider == "claude":
+        from ..adapters.llm.claude import ClaudeLLMClient, ClaudeLLMConfig
+
+        client = ClaudeLLMClient(base_url=base_url)
+        # Default to a widely available model if not specified, though future models may differ.
+        config = ClaudeLLMConfig(
+            model=model or "claude-3-5-sonnet-20240620",
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        return client.generate(prompt=prompt, config=config)
+
+    if provider == "ollama":
+        from ..adapters.llm.ollama import OllamaLLMClient, OllamaLLMConfig
+
+        client = OllamaLLMClient(base_url=base_url)
+        config = OllamaLLMConfig(
+            model=model or "llama3.1:8b",
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        return client.generate(prompt=prompt, config=config)
+
+    raise ValueError(f"Unsupported provider: {provider}")
+
+
+def retrieve_cited_context(
+    kernel: MemoryKernel,
+    query: str,
+    tags: list[str] | None = None,
+    depth: int = 2,
+    top_k: int = 8,
+    token_limit: int = 2048,
+) -> tuple[str, list[SourceRef]]:
+    nodes = kernel.retrieve_nodes(query=query, tags=tags, depth=depth, top_k=top_k)
+    return build_cited_context(nodes=nodes, token_limit=token_limit)

memograph/core/compressor.py

@@ -0,0 +1,21 @@
+# core/compressor.py
+from .node import MemoryNode
+
+
+class TokenCompressor:
+    def __init__(self, token_limit: int = 4096, chars_per_token: float = 3.8):
+        self.char_limit = int(token_limit * chars_per_token)
+
+    def compress(self, nodes: list[MemoryNode], separator: str = "\n\n---\n\n") -> str:
+        parts, total = [], 0
+        for node in nodes:
+            chunk = f"## {node.title}\n*Type: {node.memory_type.value} | Salience: {node.salience:.2f}*\n\n{node.content}"
+            if total + len(chunk) > self.char_limit:
+                # Truncate last entry to fit
+                remaining = self.char_limit - total
+                if remaining > 100:
+                    parts.append(chunk[:remaining] + "…")
+                break
+            parts.append(chunk)
+            total += len(chunk) + len(separator)
+        return separator.join(parts)

memograph/core/enums.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class MemoryType(Enum):
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+    FACT = "fact"

memograph/core/graph.py

@@ -0,0 +1,74 @@
+# core/graph.py
+from collections import defaultdict, deque
+
+from .node import MemoryNode
+
+
+class VaultGraph:
+    def __init__(self):
+        self._nodes: dict[str, MemoryNode] = {}
+        self._adjacency: dict[str, set[str]] = defaultdict(set)
+
+    def add_node(self, node: MemoryNode):
+        self._nodes[node.id] = node
+        for link in node.links:
+            self._adjacency[node.id].add(link)
+
+    def build_backlinks(self):
+        """Populate backlinks after all nodes are loaded."""
+        backlink_map: dict[str, list[str]] = defaultdict(list)
+        for node_id, targets in self._adjacency.items():
+            for target in targets:
+                backlink_map[target].append(node_id)
+        for node_id, node in self._nodes.items():
+            node.backlinks = backlink_map.get(node_id, [])
+
+    def get(self, node_id: str) -> MemoryNode | None:
+        return self._nodes.get(node_id)
+
+    def neighbors(self, node_id: str, depth: int = 1) -> list[MemoryNode]:
+        """BFS traversal up to `depth` hops, following both links and backlinks."""
+        visited, queue = set(), deque([(node_id, 0)])
+        result = []
+        while queue:
+            curr_id, d = queue.popleft()
+            if curr_id in visited or d > depth:
+                continue
+            visited.add(curr_id)
+            if node := self._nodes.get(curr_id):
+                if curr_id != node_id:
+                    result.append(node)
+                if d < depth:
+                    for nxt in self._adjacency[curr_id] | set(node.backlinks):
+                        queue.append((nxt, d + 1))
+        return result
+
+    def remove_node(self, node_id: str):
+        """Remove a node from the graph (e.g., when a file is deleted)."""
+        if node_id in self._nodes:
+            # Remove the node itself
+            del self._nodes[node_id]
+
+            # Remove from adjacency list
+            if node_id in self._adjacency:
+                del self._adjacency[node_id]
+
+            # Remove any references to this node in other adjacency lists
+            for adj_set in self._adjacency.values():
+                adj_set.discard(node_id)
+
+    def all_nodes(self) -> list[MemoryNode]:
+        """Return all nodes in the graph."""
+        return list(self._nodes.values())
+
+    def filter(self, tags=None, memory_type=None, min_salience=0.0) -> list[MemoryNode]:
+        results = []
+        for node in self._nodes.values():
+            if tags and not set(tags).intersection(node.tags):
+                continue
+            if memory_type and node.memory_type != memory_type:
+                continue
+            if node.salience < min_salience:
+                continue
+            results.append(node)
+        return sorted(results, key=lambda n: n.salience, reverse=True)

memograph/core/indexer.py

@@ -0,0 +1,173 @@
+# core/indexer.py
+import json
+from pathlib import Path
+
+from .graph import VaultGraph
+from .parser import parse_file
+
+CACHE_FILE = ".memograph_cache.json"
+GRAPH_CACHE_FILE = ".memograph_graph.json"
+EMBEDDINGS_CACHE_FILE = ".memograph_embeddings.json"
+
+
+class VaultIndexer:
+    def __init__(self, vault_root: Path, embedding_adapter=None):
+        self.root = vault_root
+        self.cache_path = vault_root / CACHE_FILE
+        self.graph_cache_path = vault_root / GRAPH_CACHE_FILE
+        self.embeddings_cache_path = vault_root / EMBEDDINGS_CACHE_FILE
+        self.embedding_adapter = embedding_adapter
+        self._mtime_cache: dict[str, float] = self._load_cache()
+        self._embeddings_cache: dict[str, list[float]] = self._load_embeddings_cache()
+
+    def _load_cache(self) -> dict[str, float]:
+        if self.cache_path.exists():
+            try:
+                return json.loads(self.cache_path.read_text())
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+    def _save_cache(self, mtimes: dict[str, float]):
+        self.cache_path.write_text(json.dumps(mtimes))
+        self._mtime_cache = mtimes
+
+    def _load_embeddings_cache(self) -> dict[str, list[float]]:
+        """Load cached embeddings from disk."""
+        if self.embeddings_cache_path.exists():
+            try:
+                return json.loads(self.embeddings_cache_path.read_text())
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+    def _save_embeddings_cache(self):
+        """Save embeddings cache to disk."""
+        self.embeddings_cache_path.write_text(json.dumps(self._embeddings_cache))
+
+    def _load_graph_from_cache(self, graph: VaultGraph) -> bool:
+        """Load previously indexed graph state from cache. Returns True if successful."""
+        if not self.graph_cache_path.exists():
+            return False
+
+        try:
+            cache_data = json.loads(self.graph_cache_path.read_text())
+            # Reconstruct nodes from cached data
+            for node_data in cache_data.get("nodes", []):
+                # Import here to avoid circular dependency
+                from .enums import MemoryType
+                from .node import MemoryNode
+
+                node = MemoryNode(
+                    id=node_data["id"],
+                    title=node_data["title"],
+                    content=node_data["content"],
+                    memory_type=MemoryType[node_data["memory_type"]],
+                    tags=node_data["tags"],
+                    links=node_data["links"],
+                    backlinks=node_data["backlinks"],
+                    salience=node_data["salience"],
+                    access_count=node_data["access_count"],
+                    source_path=node_data.get("source_path"),
+                )
+                # Restore embedding if available
+                if node.id in self._embeddings_cache:
+                    node.embedding = self._embeddings_cache[node.id]
+                graph.add_node(node)
+            return True
+        except (json.JSONDecodeError, KeyError, ValueError):
+            return False
+
+    def _save_graph_to_cache(self, graph: VaultGraph):
+        """Save graph state to cache for faster subsequent loads."""
+        nodes_data = []
+        for node in graph.all_nodes():
+            nodes_data.append(
+                {
+                    "id": node.id,
+                    "title": node.title,
+                    "content": node.content,
+                    "memory_type": node.memory_type.name,
+                    "tags": node.tags,
+                    "links": node.links,
+                    "backlinks": node.backlinks,
+                    "salience": node.salience,
+                    "access_count": node.access_count,
+                    "source_path": node.source_path,
+                }
+            )
+
+        cache_data = {"nodes": nodes_data}
+        self.graph_cache_path.write_text(json.dumps(cache_data, indent=2))
+
+    def index(self, graph: VaultGraph, force=False) -> tuple[int, int]:
+        """Returns (indexed, skipped) counts."""
+        new_mtimes = {}
+        indexed = skipped = 0
+
+        if not self.root.exists():
+            self.root.mkdir(parents=True, exist_ok=True)
+
+        # Load existing graph from cache if not forcing rebuild
+        if not force and self._load_graph_from_cache(graph):
+            # Graph loaded from cache, now check for changes
+            current_files = set()
+
+            for md_file in self.root.rglob("*.md"):
+                if md_file.name in [CACHE_FILE, GRAPH_CACHE_FILE, EMBEDDINGS_CACHE_FILE]:
+                    continue
+
+                rel = md_file.relative_to(self.root).as_posix()
+                current_files.add(rel)
+                mtime = md_file.stat().st_mtime
+                new_mtimes[rel] = mtime
+
+                unchanged = self._mtime_cache.get(rel) == mtime
+                if unchanged:
+                    skipped += 1
+                else:
+                    # File is new or modified - parse and update
+                    node = parse_file(md_file, self.root)
+                    self._generate_and_cache_embedding(node)
+                    graph.add_node(node)
+                    indexed += 1
+
+            # Remove nodes for deleted files
+            cached_files = set(self._mtime_cache.keys())
+            deleted_files = cached_files - current_files
+            for deleted_rel in deleted_files:
+                # Extract node ID from relative path
+                node_id = Path(deleted_rel).stem
+                if graph.get(node_id):
+                    graph.remove_node(node_id)
+        else:
+            # Force rebuild or no cache - parse all files
+            for md_file in self.root.rglob("*.md"):
+                if md_file.name in [CACHE_FILE, GRAPH_CACHE_FILE, EMBEDDINGS_CACHE_FILE]:
+                    continue
+
+                rel = md_file.relative_to(self.root).as_posix()
+                mtime = md_file.stat().st_mtime
+                new_mtimes[rel] = mtime
+
+                node = parse_file(md_file, self.root)
+                self._generate_and_cache_embedding(node)
+                graph.add_node(node)
+                indexed += 1
+
+        graph.build_backlinks()
+        self._save_cache(new_mtimes)
+        self._save_graph_to_cache(graph)
+        self._save_embeddings_cache()
+        return indexed, skipped
+
+    def _generate_and_cache_embedding(self, node):
+        """Generate and cache embedding for a node if adapter is available."""
+        if self.embedding_adapter:
+            # Check if we already have a cached embedding
+            if node.id in self._embeddings_cache:
+                node.embedding = self._embeddings_cache[node.id]
+            else:
+                # Generate new embedding
+                node.embedding = self.embedding_adapter.embed(node.content)
+                self._embeddings_cache[node.id] = node.embedding

memograph/core/kernel.py

@@ -0,0 +1,128 @@
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from .compressor import TokenCompressor
+from .enums import MemoryType
+from .graph import VaultGraph
+from .indexer import VaultIndexer
+from .node import MemoryNode
+from .retriever import HybridRetriever
+
+
+class MemoryKernel:
+    def __init__(self, vault_path: str, embedding_adapter=None):
+        self.vault_path = Path(vault_path).expanduser()
+        self.vault_path.mkdir(parents=True, exist_ok=True)
+
+        self.graph = VaultGraph()
+        self.embedding_adapter = embedding_adapter
+        self.indexer = VaultIndexer(self.vault_path, embedding_adapter=embedding_adapter)
+        self.retriever = HybridRetriever(self.graph, embedding_adapter=embedding_adapter)
+
+    @staticmethod
+    def _normalize_tags(tags: list[str] | None) -> list[str]:
+        if not tags:
+            return []
+        normalized = []
+        for tag in tags:
+            clean = tag.strip().lstrip("#")
+            if clean:
+                normalized.append(clean)
+        return normalized
+
+    @staticmethod
+    def _slugify(text: str) -> str:
+        slug = re.sub(r"[^a-zA-Z0-9]+", "-", text.strip().lower()).strip("-")
+        return slug or datetime.now(timezone.utc).strftime("memory-%Y%m%d-%H%M%S")
+
+    def ingest(self, force: bool = False) -> dict[str, int]:
+        """
+        Ingests all memories from the vault.
+        """
+        self.graph = VaultGraph()
+        indexed, skipped = self.indexer.index(self.graph, force=force)
+        self.retriever = HybridRetriever(self.graph, embedding_adapter=self.retriever.embeddings)
+        total = len(self.graph._nodes)
+        return {"indexed": indexed, "skipped": skipped, "total": total}
+
+    def remember(
+        self,
+        title: str,
+        content: str,
+        memory_type: MemoryType = MemoryType.FACT,
+        tags: list[str] = None,
+    ):
+        """
+        Creates a new memory.
+        """
+        normalized_tags = self._normalize_tags(tags)
+        slug = self._slugify(title)
+        file_path = self.vault_path / f"{slug}.md"
+
+        counter = 2
+        while file_path.exists():
+            file_path = self.vault_path / f"{slug}-{counter}.md"
+            counter += 1
+
+        created_at = datetime.now(timezone.utc).isoformat()
+        tags_line = " ".join(f"#{tag}" for tag in normalized_tags)
+
+        payload = {
+            "title": title,
+            "memory_type": memory_type.value,
+            "created": created_at,
+            "salience": 1.0,
+        }
+        frontmatter = "---\n" + yaml.safe_dump(payload, sort_keys=False).strip() + "\n---\n\n"
+
+        body = content.strip()
+        if tags_line:
+            body = f"{body}\n\n{tags_line}"
+
+        file_path.write_text(frontmatter + body + "\n", encoding="utf-8")
+        return str(file_path)
+
+    def context_window(
+        self,
+        query: str,
+        tags: list[str] = None,
+        depth: int = 2,
+        top_k: int = 8,
+        token_limit: int = 2048,
+    ) -> str:
+        """
+        Retrieves relevant context from the memory vault.
+        """
+        nodes = self.retrieve_nodes(query=query, tags=tags, depth=depth, top_k=top_k)
+        compressor = TokenCompressor(token_limit=token_limit)
+        return compressor.compress(nodes)
+
+    def retrieve_nodes(
+        self,
+        query: str,
+        tags: list[str] = None,
+        depth: int = 2,
+        top_k: int = 8,
+    ) -> list[MemoryNode]:
+        normalized_tags = self._normalize_tags(tags)
+
+        if not self.graph._nodes:
+            self.ingest()
+
+        query_words = [w.lower() for w in re.findall(r"\w+", query) if len(w) > 2]
+        seed_ids = []
+        for node in self.graph._nodes.values():
+            haystack = f"{node.title} {node.content}".lower()
+            if any(word in haystack for word in query_words):
+                seed_ids.append(node.id)
+
+        return self.retriever.retrieve(
+            query=query,
+            seed_ids=seed_ids,
+            tags=normalized_tags,
+            depth=depth,
+            top_k=top_k,
+        )

memograph/core/node.py

@@ -0,0 +1,35 @@
+# core/node.py
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from .enums import MemoryType
+
+
+@dataclass
+class MemoryNode:
+    id: str  # Derived from file path (slug)
+    title: str
+    content: str
+    memory_type: MemoryType = MemoryType.SEMANTIC
+
+    # Graph relationships
+    links: list[str] = field(default_factory=list)  # Outgoing wikilinks
+    backlinks: list[str] = field(default_factory=list)  # Populated by graph
+    tags: list[str] = field(default_factory=list)
+
+    # Metadata / reinforcement signals
+    salience: float = 1.0  # 0.0–1.0, boosted on access/linking
+    access_count: int = 0
+    last_accessed: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    modified_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    # Source file path
+    source_path: str | None = None
+
+    # Arbitrary YAML frontmatter passthrough
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+
+    # Optional: set by embedding adapter
+    embedding: list[float] | None = None

memograph/core/parser.py

@@ -0,0 +1,58 @@
+# core/parser.py
+import contextlib
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from .enums import MemoryType
+from .node import MemoryNode
+
+WIKILINK_RE = re.compile(r"\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]")
+TAG_RE = re.compile(r"(?:^|\s)#([\w/-]+)")
+FRONTMATTER_RE = re.compile(r"^---\r?\n(.*?)\r?\n---\r?\n", re.DOTALL)
+
+
+def parse_file(path: Path, vault_root: Path) -> MemoryNode:
+    raw = path.read_text(encoding="utf-8").lstrip("\ufeff")
+    frontmatter = {}
+    content = raw
+
+    if m := FRONTMATTER_RE.match(raw):
+        with contextlib.suppress(yaml.YAMLError):
+            frontmatter = yaml.safe_load(m.group(1)) or {}
+        content = raw[m.end() :]
+
+    links = [link.lower().replace(" ", "-") for link in WIKILINK_RE.findall(content)]
+    tags = TAG_RE.findall(content)
+
+    node_id = path.relative_to(vault_root).with_suffix("").as_posix()
+    node_id = node_id.lower().replace(" ", "-")
+
+    stat = path.stat()
+
+    try:
+        mem_type = MemoryType(frontmatter.get("memory_type", MemoryType.SEMANTIC.value))
+    except (TypeError, ValueError):
+        mem_type = MemoryType.SEMANTIC
+
+    created = frontmatter.get("created")
+    try:
+        created_at = datetime.fromisoformat(created) if created else datetime.now(timezone.utc)
+    except (TypeError, ValueError):
+        created_at = datetime.now(timezone.utc)
+
+    return MemoryNode(
+        id=node_id,
+        title=frontmatter.get("title", path.stem),
+        content=content.strip(),
+        memory_type=mem_type,
+        links=links,
+        tags=tags,
+        salience=float(frontmatter.get("salience", 1.0)),
+        created_at=created_at,
+        modified_at=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc),
+        source_path=str(path),
+        frontmatter=frontmatter,
+    )

memograph/core/retriever.py

@@ -0,0 +1,81 @@
+# core/retriever.py
+from .enums import MemoryType
+from .graph import VaultGraph
+from .node import MemoryNode
+
+
+class HybridRetriever:
+    def __init__(self, graph: VaultGraph, embedding_adapter=None):
+        self.graph = graph
+        self.embeddings = embedding_adapter  # Optional
+
+    def retrieve(
+        self,
+        query: str,
+        seed_ids: list[str] = None,
+        tags: list[str] = None,
+        memory_type: MemoryType = None,
+        depth: int = 2,
+        top_k: int = 10,
+        min_salience: float = 0.0,
+    ) -> list[MemoryNode]:
+
+        candidates: dict[str, MemoryNode] = {}
+
+        # 1. Graph traversal from seeds
+        for seed_id in seed_ids or []:
+            seed = self.graph.get(seed_id)
+            if seed:
+                candidates[seed.id] = seed
+            neighbors = self.graph.neighbors(seed_id, depth=depth)
+            for n in neighbors:
+                candidates[n.id] = n
+
+        # 2. Metadata filter
+        # Only fetch from full graph if filters are applied or we have no seeds
+        filters_active = (tags is not None) or (memory_type is not None) or (min_salience > 0.0)
+
+        if filters_active or not candidates:
+            filtered = self.graph.filter(
+                tags=tags, memory_type=memory_type, min_salience=min_salience
+            )
+            for n in filtered:
+                candidates[n.id] = n
+
+        # 3. Optional: re-rank with vector similarity
+        if self.embeddings and query:
+            candidates = self._rerank(query, list(candidates.values()))
+        else:
+            candidates = sorted(
+                candidates.values(), key=lambda n: (n.salience, n.access_count), reverse=True
+            )
+
+        return candidates[:top_k]
+
+    def _rerank(self, query: str, nodes: list[MemoryNode]) -> list[MemoryNode]:
+        q_emb = self.embeddings.embed(query)
+        scored = []
+        for node in nodes:
+            if node.embedding is None:
+                node.embedding = self.embeddings.embed(node.content)
+            sim = self._cosine_similarity(q_emb, node.embedding)
+            scored.append((sim, node))
+        return [n for _, n in sorted(scored, key=lambda x: x[0], reverse=True)]
+
+    @staticmethod
+    def _cosine_similarity(left: list[float], right: list[float]) -> float:
+        """Calculate cosine similarity between two vectors (normalized dot product)."""
+        if not left or not right:
+            return 0.0
+
+        size = min(len(left), len(right))
+        dot_product = sum(left[i] * right[i] for i in range(size))
+
+        # Calculate magnitudes
+        mag_left = sum(x * x for x in left[:size]) ** 0.5
+        mag_right = sum(x * x for x in right[:size]) ** 0.5
+
+        if mag_left == 0 or mag_right == 0:
+            return 0.0
+
+        return dot_product / (mag_left * mag_right)

memograph-0.0.2.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: memograph
+Version: 0.0.2
+Summary: A graph-based memory system for LLMs with intelligent retrieval using knowledge graphs, hybrid search, and semantic embeddings
+Author-email: MemoGraph Contributors <author@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Indhar01/MemoGraph
+Project-URL: Documentation, https://github.com/Indhar01/MemoGraph#readme
+Project-URL: Repository, https://github.com/Indhar01/MemoGraph
+Project-URL: Issues, https://github.com/Indhar01/MemoGraph/issues
+Project-URL: Changelog, https://github.com/Indhar01/MemoGraph/blob/main/CHANGELOG.md
+Keywords: llm,memory,knowledge-graph,rag,retrieval,ai,machine-learning,graph-database,semantic-search,vector-embeddings,chatgpt,claude,ollama,langchain,llamaindex,markdown,note-taking,personal-knowledge-management,pkm,second-brain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Requires-Dist: tiktoken>=0.5.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.39.0; extra == "anthropic"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3.0; extra == "ollama"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
+Requires-Dist: numpy>=1.24.0; extra == "embeddings"
+Provides-Extra: all
+Requires-Dist: memograph[anthropic,embeddings,ollama,openai]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.7.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Requires-Dist: black>=23.11.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# MemoGraph 🧠
+
+[![PyPI version](https://img.shields.io/pypi/v/memograph)](https://pypi.org/project/memograph/)
+[![Python Version](https://img.shields.io/pypi/pyversions/memograph)](https://pypi.org/project/memograph/)
+[![License](https://img.shields.io/github/license/Indhar01/MemoGraph)](https://github.com/Indhar01/MemoGraph/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+
+A graph-based memory system for LLMs with intelligent retrieval. MemoGraph provides a powerful solution to the LLM memory problem by combining knowledge graphs, hybrid retrieval, and semantic search.
+
+## ✨ Features
+
+- **Graph-Based Memory**: Navigate knowledge using bidirectional wikilinks and backlinks
+- **Hybrid Retrieval**: Combines keyword matching, graph traversal, and optional vector embeddings
+- **Markdown-Native**: Human-readable markdown files with YAML frontmatter
+- **Memory Types**: Support for episodic, semantic, procedural, and fact-based memories
+- **Smart Indexing**: Efficient caching system that only re-indexes changed files
+- **CLI & Python API**: Use via command line or integrate into your Python applications
+- **Multiple LLM Providers**: Works with Ollama, Claude, and OpenAI
+- **Context Compression**: Intelligent token budgeting for optimal context windows
+- **Salience Scoring**: Memory importance ranking for better retrieval
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install memograph
+```
+
+Install with optional dependencies:
+
+```bash
+# For OpenAI support
+pip install memograph[openai]
+
+# For Anthropic Claude support
+pip install memograph[anthropic]
+
+# For Ollama support
+pip install memograph[ollama]
+
+# For embedding support
+pip install memograph[embeddings]
+
+# Install everything
+pip install memograph[all]
+```
+
+### Python Usage
+
+```python
+from memograph import MemoryKernel, MemoryType
+
+# Initialize the kernel attached to your vault path
+kernel = MemoryKernel("~/my-vault")
+
+# Ingest all notes in the vault
+stats = kernel.ingest()
+print(f"Indexed {stats['indexed']} memories.")
+
+# Programmatically add a new memory
+kernel.remember(
+    title="Meeting Note",
+    content="Decided to use BFS graph traversal for retrieval.",
+    memory_type=MemoryType.EPISODIC,
+    tags=["design", "retrieval"]
+)
+
+# Retrieve context for an LLM query
+context = kernel.context_window(
+    query="how does retrieval work?",
+    tags=["retrieval"],
+    depth=2,
+    top_k=8
+)
+
+print(context)
+```
+
+## 🎯 CLI Usage
+
+MemoGraph comes with a powerful CLI for managing your vault and chatting with it.
+
+### Ingest
+
+Index your markdown files into the graph database:
+
+```bash
+memograph --vault ~/my-vault ingest
+```
+
+Force re-indexing all files:
+
+```bash
+memograph --vault ~/my-vault ingest --force
+```
+
+### Remember
+
+Quickly add a memory from the command line:
+
+```bash
+memograph --vault ~/my-vault remember \
+    --title "Team Sync" \
+    --content "Discussed Q3 goals." \
+    --tags planning q3
+```
+
+### Context Window
+
+Generate context for a query:
+
+```bash
+memograph --vault ~/my-vault context \
+    --query "What did we decide about the database?" \
+    --tags architecture \
+    --depth 2 \
+    --top-k 5
+```
+
+### Ask (Interactive Chat)
+
+Start an interactive chat session with your vault context:
+
+```bash
+memograph --vault ~/my-vault ask --chat --provider ollama --model llama3
+```
+
+Or ask a single question:
+
+```bash
+memograph --vault ~/my-vault ask \
+    --query "Summarize our design decisions" \
+    --provider claude \
+    --model claude-3-5-sonnet-20240620
+```
+
+### Diagnostics
+
+Check your environment and connection to LLM providers:
+
+```bash
+memograph --vault ~/my-vault doctor
+```
+
+## 📖 Core Concepts
+
+### Memory Types
+
+MemoGraph supports different types of memories inspired by cognitive science:
+
+- **Episodic**: Personal experiences and events (e.g., meeting notes)
+- **Semantic**: Facts and general knowledge (e.g., documentation)
+- **Procedural**: How-to knowledge and processes (e.g., tutorials)
+- **Fact**: Discrete factual information (e.g., configuration values)
+
+### Graph Traversal
+
+The library uses BFS (Breadth-First Search) to traverse your knowledge graph:
+
+```python
+# Retrieve nodes with depth=2 (2 hops from seed nodes)
+nodes = kernel.retrieve_nodes(
+    query="graph algorithms",
+    depth=2,  # Traverse up to 2 levels deep
+    top_k=10  # Return top 10 relevant memories
+)
+```
+
+### Salience Scoring
+
+Each memory has a salience score (0.0-1.0) that represents its importance:
+
+```yaml
+---
+title: "Critical Architecture Decision"
+salience: 0.9
+memory_type: semantic
+---
+
+We decided to use PostgreSQL for better ACID guarantees...
+```
+
+## 🏗️ Project Structure
+
+```
+MemoGraph/
+├── memograph/          # Main package
+│   ├── core/           # Core functionality
+│   │   ├── kernel.py   # Memory kernel
+│   │   ├── graph.py    # Graph implementation
+│   │   ├── retriever.py # Hybrid retrieval
+│   │   ├── indexer.py  # File indexing
+│   │   └── parser.py   # Markdown parsing
+│   ├── adapters/       # LLM and embedding adapters
+│   │   ├── embeddings/ # Embedding providers
+│   │   ├── frameworks/ # Framework integrations
+│   │   └── llm/        # LLM providers
+│   ├── storage/        # Storage and caching
+│   └── cli.py          # CLI implementation
+├── tests/              # Test suite
+└── examples/           # Example usage
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Indhar01/MemoGraph.git
+   cd MemoGraph
+   ```
+
+2. Install in development mode:
+   ```bash
+   pip install -e ".[all,dev]"
+   ```
+
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+4. Run tests:
+   ```bash
+   pytest
+   ```
+
+## 📚 Documentation
+
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+- **[Security Policy](SECURITY.md)** - Security reporting and best practices
+- **[Changelog](CHANGELOG.md)** - Version history and changes
+
+## 🔒 Security
+
+See our [Security Policy](SECURITY.md) for reporting vulnerabilities.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🌟 Acknowledgments
+
+Inspired by the need for better memory management in LLM applications. Built with:
+
+- Graph-based knowledge representation
+- Hybrid retrieval strategies
+- Cognitive science principles
+
+## 📬 Contact & Support
+
+- **Issues**: [GitHub Issues](https://github.com/Indhar01/MemoGraph/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Indhar01/MemoGraph/discussions)
+
+## 🚦 Status
+
+This project is in active development. While the core functionality is stable, the API may change in minor versions until we reach v1.0.0.
+
+---
+
+Made with ❤️ for better LLM memory management

memograph-0.0.2.dist-info/RECORD

@@ -0,0 +1,19 @@
+memograph/__init__.py,sha256=sxGD_kLAm9u30e4JK1nSnPtTl3U7odvMWyv9ToYS5Uk,137
+memograph/cli.py,sha256=W3y5cdkVVSB1tkVqcWiAKjhLflCwDVK0J-64963Cuas,7210
+memograph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+memograph/core/__init__.py,sha256=4pp2UsBR8ZNO6pOWcGQFtc-oESYULW_qAV3NfXksl-c,148
+memograph/core/assistant.py,sha256=yU4xN4AjQPs6XJbH6ANPtsOkktDOc0b54D6mui-O05U,3671
+memograph/core/compressor.py,sha256=4NwdUgrj568rhd_SH1cVbGtv9WPHGh-yp2wj_LJdZsM,869
+memograph/core/enums.py,sha256=npxTlajgEyqH__SBprD7kskKRMd5XfBqsm4mfqPMezY,148
+memograph/core/graph.py,sha256=HFJhBgC3VD4tWvOPZYx9DEdVvlAhTBZkSAHNEX_EqcM,2782
+memograph/core/indexer.py,sha256=PkQR7WLb88ZsWAjMcAFdfFnBmCD1YtmV9adYXbgg2pw,6922
+memograph/core/kernel.py,sha256=3HR097ShMyViq-tuU22XicaTLcTYXWhNy4SF2b18FZI,4073
+memograph/core/node.py,sha256=uBnaqdtPsC-4zSH3cnJrQcq5gw5pLduoBFNEeE14ObA,1176
+memograph/core/parser.py,sha256=GShK6G-iSs7BxT71GQizOimjCTHVws3Qpi3lRstrDe4,1807
+memograph/core/retriever.py,sha256=oFU2vAkS-lYTsROLzuvgvuH9K89cgRfLtCOaezjFl1g,2823
+memograph-0.0.2.dist-info/licenses/LICENSE,sha256=QJn2W-w0yb-h3SNSWppUpFO4dS7vybnvYVySDbsydas,1096
+memograph-0.0.2.dist-info/METADATA,sha256=wt1xXOFPXWxMU7TMi6VYOMmnnP9_KXs36DPZ_q80PRg,10165
+memograph-0.0.2.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+memograph-0.0.2.dist-info/entry_points.txt,sha256=nCq_dnXTqGXjwi3AKq8NUC_XGWUUYSrgyIsrN1qvEXw,49
+memograph-0.0.2.dist-info/top_level.txt,sha256=rh1wBTM4dvMzgsJONWEliTDNi0AnMkeXNaiA4HS2UX4,10
+memograph-0.0.2.dist-info/RECORD,,

memograph-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memograph-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memograph = memograph.cli:main

memograph-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mnemo Contributors
+
+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.

memograph-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+memograph