seren-memory 1.9.1__tar.gz

seren_memory-1.9.1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: seren-memory
+Version: 1.9.1
+Summary: Three-tier LLM memory with consolidation. The Halls of Memory.
+Author: Chad Roesler
+License: GPL-3.0-or-later
+Keywords: llm,memory,vector-db,chromadb,consolidation,seren
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: chromadb>=0.5.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx2>=2.3; extra == "dev"

seren_memory-1.9.1/SerenMemory.pyproj

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>b1e7c0de-5e12-4a7b-9f3a-5e7e7a5e7e7a</ProjectGuid>
+    <ProjectHome>.</ProjectHome>
+    <!-- Run python -m seren_memory when you hit F5 -->
+    <StartupFile>seren_memory\__main__.py</StartupFile>
+    <SearchPath>.</SearchPath>
+    <WorkingDirectory>.</WorkingDirectory>
+    <OutputPath>.</OutputPath>
+    <Name>SerenMemory</Name>
+    <RootNamespace>seren_memory</RootNamespace>
+    <InterpreterId>Global|PythonCore|3.11</InterpreterId>
+    <IsWindowsApplication>False</IsWindowsApplication>
+    <Description>Three-tier LLM memory with consolidation. The Halls of Memory.</Description>
+    <TestFramework>Pytest</TestFramework>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="seren_memory\mcp\server.py" />
+    <Compile Include="seren_memory\mcp\tools.py" />
+    <Compile Include="seren_memory\mcp\__init__.py" />
+    <Compile Include="seren_memory\__init__.py" />
+    <Compile Include="seren_memory\__main__.py" />
+    <Compile Include="seren_memory\app.py" />
+    <Compile Include="seren_memory\config.py" />
+    <Compile Include="seren_memory\collections.py" />
+    <Compile Include="seren_memory\models\__init__.py" />
+    <Compile Include="seren_memory\models\schemas.py" />
+    <Compile Include="seren_memory\routes\__init__.py" />
+    <Compile Include="seren_memory\routes\short.py" />
+    <Compile Include="seren_memory\routes\near.py" />
+    <Compile Include="seren_memory\routes\long.py" />
+    <Compile Include="seren_memory\routes\search.py" />
+    <Compile Include="seren_memory\consolidator\__init__.py" />
+    <Compile Include="seren_memory\consolidator\service.py" />
+    <Compile Include="tests\conftest.py" />
+    <Compile Include="tests\test_auth.py" />
+    <Compile Include="tests\test_brief.py" />
+    <Compile Include="tests\test_drafts.py" />
+    <Compile Include="tests\test_mcp_endpoint.py" />
+    <Compile Include="tests\test_mcp_fallback.py" />
+    <Compile Include="tests\test_mcp_mount.py" />
+    <Compile Include="tests\test_mcp_tools.py" />
+    <Compile Include="tests\test_near_listing.py" />
+    <Compile Include="tests\test_search.py" />
+    <Compile Include="tests\test_smoke.py" />
+    <Compile Include="tests\test_validation.py" />
+    <Compile Include="tests\__init__.py" />
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="seren_memory\" />
+    <Folder Include="seren_memory\mcp\" />
+    <Folder Include="seren_memory\mcp\__pycache__\" />
+    <Folder Include="seren_memory\models\" />
+    <Folder Include="seren_memory\routes\" />
+    <Folder Include="seren_memory\consolidator\" />
+    <Folder Include="seren_memory\viewer\" />
+    <Folder Include="tests\" />
+    <Folder Include="tests\__pycache__\" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="pyproject.toml" />
+    <Content Include="seren-memory.yaml.sample" />
+    <Content Include="seren-memory.service.sample" />
+    <Content Include="seren_memory\mcp\__pycache__\server.cpython-311.pyc" />
+    <Content Include="seren_memory\mcp\__pycache__\tools.cpython-311.pyc" />
+    <Content Include="seren_memory\mcp\__pycache__\__init__.cpython-311.pyc" />
+    <Content Include="seren_memory\viewer\halls.html" />
+    <Content Include="tests\__pycache__\test_smoke.cpython-311-pytest-9.0.3.pyc" />
+    <Content Include="tests\__pycache__\__init__.cpython-311.pyc" />
+  </ItemGroup>
+  <ItemGroup>
+    <InterpreterReference Include="Global|PythonCore|3.11" />
+  </ItemGroup>
+  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Python Tools\Microsoft.PythonTools.targets" />
+</Project>

