neurostack 0.1.0__py3-none-any.whl

neurostack/__init__.py

@@ -0,0 +1,3 @@
+"""NeuroStack — AI-provider-agnostic, neuroscience-grounded knowledge management."""
+
+__version__ = "0.1.0"

neurostack/__main__.py

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

neurostack/brief.py

@@ -0,0 +1,159 @@
+"""Session brief generator: vault DB + external memory sources + git log."""
+
+import os
+import sqlite3
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+from .config import get_config
+from .schema import DB_PATH, get_db
+
+# Optional external memory DB (e.g. engram) -- configurable via env var
+EXTERNAL_MEMORY_DB = Path(os.environ.get(
+    "NEUROSTACK_MEMORY_DB",
+    str(Path.home() / ".engram" / "engram.db"),
+))
+
+
+def get_recent_vault_changes(conn: sqlite3.Connection, limit: int = 10) -> list[dict]:
+    """Get recently modified notes with summaries."""
+    rows = conn.execute(
+        """
+        SELECT n.path, n.title, s.summary_text, n.updated_at
+        FROM notes n
+        LEFT JOIN summaries s ON s.note_path = n.path
+        ORDER BY n.updated_at DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_git_recent(vault_root: Path, limit: int = 5) -> list[str]:
+    """Get recent git commits from the vault."""
+    try:
+        result = subprocess.run(
+            ["git", "log", f"--max-count={limit}", "--oneline", "--no-decorate"],
+            cwd=vault_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return [l.strip() for l in result.stdout.strip().split("\n") if l.strip()]
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return []
+
+
+def get_external_memories(limit: int = 5) -> list[dict]:
+    """Get recent observations from external memory DB (e.g. engram)."""
+    if not EXTERNAL_MEMORY_DB.exists():
+        return []
+    try:
+        econn = sqlite3.connect(str(EXTERNAL_MEMORY_DB))
+        econn.row_factory = sqlite3.Row
+        rows = econn.execute(
+            """
+            SELECT topic_key, content, timestamp
+            FROM memories
+            ORDER BY timestamp DESC
+            LIMIT ?
+            """,
+            (limit,),
+        ).fetchall()
+        result = [dict(r) for r in rows]
+        econn.close()
+        return result
+    except Exception:
+        return []
+
+
+def get_top_notes(conn: sqlite3.Connection, limit: int = 5) -> list[dict]:
+    """Get top notes by PageRank."""
+    rows = conn.execute(
+        """
+        SELECT gs.note_path, n.title, gs.pagerank, gs.in_degree
+        FROM graph_stats gs
+        JOIN notes n ON n.path = gs.note_path
+        ORDER BY gs.pagerank DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def generate_brief(vault_root: Path = None) -> str:
+    """Generate a compact session brief."""
+    if vault_root is None:
+        vault_root = get_config().vault_root
+    conn = get_db(DB_PATH)
+
+    now = datetime.now()
+    hour = now.hour
+    if 5 <= hour < 12:
+        time_ctx = "morning"
+    elif 12 <= hour < 17:
+        time_ctx = "afternoon"
+    elif 17 <= hour < 21:
+        time_ctx = "evening"
+    else:
+        time_ctx = "night"
+
+    parts = [f"## Session Brief ({now.strftime('%Y-%m-%d %H:%M')}, {time_ctx})\n"]
+
+    # Vault stats
+    note_count = conn.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]
+    chunk_count = conn.execute("SELECT COUNT(*) as c FROM chunks").fetchone()["c"]
+    summary_count = conn.execute("SELECT COUNT(*) as c FROM summaries").fetchone()["c"]
+    embedded_count = conn.execute(
+        "SELECT COUNT(*) as c FROM chunks WHERE embedding IS NOT NULL"
+    ).fetchone()["c"]
+    parts.append(
+        f"**Vault:** {note_count} notes, {chunk_count} chunks, "
+        f"{embedded_count} embedded, {summary_count} summarized\n"
+    )
+
+    # Recent changes
+    changes = get_recent_vault_changes(conn, limit=5)
+    if changes:
+        parts.append("**Recent changes:**")
+        for c in changes:
+            summary = c.get("summary_text", "") or ""
+            if summary:
+                parts.append(f"- `{c['path']}`: {summary[:100]}")
+            else:
+                parts.append(f"- `{c['path']}` ({c['title']})")
+        parts.append("")
+
+    # Git history
+    commits = get_git_recent(vault_root, limit=3)
+    if commits:
+        parts.append("**Recent commits:**")
+        for c in commits:
+            parts.append(f"- {c}")
+        parts.append("")
+
+    # External memory observations
+    memories = get_external_memories(limit=3)
+    if memories:
+        parts.append("**Recent memories:**")
+        for e in memories:
+            content = e.get("content", "")[:100]
+            parts.append(f"- [{e.get('topic_key', '?')}] {content}")
+        parts.append("")
+
+    # Top connected notes
+    top = get_top_notes(conn, limit=5)
+    if top:
+        parts.append("**Most connected notes:**")
+        for t in top:
+            parts.append(
+                f"- `{t['note_path']}` (PR: {t['pagerank']:.4f}, {t['in_degree']} inlinks)"
+            )
+        parts.append("")
+
+    return "\n".join(parts)

