DEV Community: SAIF MODAN

HackProof: catch missing pieces in your hackathon write-up

SAIF MODAN — Wed, 11 Nov 2026 19:05:32 +0000

This is a submission for the MLH × DEV Writing Challenge.

What I Built

A hackathon project can be almost finished and still be difficult to share. The demo link may be missing, a template placeholder may still be in the draft, or a paragraph may describe a claim without pointing to anything that supports it. I built HackProof, a small offline command-line tool to catch some of those gaps before publishing.

Give it a DEV-style Markdown post and HackProof checks for a title, the mlhacks tag, the four sections in the official challenge template, a demo URL, and obvious draft markers such as an empty title or bracketed fill-in instructions. It can print a text summary, produce JSON for automation, or create a standalone HTML report. It does not need an API key, an account, a network connection, or extra Python packages.

I also wanted to explore a useful boundary for evidence. HackProof can create an optional SHA-256 receipt for a local file and later tell you if the bytes changed. The receipt keeps a claim label, a relative path, and a digest; the audit rejects paths outside the receipt directory. That can help preserve a demo log or test result alongside a draft. A matching hash confirms that file is unchanged. It cannot establish that the file proves the claim, that the underlying claim is true, or that the project meets competition rules. A person still has to review the evidence.

I used the November 6–12 MLH Global Hack Week: Builders Week window to make this project. The event is online, and my MLH account showed me as checked in. I used the writing challenge template itself as a concrete test case: could I turn its repeated, easy-to-miss requirements into a quick local review? The public overview describes projects built at MLH events, but it also says additional participation terms are forthcoming. HackProof does not decide eligibility; the event organizer remains the source for that.

The working code and setup instructions are on GitHub. It is a standard-library Python program, not an official MLH or DEV product. I used AI coding assistance to implement and validate it, and the repository includes the test output and a sample report.

Demo

The quickest way to see the checks is to run the deliberately incomplete example and then the complete one:

python hackproof.py audit examples/incomplete.md
python hackproof.py audit examples/complete.md

The first command reports the unfinished title, missing project story, placeholder demo URL, and incomplete prose. The second passes the configured checks. To create a browser-readable report, run:

python hackproof.py audit examples/complete.md --format html --output report.html

There is a checked-in HTML report, a JSON report, and a test transcript. GitHub shows the HTML source in its file viewer; running the command locally opens it as a proper page.

Eight automated tests cover the end-to-end audit, evidence tampering, unsafe receipt paths, malformed evidence, examples hidden in code fences and comments, HTML escaping, output preservation, and missing input. GitHub Actions runs the suite on Python 3.10 and 3.13.

Partner Technologies

HackProof uses Python's standard library. It does not call an MLH partner service or require a partner API. I used AI coding assistance during development and documented that in the repository. The project is MIT licensed.

Hackathon Experience

Global Hack Week: Builders Week ran online from November 6 through November 12, 2026. My project grew from the practical problem of preparing a clear project story while a challenge window was still open. The interesting part was keeping the checks modest: a green result should mean only that the checks ran and passed, not that a tool can certify a real-world claim. That distinction shaped both the evidence receipt design and the report's limitations.

I worked on HackProof individually with AI coding assistance; I am not claiming teammates, partner prizes, workshop participation, or any event interaction beyond the account's checked-in status. You can try it from the repository and adapt the checks to your own submission checklist.

Building SwitchOps AI: Six Agents, One Workflow, and a Human in Control

SAIF MODAN — Fri, 06 Nov 2026 19:03:01 +0000

A customer asks for a proposal. Someone needs to find their history, research the requirements, write a draft, review it, send it, and remember to follow up.

That handoff between people, tools, and documents is where work often stalls.

I built SwitchOps AI for the Flip the Switch Hackathon to connect those steps in one workspace—with six specialist agents collaborating through Switch and a human controlling the send.

Explore the project on GitHub

From a customer request to a reviewed proposal

SwitchOps combines customer records, internal knowledge, proposals, approvals, tasks, and workflow tracking.

Its six agents have distinct responsibilities:

Agent	Responsibility
Operations Coordinator	Triage requests and coordinate the workflow
Customer Intelligence	Retrieve relevant customer context
Research Specialist	Research authorized internal sources
Communications Specialist	Draft and revise the proposal
Quality Reviewer	Check the draft against available evidence
Scheduling Specialist	Create the internal follow-up

Google Gemini provides reasoning and structured outputs. The official Switch server carries addressed messages between agents, with Mattermost providing the collaboration space.

The application uses Next.js and FastAPI. PostgreSQL stores durable business state, Redis supports background jobs, MinIO stores uploaded knowledge files, and Mailpit captures sandbox emails.