seren_memory-1.9.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seren-memory"
+dynamic = ["version"]
+description = "Three-tier LLM memory with consolidation. The Halls of Memory."
+readme = "README.md"
+# Upper bound is the chromadb wall, not ours: SerenMemory itself is fine on
+# 3.13+, but chromadb's transitive deps don't build there yet (an lz4 wheel
+# build failure). Capping here turns a cryptic transitive build explosion into
+# a clean "needs a different Python" from pip. LIFT THE <3.13 the day chromadb
+# ships 3.13 support (bump the CI matrix to match in the same commit).
+requires-python = ">=3.10,<3.13"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "Chad Roesler" }]
+keywords = ["llm", "memory", "vector-db", "chromadb", "consolidation", "seren"]
+
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.9.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.27.0",
+    "chromadb>=0.5.0",
+]
+
+[project.optional-dependencies]
+mcp = [
+    # The Python MCP SDK from Anthropic. FastMCP (the high-level server
+    # API) was merged into the main SDK; this single dep gives us both.
+    # Pin loosely - the SDK is moving fast; our server.py is written to
+    # tolerate the streamable_http→sse transport-name drift across recent
+    # versions.
+    "mcp>=1.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    # starlette >= 0.43 emits StarletteDeprecationWarning when fastapi.testclient
+    # falls back to httpx; installing httpx2 silences it and future-proofs the
+    # test stack against the upcoming hard cutover.
+    "httpx2>=2.3",
+]
+
+[project.scripts]
+seren-memory = "seren_memory.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seren_memory*"]
+
+# Ship the viewer HTML inside the wheel. Without this, pip strips non-.py
+# files and GET /viewer 404s on an installed copy (works in dev checkout,
+# silently breaks once installed - the classic package-data gotcha).
+[tool.setuptools.package-data]
+seren_memory = ["viewer/*.html"]
+
+[tool.setuptools_scm]
+# .git is one level above pyproject.toml (repo root, not the SerenMemory subdir)
+root = ".."
+version_scheme = "release-branch-semver"
+# Write the tag-derived version into the package (shipped in the wheel, read
+# by __init__ / importlib.metadata). Replaces the old sed-on-__init__ hack -
+# version now flows from the git tag with no manual step. _version.py is
+# gitignored; it's a build artifact, never committed.
+version_file = "seren_memory/_version.py"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

seren_memory-1.9.1/seren-memory.service.sample

@@ -0,0 +1,37 @@
+# SerenMemory systemd unit (sample)
+#
+# Install:
+#   1. Edit __TARGET_USER__ and paths below
+#   2. sudo cp seren-memory.service /etc/systemd/system/
+#   3. sudo systemctl daemon-reload
+#   4. sudo systemctl enable --now seren-memory
+#
+# Logs:  journalctl -u seren-memory -f
+
+[Unit]
+Description=SerenMemory - three-tier LLM memory with consolidation
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=__TARGET_USER__
+WorkingDirectory=/home/__TARGET_USER__/seren-memory
+
+# Use the venv's python. Adjust the venv path to wherever you installed.
+ExecStart=/home/__TARGET_USER__/seren-venvs/memory/bin/python -m seren_memory --config /home/__TARGET_USER__/seren-memory/seren-memory.yaml
+
+# Config can also come from env - uncomment + set as needed:
+# Environment=SEREN_MEMORY_PORT=7420
+# Environment=SEREN_MEMORY_MODEL_URL=http://localhost:8090/v1
+# Environment=SEREN_MEMORY_BEARER_TOKEN=
+
+Restart=on-failure
+RestartSec=5
+
+# The consolidation loop and chroma keep some state in memory; give it
+# room but cap it so a runaway can't OOM the box.
+MemoryMax=2G
+
+[Install]
+WantedBy=multi-user.target

seren_memory-1.9.1/seren-memory.yaml.sample

