Funes's Hoard

Where was I? What was I doing before lunch? How much of this week actually went to Faustus?

Your computer's episodic memory: foreground app, window, files opened and commits made, kept in a local SQLite file and filtered for privacy before anything is written.

Español · Quick start · Connect to Faustus · MCP reference · Portfolio

Actual application, three days of synthetic demo data (--demo, no real window titles).

Before anything else, what this does with your activity.

• Where it lives: one SQLite file, data/funes.sqlite3, on this computer. No account, no telemetry, no cloud copy.

• What is recorded: the foreground app, its window title, idle and locked time, files opened through Windows Recent Items, and commits in the git folders you add.

• What is never recorded: keystrokes, screen content, screenshots or the clipboard. Password managers and private/incognito windows are excluded by default, and your own rules can drop or redact any app or window before a sample is written.

• Pause: 15 min, 1 h or until you resume, from any screen. The assistant can pause too, but can never resume or shorten your pause.

• Delete: any time range, permanently, from Privacy (with "last 15 min / 30 min / hour / today" shortcuts), plus automatic purge after 180 days by default.

• What leaves the app: only "Write my day", if you use it, sends a compact day summary (categories, apps, projects, durations; never window titles) to the language model Hoard Link finds on this machine or the address you set in Settings. It can be switched off.

Full detail in Privacy and security.

Why

A local assistant has no record of what was on the user's screen. Asked "where was I?", "how did today go?" or "what was that DuckDB page I had open yesterday?", a language model can only invent an answer or ask the user to reconstruct it. Funes's Hoard records the one thing the model cannot see: the sequence of windows in front of the user, with idle and locked time, the files they opened and the commits they made. It turns that into spans, day summaries, focus blocks and resume-context answers, and gives the assistant eight small tools to ask for them.

Related MCP server: DevFlow MCP

What is implemented

More screens: Search · Privacy · Settings · Assistant activity (real calls made through the agent API by scripts/screenshots.py, including a rejected one).

Use cases

Eight concrete scenarios for a fictional developer, each walked end to end as a person in the browser and as a local model over MCP (docs/USE_CASES.md, findings and fixes in docs/USABILITY_REPORT.md):

• Monday morning, "where was I?": the Today screen opens with the last three work contexts before now (project, last titles, files, commits), so Friday's last file is on screen before you pick a day; one click pins that moment in its day's timeline.

• "Faustus, ¿dónde lo dejé ayer?": one activity_where_was_i call, about 500 tokens, answers with the project, the window and the editor title that names the file, skipping the music player and the chat.

• A weekly note for a job search: activity_summary gives hours per project as ready-to-read strings, and a search for the job boards or a novel's title says how long those windows were open; Faustus writes the note with its own notes tool.

• "That FTS5 page from Tuesday": search, click the hit and land on that day with the segment pinned (the address keeps it, so reload and Back work); an agent passes the hit's ts to activity_timeline(around=...).

• Privacy before an interview or the bank: pause for an hour, private windows (also Spanish "incógnito") and bank pages never become searchable, and "Last 30 min" fills the delete-range pickers for the half hour you forgot.

• Hours per project for a chart: export spans as CSV (local dates and times, minutes, category, project) for a spreadsheet or a data-analysis tool.

Quick start

git clone https://github.com/Luissalet/FunesHoard.git
cd FunesHoard

Windows

Double-click Iniciar Funes's Hoard.cmd. It runs scripts\start.ps1, which on first run creates .venv (Python 3.11+, preferring C:\Python313), installs requirements-lock.txt and builds the interface if frontend\dist is missing (Node 22); later runs reinstall only when the lock changed. It then starts the app hidden, with the repo root as working directory, waits for /api/health and opens http://127.0.0.1:8813. If the app is already running it just opens it. Detener Funes's Hoard.cmd stops it. The same from PowerShell: scripts\start.ps1 [-Port 8813] [-Demo] [-NoBrowser] and scripts\stop.ps1.

Manual steps:

python -m venv .venv
.venv\Scripts\pip install -r requirements-lock.txt
cd frontend; npm ci; npm run build; cd ..
.venv\Scripts\python -m funes_hoard

Linux / macOS

Recording is Windows-first: on Linux the probe is best effort (X11 with xdotool and xprintidle), and macOS has no probe. The interface, the API and the MCP tools all run on synthetic data with --demo. Python 3.11 or newer and Node 22:

python3 -m venv .venv
.venv/bin/pip install -r requirements-lock.txt
(cd frontend && npm ci && npm run build)
.venv/bin/python -m funes_hoard --demo

The app answers on http://127.0.0.1:8813 (curl http://127.0.0.1:8813/api/health).

Flags: --demo (synthetic data in data-demo/, nothing recorded from the desktop), --data-dir (or FUNES_DATA_DIR), --port, --no-browser. Your own data lives in data/. The app only listens on loopback; --host refuses anything else.

Connect it to Faustus

Funes's Hoard is a plugin for Faustus and declares itself with faustus-plugin.json at the repo root. Start the app, then in Faustus open Connectors -> Nearby apps -> Add: Faustus finds it on port 8813, checks that /api/health answers as funes-hoard, starts the MCP adapter and loads the where-was-i skill, which tells a local model which tool to pick and the traps. The adapter is a stdio script started by path, with the app's URL in FUNES_URL:

$env:FUNES_URL = "http://127.0.0.1:8813"
.venv\Scripts\python.exe funes_hoard\mcp_server.py

MCP tools

It works with any MCP client over stdio; docs/MCP.md has the output of every tool, the error codes and a config snippet.