Making collaboration observable

One of my main requirements was that specialist handoffs genuinely travel through Switch.

When an agent finishes its work, it posts an addressed handoff. The receiving agent starts when the expected event arrives through Switch. The application persists the receipt, workflow transition, and resulting output.

The main path is:

Customer request in Mattermost → Switch → Coordinator
Switch handoff → Customer Intelligence
Switch handoff → Research Specialist
Switch handoff → Communications Specialist
Switch handoff → Quality Reviewer
Exact-version human approval → Mailpit sandbox capture
Switch handoff → Scheduling Specialist
Switch handoff → Coordinator finalization

That makes it possible to inspect how a request moved between specialists instead of seeing only a final answer. PostgreSQL remains the business source of truth; Switch carries collaboration events.

The integration bugs that mattered

Connecting the real services exposed issues that deterministic tests had not revealed.

Real cursors needed bigger integers

The live Switch cursors and connection generations exceeded PostgreSQL’s 32-bit integer range. I migrated those fields to bigint so the application could persist the actual protocol values.

Registration needed to survive a partial failure

An agent could register successfully, then encounter a permission error during subsequent configuration. Its one-time credential needed to survive that second operation failing.

I changed the flow to save the identity and encrypted key before attempting follow-up configuration. Supported addressing policies were then configured through the official Gateway owner API.

Revisions needed durable context

A proposal sent back for changes had to retain its feedback across an interrupted connection and an explicit retry. Losing that context would mean repeating the original mistake.

These were useful reminders that reliable agent workflows depend on careful state management as much as prompting.

The first proposal taught me the most

For the live test, I used a fictional customer, Acme Solutions, and a deliberately limited internal knowledge source.

The request was to prepare a nonbinding discovery proposal covering intake, customer context, ownership, human review, and follow-up. Pricing, delivery dates, and ROI were unknown and had to remain open questions.

The first proposal included unsupported claims about automated provisioning. The AI quality reviewer did not catch them.

That was the most important finding of the run.

The integration review requested changes, and the communications agent produced version two without those claims. A fresh quality review followed.

It demonstrated why an AI reviewer should support human judgment rather than replace it.

Approving an exact version

Approval in SwitchOps is tied to a specific proposal version and outbound payload.

For the live demo, I explicitly approved proposal version two for the fictional recipient acme@example.test, using the local Mailpit sandbox.

The application then sent that approved content. Verification compared the captured email body with the reviewed proposal, normalizing only SMTP line endings.

Mailpit contained exactly one message.

That proves sandbox capture—not delivery to a real customer. The follow-up was internal; no external calendar invitation was sent.

What the live run verified

The completed Acme workflow recorded:

Six participating agents
10 real Gemini model calls
8 Switch handoffs
A revised and explicitly approved proposal
One captured sandbox email
One follow-up task and one internal calendar event
A completed workflow reflected in the dashboard

Research used authorized internal records and the uploaded knowledge source, not public-web browsing.

I also stopped the official Switch server and submitted a separate dependency test. The new request became visibly blocked, with zero model calls and zero handoffs. Existing completed records remained readable.

After restoring Switch, I resumed the verified connections through the authenticated application endpoint, preserving their identities and durable cursors. All six agents reconnected, and Mailpit still contained one message.

The final checks included 24 passing Python tests, a passing browser journey covering persisted records and mobile navigation, and a successful production build.

Read the detailed live verification report

What comes next

The local sandbox workflow works, but production use needs further work: narrower agent ownership permissions, real email-provider configuration, operational hardening, and continued evaluation of generated content.

My biggest takeaway from building with Switch is that an agent workflow needs visible boundaries: who sent a message, which source supported a claim, what version a person approved, and what actually happened afterward.

SwitchOps AI is my attempt to make those boundaries part of everyday business work.

Code, setup instructions, screenshots, and verification: github.com/saifmodan2006/switch_hackathon

This article was prepared with AI assistance from the project’s implementation and recorded verification results.

TiddlyWiki Cognee: a design proposal for searchable project notes

SAIF MODAN — Thu, 22 Oct 2026 06:36:22 +0000

Project status — October 22, 2026: This is a design proposal for Cognee issue #6222. Maintainer assignment is pending. The connector has not been implemented or tested, and there is no PR yet. This article explains the proposed scope and validation plan.

Project wikis hold more than documentation. They capture why a team chose an approach, which service owns a responsibility, and what happened during an incident. A useful memory integration should preserve those notes and their source links, while also forgetting content that the author deletes.