neurostack/chunker.py

@@ -0,0 +1,119 @@
+"""Markdown heading-based chunker with frontmatter parser."""
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class Chunk:
+    heading_path: str  # e.g. "## Architecture > ### Networking"
+    content: str
+    position: int
+
+
+@dataclass
+class ParsedNote:
+    path: str
+    title: str
+    frontmatter: dict = field(default_factory=dict)
+    content_hash: str = ""
+    chunks: list[Chunk] = field(default_factory=list)
+    wiki_links: list[str] = field(default_factory=list)
+
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
+WIKI_LINK_RE = re.compile(r"\[\[([^\]|#]+?)(?:\|[^\]]+?)?\]\]")
+
+# Target max chunk size in characters (~500 tokens ≈ ~2000 chars)
+MAX_CHUNK_CHARS = 2000
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Extract YAML frontmatter and return (metadata, remaining_content)."""
+    match = FRONTMATTER_RE.match(text)
+    if not match:
+        return {}, text
+    try:
+        fm = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        fm = {}
+    return fm, text[match.end() :]
+
+
+def chunk_by_headings(content: str) -> list[Chunk]:
+    """Split markdown content into chunks by ## headings."""
+    chunks = []
+    heading_stack: list[tuple[int, str]] = []
+    current_lines: list[str] = []
+    position = 0
+
+    def flush():
+        nonlocal position
+        text = "\n".join(current_lines).strip()
+        if text:
+            path = " > ".join(f"{'#' * lvl} {name}" for lvl, name in heading_stack) if heading_stack else "(intro)"
+            # Split oversized chunks
+            if len(text) > MAX_CHUNK_CHARS:
+                for i in range(0, len(text), MAX_CHUNK_CHARS):
+                    sub = text[i : i + MAX_CHUNK_CHARS].strip()
+                    if sub:
+                        chunks.append(Chunk(heading_path=path, content=sub, position=position))
+                        position += 1
+            else:
+                chunks.append(Chunk(heading_path=path, content=text, position=position))
+                position += 1
+
+    for line in content.split("\n"):
+        m = HEADING_RE.match(line)
+        if m:
+            level = len(m.group(1))
+            name = m.group(2).strip()
+            # Flush current content
+            flush()
+            current_lines = [line]
+            # Update heading stack
+            while heading_stack and heading_stack[-1][0] >= level:
+                heading_stack.pop()
+            heading_stack.append((level, name))
+        else:
+            current_lines.append(line)
+
+    flush()
+    return chunks
+
+
+def extract_wiki_links(content: str) -> list[str]:
+    """Extract wiki-link targets from markdown content."""
+    return list(set(WIKI_LINK_RE.findall(content)))
+
+
+def parse_note(path: Path, vault_root: Path) -> ParsedNote:
+    """Parse a markdown note into structured data."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    content_hash = hashlib.sha256(text.encode()).hexdigest()[:16]
+
+    frontmatter, body = parse_frontmatter(text)
+
+    # Title: from frontmatter, first H1, or filename
+    title = frontmatter.get("title", "")
+    if not title:
+        h1 = re.search(r"^#\s+(.+)$", body, re.MULTILINE)
+        title = h1.group(1) if h1 else path.stem
+
+    rel_path = str(path.relative_to(vault_root))
+    chunks = chunk_by_headings(body)
+    wiki_links = extract_wiki_links(body)
+
+    return ParsedNote(
+        path=rel_path,
+        title=title,
+        frontmatter=frontmatter,
+        content_hash=content_hash,
+        chunks=chunks,
+        wiki_links=wiki_links,
+    )