Agent memory tools, honestly compared: memory APIs, session capture, notes, and a shared record

Agent memory tools, honestly compared: memory APIs, session capture, notes, and a shared record

By Mike Schreiber

“Memory for AI agents” is a broad buying brief. Before comparing tools, specify what needs remembering: a user preference, evidence of work, a standing instruction, or a project decision. Those are different requirements, even when one workflow needs all of them.

This guide compares four approaches by the job you would hire them to do. It does not rank named memory APIs or session recorders without verified documentation. The product-specific details below are limited to the supplied Hark documentation and verified instruction-file sources.

The useful question is not simply “Which remembers more?” It is “What should the next agent know, and who gets to say it is true?”

Four approaches, four evaluation questions

1. Memory APIs: what should an application remember about a user?

Evaluate a memory API when the requirement is application-level recall. Frame the trial around your own requirements rather than assuming every vendor offers the same extraction, retrieval, deletion, or access controls.

Hypothetical example: A meal-planning application needs to remember that a user prefers vegetarian lunches. Test whether a correction replaces the earlier preference, whether retrieval stays within that user's scope, and whether deletion meets your requirements.

Ask candidates to demonstrate:

• How a remembered item is created and corrected.
• How retrieval is restricted to the right user.
• How conflicting statements are handled.
• What your expected read and write pattern would cost.

This is a different problem from deciding whether a project may change its billing architecture. Do not use a personalization test as evidence that a tool handles project governance.

2. Session capture: what happened during the work?

Evaluate session capture when your primary question concerns the work trail. Define the evidence you need before choosing a recorder: prompts, tool actions, file changes, test results, or links to commits.

Hypothetical example: A maintainer wants to investigate why a retry loop changed. A useful trial would ask the candidate system to recover the relevant session evidence, then compare that evidence with the committed change.

Check capture scope, access, retention, redaction, and retrieval directly in the candidate's documentation. Do not assume a recording proves that a human approved an architectural choice. In your workflow, label the recording as evidence and record approval separately.

Session evidence and current instructions should answer different questions: “What happened?” versus “What should happen next?”

3. Notes and instruction files: what guidance should persist?

Start with notes when you can maintain a small, explicit set of conventions. Claude Code reads CLAUDE.md instructions at session start; its documentation recommends keeping session-wide facts there and moving multi-step procedures or narrowly scoped guidance into skills or path-scoped rules. Claude Code memory documentation

Cursor provides persistent rules, including version-controlled project rules in .cursor/rules. Codex builds an instruction chain at startup and merges project guidance from the root toward the working directory, with closer instructions overriding earlier guidance. Cursor rules · Codex AGENTS.md guidance

Hypothetical example: Keep “Run the billing tests before submitting billing changes” in persistent guidance. Put “The staging migration is currently blocked” in a separately maintained status note with an owner and review date.

Notes need not be informal. You can impose headings for decisions, evidence, proposals, and superseded guidance. The evaluation question is whether maintaining that structure manually fits your workflow.

4. A shared project record: what is current, and who approved it?

Hark separates stable repository context from living project state and composes them into an agent brief. Its documented session flow includes reading the brief, recording work during the session, and ending with a handoff. Hark working with agents

The important distinction is between human decisions, observed work, and proposed notes. Under Hark's default Standard trust level, agent proposals require review, while repository facts backed by a commit, pull request, or release are accepted as observed. Decisions are never automatically approved at any trust level. Hark working with agents

Hypothetical example: A team is changing invoice delivery:

• Human decision: Keep the existing payment provider for this release because reconciliation depends on it.
• Observed work: A linked commit adds an invoice-preview endpoint.
• Proposed note: The agent suggests that staging validation should happen next.

Do not collapse these into “The payment migration is approved.” A commit demonstrates work, not permission to change the plan.

Hark's Relaxed and Autopilot settings allow specified non-decision content to be auto-accepted. Conflicts with accepted decisions still go to review, and automatically accepted content is labelled “Auto-approved.” Review settings therefore matter when interpreting the record. Hark working with agents

A sequential trial that tests the handoff

Step 1: Write the failure you want to prevent

Choose a concrete question: “Will the next agent preserve the payment-provider constraint?” is more testable than “Will it remember the project?” Define a passing answer before installation.

Keep the first trial narrow. Use a test project without sensitive production material, and assign a person to review inferred statements.

Step 2: Establish stable instructions

Write conventions separately from temporary status. For Claude Code, session-wide build commands and house rules belong in CLAUDE.md according to its guidance. Claude Code memory documentation

For the hypothetical invoice project, record the test command as a convention. Record the provider constraint as a decision with its rationale, rather than expecting an agent to infer that rationale from code.

Step 3: Connect and verify the chosen client

For a Hark trial using Codex, the documented connection commands are below. Login opens a browser for sign-in and approval; codex mcp list confirms the connection. Hark Codex connection guide

codex mcp add hark --url https://harkstudio.io/mcp

codex mcp login hark

codex mcp list

Then ask, “List my Hark workspaces.” That is the documented verification prompt. Confirm the intended workspace before creating test data. Hark Codex connection guide

Step 4: Record what code cannot tell you

Hark's repository setup flow uses propose_venture_from_project to propose the project and build state, then asks the user for a constraint or decision not visible in the code. Hark setup from your repo

Treat inferred rationale as a proposal to check. In this hypothetical trial, the human supplies the reconciliation constraint; the agent should not invent a business reason from the payment integration alone.

Step 5: Finish work, then test a fresh session

Hark documents end_session as the close of a working session, producing a handoff organized around what was done, what changed, what comes next, and cautions. Its handoff test is to open another client or fresh session and request get_agent_brief for the project. Hark working with agents · Hark setup from your repo

Ask the incoming agent to distinguish the accepted constraint from observed implementation and suggested next work. This tests continuity of the project record, not transfer of chat history.

Troubleshooting and boundaries

Connected, but authentication keeps looping? Hark's documented remedy is to remove the connector, sign out, sign back in, and re-add it. A plan-cap error instead indicates the workspace's monthly agent-call cap; check billing rather than repeating authentication. Hark Codex connection guide

The incoming brief differs from your expectation? Check the project identity, review outstanding candidates, and inspect the configured trust level. Hark provides list_candidates for unreviewed proposals and close_session to stop a session without a handoff when an agent is on the wrong project. Hark working with agents

Need a repository-readable fallback? With repo export enabled for a linked repository, Hark writes accepted content into .hark/HANDOFF.md, .hark/DECISIONS.md, and an AGENTS.md block. Those exported files remain readable if Hark is unreachable. This is not a claim that every service function works offline. Hark working with agents

Concerned about sensitive session material? The Claude Code mod sends a handoff summary, not prompts, transcripts, file contents, or diffs. Its closing-note cleaning is best effort: a secret written in prose could still be sent. Do not generalize this mod-specific boundary to every integration. Hark Claude Code mod

FAQs

Do I need all four approaches?

No. Start with the smallest workflow that passes your test. Add another layer only for a distinct unmet requirement.

Can Hark automatically approve decisions?

No. Its documentation says decisions are never approved automatically, regardless of trust level. Hark working with agents

Is a handoff a session replay?

Treat them as different requirements. Hark's documented handoff summarizes work, changes, next steps, and cautions. Test any transcript-retrieval requirement separately. Hark working with agents

Sources

• Hark: Working with agents
• Hark: Set up from your repo
• Hark: Codex connection
• Hark: Claude Code mod
• Claude Code: Memory
• Cursor: Rules
• Codex: AGENTS.md guidance