@@ -0,0 +1,89 @@
+# ═══════════════════════════════════════════════════════════════════════
+#  seren-memory.yaml - config for SerenMemory
+# ═══════════════════════════════════════════════════════════════════════
+#
+#  Copy to seren-memory.yaml, edit, and run:
+#     python -m seren_memory --config seren-memory.yaml
+#
+#  Or just run with no config at all - the defaults below are baked in, so
+#  `python -m seren_memory` works zero-config for a local dev spin.
+#
+#  Env vars override file values (handy for Docker/systemd):
+#     SEREN_MEMORY_PORT, SEREN_MEMORY_HOST, SEREN_MEMORY_BEARER_TOKEN,
+#     SEREN_MEMORY_PERSIST_DIR, SEREN_MEMORY_MODEL_URL,
+#     SEREN_MEMORY_MODEL_NAME, SEREN_MEMORY_CONSOLIDATOR_ENABLED
+#
+# ═══════════════════════════════════════════════════════════════════════
+
+server:
+  host: 0.0.0.0
+  port: 7420
+  # Leave empty for no auth (trusted LAN / dev). Set a token to require
+  #   Authorization: Bearer <token>
+  # on every endpoint except / and /health.
+  bearer_token: ""
+
+storage:
+  # Where chroma persists. ~ is expanded. Created if missing.
+  persist_dir: ~/.seren-memory/chroma
+  # Collection names - rarely need changing.
+  short_collection: seren_short
+  near_collection: seren_near
+  long_collection: seren_long
+  brief_collection: seren_briefs
+  # Embedding model. Leave null for chroma's default (all-MiniLM-L6-v2,
+  # ~80MB, CPU-friendly, downloaded on first use).
+  embedding_model: null
+
+lifetimes:
+  # ShortTerm entries older than this become eligible to age out during
+  # consolidation (unless promoted or pinned). 8 days = a week plus drift.
+  # 691200 = 8 * 24 * 3600.
+  short_term_seconds: 691200
+  # NearTerm intents with no explicit expiry get REVIEWED (not auto-deleted)
+  # after this long unfulfilled. 30 days.
+  near_term_review_seconds: 2592000
+
+consolidator:
+  enabled: true
+
+  # "thread" = runs as a background loop inside this process (simple).
+  # "external" = you drive it by POSTing /consolidate/run on a schedule
+  #              (e.g. a separate systemd timer or Seren's scheduler).
+  mode: thread
+
+  # How often the consolidation window opens. ~20 hours, NOT 24, on
+  # purpose: the window drifts through the day over a week so it never
+  # aligns to a 'day boundary' that doesn't exist for the system. This
+  # number is load-bearing - resist the urge to 'fix' it to 24h.
+  # 72000 = 20 * 3600.
+  interval_seconds: 72000
+
+  # OpenAI-compatible inference endpoint for the consolidation model.
+  # The consolidator does classification + light summarization, so a
+  # 2B-4B model is plenty. Point this at Seren's llama-server, ollama,
+  # a remote API - anything that speaks /v1/chat/completions.
+  model_url: http://localhost:8090/v1
+  model_name: default
+  model_timeout_seconds: 120
+
+  # Never process more than this many short-term entries per window
+  # (prevents a runaway run hammering the model). Rest wait for next window.
+  max_entries_per_run: 500
+
+  # A topic cluster needs at least this many short-term entries to be
+  # promoted to long-term - unless a brief promote-hint or a pin overrides.
+  # This is the main "how eager is consolidation" knob.
+  promote_min_evidence: 3
+
+  # Before deleting aged-out short-term entries, copy them to a 'pruned'
+  # collection for this many days as insurance. 0 = no safety net.
+  # Recommended > 0 until you trust the heuristic.
+  pruned_safety_days: 14
+
+  # How many times the consolidator will re-synthesize a cluster after the
+  # main model rejects a draft with a critique. On the Nth rejection the
+  # chain flips to 'requires_selection' - the model must then compare all
+  # attempts via GET /drafts/{id}/chain and commit the best via POST
+  # /drafts/{id}/select.
+  max_redraft_attempts: 3

seren_memory-1.9.1/seren_memory/__init__.py

@@ -0,0 +1,25 @@
+"""
+SerenMemory - three-tier LLM memory with consolidation.
+
+The Halls of Memory: ShortTerm (working), NearTerm (open loops), LongTerm
+(consolidated). A small "consolidator" model does the dream-work of
+promoting what matters and letting the rest go.
+
+Standalone. Bring your own LLM (any OpenAI-compatible endpoint). Configure
+a couple of values and you've got a memory system that matters.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+# Version flows from the git tag via setuptools-scm (written to _version.py
+# at build time and recorded in the installed package's metadata). No manual
+# bump, no sed step. The fallback only fires in a bare source checkout that
+# was never installed; do `pip install -e .` to resolve it.
+try:
+    __version__: str = _pkg_version("seren-memory")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"
+
+from .app import create_app  # noqa: F401,E402
+from .config import load_config, MemoryConfig  # noqa: F401,E402

seren_memory-1.9.1/seren_memory/__main__.py

@@ -0,0 +1,42 @@
+"""
+Entry point: python -m seren_memory [--config path]
+
+Boots the FastAPI app with uvicorn using the resolved config.
+"""
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from .app import create_app
+from .config import load_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="seren_memory",
+        description="SerenMemory - three-tier LLM memory with consolidation.")
+    parser.add_argument(
+        "--config", "-c", default=None,
+        help="Path to seren-memory.yaml (default: ./seren-memory.yaml or "
+             "$SEREN_MEMORY_CONFIG, falling back to built-in defaults).")
+    args = parser.parse_args()
+
+    cfg = load_config(args.config)
+    app = create_app(cfg)
+
+    print(f"[seren-memory] listening on {cfg.server.host}:{cfg.server.port}")
+    print(f"[seren-memory] auth: "
+          f"{'enabled' if cfg.server.bearer_token else 'DISABLED (no token)'}")
+
+    uvicorn.run(
+        app,
+        host=cfg.server.host,
+        port=cfg.server.port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

seren_memory-1.9.1/seren_memory/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.9.1'
+__version_tuple__ = version_tuple = (1, 9, 1)
+
+__commit_id__ = commit_id = 'g3e9f2859e'