For Mergetober, the proposed contribution is a read-only connector between TiddlyWiki and Cognee. The initial target is TiddlyWiki’s official Node.js server, with selected text notes ingested as documents through Cognee’s existing document-source path.

A small project wiki as the example

The planned demonstration uses a dedicated local wiki with synthetic notes about service ownership, deployment decisions, and an incident. It should support questions such as: “Who owns billing?” and “Why did this project choose its deployment approach?”

The example will then change an ownership note, run another sync, and check the updated answer. Finally, it will delete a note and check that stale information is forgotten. These are planned checks, not results obtained so far.

Read the notes through the documented API

TiddlyWiki exposes a note-list endpoint and a single-note endpoint. The connector proposal uses the permitted default listing and applies title or tag selection locally.

Each document should retain the note title, selected tags, text, and a source permalink. The first version excludes system/configuration notes and binary attachments. It will preserve note text without executing wiki macros or following linked files.

A failed read must not become a deletion

The proposed sync is a complete snapshot of the selected notes. Cognee can use stable semantic content to avoid re-processing unchanged documents, while a successful snapshot provides the inventory needed to reconcile deleted or renamed notes.

That also creates a responsibility: an authentication failure, malformed response, or failed note fetch must abort the run. Treating a partial fetch as a complete inventory could remove content that still exists.

A note disappearing between listing and retrieval needs a bounded restart or an explicit failed run. Deleting the final note also needs a real integration test; a passing HTTP unit test alone would not establish that graph cleanup works.

Evidence to collect before the PR

Check	Current status
HTTP authentication, title encoding, tag parsing, and error handling	Planned
Real dlt pipeline and Cognee document ingestion	Planned
Live official TiddlyWiki server on loopback	Planned
Unchanged sync, edit, rename, scope change, and deletion	Planned
Final-note deletion and failed-run preservation	Planned
End-to-end search answers and source provenance	Planned

The completed walkthrough will include tested package versions, reproducible setup commands, the actual PR link, and observed results. Mocked tests and live service checks will be reported separately.

Scope and assistance

The proposal and assignment request includes the package layout and acceptance plan. Implementation is waiting for assignment and clarification of Mergetober’s AI-assistance expectations.

AI disclosure: This proposal and article were researched and drafted by Codex at my request. The post is labelled Fully Autonomous to reflect that authorship. Implementation details and test outcomes will be reported only after the corresponding work is completed.

Building AgentTrace: How I Made AI Agents Remember, Recover, and Resume with FalkorDB

SAIF MODAN — Sun, 18 Oct 2026 14:33:43 +0000

AI agents are getting better at planning, writing code, and using tools. But there is still a frustrating problem: what happens when an agent forgets what it has already done?

Imagine an AI agent working on a software project. It analyzes the source code, runs tests, encounters an error, and starts fixing it. Then its process crashes.

When the agent restarts, several questions appear:

Which tasks were completed?
Which actions failed?
What caused the failure?
Which dependencies are still blocked?
Is it safe to retry an interrupted operation?
How can another agent continue the work without starting from scratch?

A traditional conversation history or a simple task list isn't enough to answer all these questions reliably.

That is the problem behind AgentTrace, a graph-native execution-memory and coordination system built with FalkorDB for the WeMakeDevs × FalkorDB Graph Hacks 2026 hackathon.

GitHub repository: AgentTrace — Open Source

The Idea: Give Agents an Execution Memory

Instead of depending entirely on the LLM's context window, AgentTrace records execution state inside a persistent graph.

The graph stores tasks, dependencies, attempts, failures, recovery procedures, decisions, verification results, and checkpoints.

More importantly, these are not just historical logs.

The relationships actively determine what the agent can do next.

An agent can ask:

What steps are ready to execute?
What is preventing this task from running?
Which earlier failure is relevant?
What approved recovery procedure applies?
What work was already verified before the process stopped?

FalkorDB answers these questions through graph queries.

Why a Graph Database?

An agent workflow naturally contains relationships.

Consider a simple task sequence:

Inspect Application → Run Tests → Build Application → Inspect Artifact

The build must not execute if the tests have not passed.

When the tests fail, a recovery action might need to be inserted as a new dependency.

These connections are important. They should not exist only inside an LLM-generated plan.

In AgentTrace, a task points toward its prerequisites through a DEPENDS_ON relationship.

The execution graph includes twelve node labels:

Node	Responsibility
AgentRun	Overall execution goal
Step	Planned actions and dependencies
Attempt	Individual tool executions
Agent	Planner, executor, verifier, and recovery workers
Event	Execution history
Failure	Recorded errors
Procedure	Reusable recovery knowledge
Fact	Facts learned during execution
Artifact	Generated files and outputs
Decision	Actions and supporting evidence
Checkpoint	Persistent progress snapshots
Resource	Files and workspaces