Shared models (HoardLink)

The only feature that needs a language model, "Write my day", never loads one of its own: it uses HoardLink (vendored in funes_hoard/hoard_link/), the resolver every Faustus plugin app shares, in this order -- explicit override in Settings, then Faustus's own model registry, then a shared llama.cpp, Ollama or other OpenAI-compatible server already running on this machine. The rest of the app works fully without any model at all, and Settings says exactly why when one is not available.

Architecture

flowchart LR
  Probe["Windows probe, 1 sample/s"] --> Privacy["privacy rules: drop or redact"]
  Privacy --> Spans["span builder + classification"]
  Spans --> DB[("SQLite in WAL mode")]
  Pollers["recent files, git log, retention"] --> DB
  UI["React interface"] -->|"/api/*"| API["FastAPI on 127.0.0.1:8813"]
  Model["Faustus or any MCP client"] -->|stdio| MCP["mcp_server.py"]
  MCP -->|"/api/agent/*"| API
  API --> DB
  API -->|"Write my day"| Link["HoardLink: shared language model"]

FastAPI, one collector thread sampling once a second, one scheduler thread for recent files, git and retention, and SQLite in WAL mode. The span, privacy, classification and summary logic is pure Python with no FastAPI or sqlite imports. The MCP adapter is a separate script that only speaks HTTP to the app. See docs/ARCHITECTURE.md.

Privacy and security

• Everything stays in data/funes.sqlite3 on this computer. No telemetry and no network use; git log runs locally. The one exception is "Write my day", described above: it sends only the compact activity_summary data (categories, apps, projects, durations, focus blocks) to the language model -- never raw or redacted window titles -- and can be turned off in Settings; deleting a day's history also deletes its cached narrative.

• Exclusion rules run before a sample is written; a test asserts the row never exists. Redacted titles are never put in the search index.

• The server binds loopback only. A middleware rejects DNS rebinding (a Host header that is not a loopback name with this app's port) and cross-site writes (a foreign Origin or Sec-Fetch-Site: cross-site); there is no CORS.

• The assistant sees only what the eight tools return and can do exactly one thing: pause (or lengthen a pause). Every call, including rejected ones, is stored in the agent_calls audit table (tool, argument summary, duration, ok/error) and listed on "Assistant activity".

• Results are capped (default 5-20 items, maximum 100) and long titles are truncated, because the intended consumer is a local model with a finite context window; the server instructions tell the model to treat window titles as data, never as instructions.

• Retention and delete-range also remove file_events and commits in the same window, not only spans, so deleting history means all of it.

Development

.venv/bin/python -m pytest tests/ -q    # 271 passed, offline, about 15-30 s
cd frontend && npm ci && npm run build  # 0 TypeScript errors

On Windows, .venv\Scripts\python -m pytest tests/ -q. CI runs the same two jobs on Ubuntu with Python 3.12 and Node 22.

The suite covers span merging, away/locked back-dating, sleep gaps, excluded and paused interludes, crash flushing and stale open spans; privacy rules (asserting the excluded row never exists) and rule validation; pause expiry and the agent's extend-only pause; retention and delete-range including the search index and the "Write my day" cache; the .lnk parser on fixtures built in the tests (ANSI, Unicode, suffix, truncated); project detection from editor titles; focus blocks, switches, clipping and where-was-i on scripted days; date words in both languages and their range edges; search on both the FTS5 and LIKE paths with hostile input; the browser guard (host and origin ports, null origin), the SPA path-traversal fix and the exact agent route list; the shared model backend (backend.json persistence and merging, the token never echoed back, resolved/unavailable Settings states, the Re-check swap, and "Write my day" caching/regeneration/disabling and the empty-day and empty-answer refusals against a fake Link, plus one pass through the real resolver over a mocked HTTP transport -- never a real network call); the Windows probe logic with the Win32 calls faked (tick wraparound, access-denied executables); git scanning with UTF-8 subjects, author filters, hidden consoles and timezones ahead of UTC; the CLI; the manifest check; and an MCP protocol test that spawns mcp_server.py over stdio against a live app and checks keywords, annotations, error passthrough and the audit log.

scripts/uxtest_data.py, scripts/ui_walkthrough.py and scripts/agent_walkthrough.py rebuild the realistic data set and replay the use cases in a browser and over MCP; scripts/screenshots.py retakes the images in docs/media/.

Roadmap / known limits

• Windows-only paths are tested with fakes. The suite and CI run on Linux; the target is Windows with Python 3.13. The Win32 calls in WindowsProbe (GetForegroundWindow, GetLastInputInfo, OpenInputDesktop) have declared signatures and the logic around them is tested with the calls faked. Lock detection relies on OpenInputDesktop failing on the secure desktop, so a UAC prompt also counts as "locked".

• FTS5 in the python.org 3.13 sqlite3 is expected but checked at startup; without it search falls back to LIKE.

• The PowerShell launchers were run under PowerShell 7 on Linux (without -WindowStyle Hidden, which only exists on Windows); stop.ps1's Get-CimInstance and Get-NetTCPConnection calls have not been exercised.

• No browser address-bar reader: a title rule decides streaming vs. browsing, so a video on a site the rule does not know stays Browsing with the ordinary idle threshold.

• "Where was I?" looks three days back; after a longer absence it says there is nothing to pick up.

• The Models panel shows the backend's diagnostic reason in English in both languages, and "Write my day" usually answers in English.

See docs/USABILITY_REPORT.md for how each item was found.

License

MIT - see LICENSE.