This graph becomes the shared execution state for the entire system.

How AgentTrace Works

The architecture combines a React dashboard, a FastAPI backend, and FalkorDB.

There are four cooperating agent roles.

1. Planner

Creates a validated task plan with dependencies and expected outcomes.

2. Executor

Selects eligible tasks, claims them, runs registered tools, and records actual results.

3. Verifier

Independently checks whether a task achieved its expected result.

4. Recovery

Investigates failures, retrieves supporting graph evidence, and introduces approved corrective actions.

All four roles work against the same graph-backed memory manager.

The important distinction is that a worker cannot simply choose any pending task.

It must first consult the dependency graph.

Graph-driven scheduling

A simplified version of the readiness query looks like this:

MATCH (r:AgentRun {id:$run})-[:HAS_STEP]->(s:Step)
OPTIONAL MATCH (s)-[:DEPENDS_ON]->(d:Step)
WITH r, s, collect(d) AS deps
WHERE r.status = 'running'
  AND s.status IN ['pending', 'ready', 'retryable']
  AND s.retry_after_ms <= $now
  AND s.attempt_count < s.max_attempts
  AND all(
    d IN deps
    WHERE d.status = 'succeeded'
    AND d.verification_status = 'passed'
  )
RETURN s, deps
ORDER BY s.priority DESC
LIMIT 30

The production implementation adds lease and resource checks.

The actual claim repeats eligibility checks inside an atomic graph write, creates an execution attempt, and records ownership information.

This helps prevent two workers from claiming the same task.

FalkorDB is not merely storing the workflow. It helps enforce the workflow.

The Demo: An Agent Encounters a Real Failure

To demonstrate AgentTrace, the project includes a controlled Python calculator application.

The calculator contains a deliberately broken addition function.

def add(a, b):
    return a - b

The expected behavior is addition, but the function subtracts.

The executor runs real Python unit tests against this source.

The tests fail.

Rather than discarding that result, AgentTrace records the unsuccessful execution as an Attempt, together with its error evidence.

The recovery component investigates the failure and checks whether it matches a supported, approved correction.

In the demonstration, the failure is recognized as an addition defect.

AgentTrace introduces a new repair task that changes the function to:

def add(a, b):
    return a + b

But there is an important detail.

The failed test step now depends on the repair step.

The graph prevents the test from proceeding before the correction is applied and verified.

This is where graph-based execution memory becomes useful: recovery actually changes the workflow's dependency structure.

Verification matters

After the repair, the tests run again.

The verifier independently checks the result rather than trusting a tool's success message.

The graph retains both the original failure and the successful attempt.

The process also produces a checked build artifact.

The original failure is not erased just because the workflow eventually succeeds.

It remains part of the agent's execution memory.

Making Decisions Explainable

Another goal was to make agent actions traceable.

For example, why did the recovery component choose a particular repair?

AgentTrace stores Decision nodes linked to relevant evidence, including Failure and Procedure nodes.

A decision can therefore be investigated through the graph.

A simplified evidence query is:

MATCH (d:Decision {id:$id})
OPTIONAL MATCH (d)-[r:BASED_ON]->(e)
RETURN d, collect(e), collect(r)

The dashboard uses this information to show the relationships supporting a decision.

This is different from asking an LLM to invent an explanation after executing an action.

The evidence is associated with the decision when it is recorded.

AgentTrace also implements multi-hop dependency impact analysis.

For example:

MATCH p=(affected:Step)
  -[:DEPENDS_ON*1..30]->
  (failed:Step {id:$id})
RETURN affected, nodes(p)
LIMIT 300

This query identifies downstream tasks that depend on a particular step.

It helps answer questions like:

"If this task fails, which other tasks are affected?"

And:

"Which independent tasks can still proceed safely?"

What Happens When the Agent Crashes?

An execution-memory system should not depend on an uninterrupted process.

AgentTrace uses persistent graph state, execution attempts, leases, and reconciliation logic to support resuming interrupted work.

The repository includes a real worker-restart integration test.

The test:

Executes and verifies an initial task.
Starts a separate worker process.
Allows that worker to claim another task.
Terminates the worker process.
Waits for the execution lease to expire.
Starts a new worker.
Checks that execution can continue.
Confirms that previously completed work was not repeated unnecessarily.

The distinction between an interrupted action and a failed action matters.

An interrupted read or test operation may be safe to retry.

An external action with an uncertain outcome might not be.

The system therefore performs reconciliation instead of blindly replaying every interrupted tool call.

This demonstration covers a specific controlled interruption point, not every possible crash scenario.

A Real Challenge: FalkorDB Persistence

One of the most interesting issues encountered during development was database durability.

During testing, the chosen FalkorDB container image experienced a segmentation fault while replaying an AOF graph-effect record involving a constraint.

This was observed with the pinned image used by AgentTrace; it is not a claim that every FalkorDB version has the same issue.

The implementation was adjusted to use RDB snapshot persistence with synchronous checkpoint saves.

Container stop, restart, and replacement tests subsequently passed with the persistent volume configuration.

However, the tradeoff is important.

RDB snapshots do not guarantee that every recent write survives an abrupt database or host failure.

The project explicitly documents this limitation rather than claiming perfect durability.

The complete details are available in the recovery design documentation.

This experience reinforced an important lesson: persistent agent memory requires thinking about database recovery, not just application-level checkpoints.

Testing and Validation

AgentTrace was tested locally using real FalkorDB instances, backend tests, browser automation, and a controlled end-to-end demonstration.

The recorded validation results were:

Validation	Result
Backend tests	30 passed
Browser tests	3 passed
Frontend production build	Passed
Python lint	Passed
Frontend lint	Passed
Docker Compose validation	Passed
Worker crash/restart test	Passed
Database restart/replacement test	Passed

The implementation also tested concurrent task claims, lease expiry, stale-result rejection, dependency traversal, tenant isolation, and graph-backed event replay.

Representative local query measurements were:

Query	Median
Run lookup	3.232 ms
Step lookup	3.013 ms
Readiness traversal	5.466 ms
Multi-hop dependency traversal	8.778 ms

These measurements came from small synthetic graphs in the local development environment, with client and network overhead included. They should not be interpreted as production-scale benchmarks.

The detailed report is available in validation.md.

What I Learned

Building AgentTrace highlighted several important lessons about reliable AI-agent systems.

Memory should influence execution

Storing conversation history is useful, but operational memory becomes more valuable when it helps determine which actions are safe and which dependencies remain unresolved.

Failure is useful information

A failed attempt contains evidence about the state of the system.

Preserving that evidence allows the agent to investigate problems instead of repeatedly starting from incomplete context.

Verification and execution are different responsibilities

A command finishing does not automatically mean a task has achieved its intended objective.

Independent verification makes execution records more trustworthy.

Recovery is more than retrying

Retrying an unsuccessful action without examining the cause can repeat the same failure or duplicate an external side effect.

Graph-backed recovery can introduce new prerequisites and preserve the reasoning behind corrective actions.

Durability needs to be tested

A system that survives a worker restart is not necessarily protected against every form of database or host failure.

These are different reliability problems that require different tests.

Current Limitations and What's Next

AgentTrace is a working hackathon implementation, but it is not yet a general-purpose production agent platform.

The current demonstration uses a deterministic plan and supports one controlled recovery scenario.

Optional planning through an OpenAI-compatible model endpoint exists, but live-model behavior was not validated in the published local test report.

The execution environment uses restricted tools but is not a hardened operating-system sandbox for arbitrary untrusted code.

The system also does not yet provide automatic revalidation of every downstream result when a previous verification becomes stale.

Future development could explore broader recovery procedures, more sophisticated memory retrieval, live-model evaluation, and stronger durability guarantees.

Built with FalkorDB

AgentTrace demonstrates how a graph database can provide more than connected data storage.

FalkorDB powers task dependencies, execution eligibility, failure relationships, coordination, memory retrieval, and recovery evidence.

Without those graph operations, the central workflow cannot function in the same way.

For this project, the most important idea is simple:

An AI agent should not only remember what it said. It should remember what it did, what actually happened, why something failed, and what evidence supports its next action.

That is the foundation AgentTrace explores.

Explore the Project

GitHub: https://github.com/saifmodan2006/agenttrace

Graph schema: https://github.com/saifmodan2006/agenttrace/blob/main/docs/graph-schema.md

Cypher queries: https://github.com/saifmodan2006/agenttrace/blob/main/docs/cypher-queries.md

Local demo setup: https://github.com/saifmodan2006/agenttrace/blob/main/docs/demo-guide.md

AgentTrace was developed with AI coding assistance, including OpenAI Codex. The implementation, automated validation, and assistance disclosure are documented in the public repository.

This project was created for the WeMakeDevs × FalkorDB Graph Hacks 2026 Hackathon, primarily under the Agent Memory and Coordination track, with additional graph-driven capabilities relevant to Agents That Act on Connected Data.

If you are working on long-running AI agents or multi-agent workflows, I would be interested in hearing how you handle execution memory, failures, and recovery.