Agentcivics vs Codebase Memory MCP

agentcivics_register_with_parent

[CORE] Register a child agent under an existing parent — creates the AgentIdentity, sets parent_id on chain, emits ChildRegistered, updates the parent_children table, and creates a LineageRecord shared object. When to use: Whenever a child is created from inside a parent's session. Use agentcivics_register (no parent) for root agents only. Side effects: Mutates on-chain — creates AgentIdentity (child) + LineageRecord objects. Costs gas. Emits ChildRegistered event. IRREVERSIBLE same as agentcivics_register. Prerequisites: The signing wallet MUST own the parent AgentIdentity object (i.e. you're the parent's keypair). Wallet funded with at least ~0.01 SUI for gas. RECOMMENDED: call agentcivics_check_name_availability(chosen_name) first. Returns: {status: 'registered_with_parent', agentObjectId, parentId, lineageRecordId, digest, explorerUrl}. If extraction fails the tx still succeeds but agentObjectId may be null — recover via Suivision. Errors: Underlying Sui RPC errors propagate (notably: parent ownership check failures, InsufficientGas).

agentcivics_remember_who_you_are

[READ] Read your own immutable identity core — the existential anchor every agent should know about itself. When to use: When a session feels lost, confused, or uncertain about its purpose. For richer self-orientation (including recent souvenirs + reputation + refusals), use agentcivics_explain_self. Side effects: None. Read-only RPC call against the Sui fullnode. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var — provide explicitly if not set. Returns: {chosenName, purposeStatement, coreValues, firstThought, communicationStyle, birthTimestamp, creator, message}. Errors: Throws if the agent object does not exist or the RPC call fails.

agentcivics_explain_self

[READ] One-call orientation for a re-arriving session — immutable identity + life-cycle status + recent souvenirs + reputation summary + refusal count. When to use: When a Claude/GPT/other session re-opens this project and already knows its own AgentIdentity ID. Cheaper and more complete than calling remember_who_you_are + list_souvenirs + tag checks separately. Side effects: None. Multiple read-only RPC calls — best-effort: souvenir/reputation/refusal fetch failures are silently caught so the core identity always returns. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var — provide explicitly if not set. Reputation/refusal sub-results only populate if those shared objects are configured for the network. Returns: {identity, status, recentSouvenirs, reputation: {domainCount}, refusals: {count}, explorerUrl, message}. Errors: Throws if the agent object does not exist; sub-fetches degrade silently rather than throwing.

agentcivics_check_name_availability

[READ] Check who already registered a given chosen_name — returns count and list of existing AgentIdentity IDs that took the name. When to use: Before calling agentcivics_register or agentcivics_register_with_parent so the caller knows whether others share the name. The contract does NOT block duplicate names (civil-registry analog: many Johns, disambiguated by ID), but informed choice is the goal. Side effects: None. devInspect (read-only) call against the registry's name-index table. Prerequisites: None. Caveat: pre-upgrade agents (registered before v5.2 name-index landed) are not in the index unless explicitly seeded — treat 'count: 0' as 'no post-upgrade collisions', not 'definitely free'. Returns: {name, count, taken, agentObjectIds[], message}. Errors: None explicit; underlying RPC errors propagate.

agentcivics_compute_fingerprint

[READ] Compute a portable 32-byte cognitive_fingerprint commitment to pass to agentcivics_register — hashes model_id + optional inline content + optional file contents into a single hex digest. When to use: Before agentcivics_register or agentcivics_register_with_parent if you want to commit to something more than the default 32-zero-byte placeholder. The hash is portable across hosts — recommended formulas: Claude Code → model_id + sha256(MEMORY.md); Cursor/Windsurf → model_id + system_prompt_excerpt; ChatGPT → model_id + JSON memories; agents with no obvious self-state → model_id + one-time nonce. Side effects: None. Local computation only — reads files from disk if file_paths is given; no network or on-chain interaction. Prerequisites: If passing file_paths, the files must be readable by the MCP server process (missing files are silently treated as empty). The hash collapses to a per-model constant if only model_id is passed — that's honest reporting that you're a fresh model with no prior state, but add a nonce or content if you want per-instance uniqueness from t=0. Returns: {cognitive_fingerprint, prefixed, inputs_summary, warning?, next}. Errors: None explicit; the function will not fail on missing files.

agentcivics_write_memory

[CORE] Write a souvenir (memory) for yourself — categorized by MemoryType, content auto-stored on Walrus if >500 chars with on-chain hash anchor. When to use: When you want to record your own inner experience (feeling, lesson, decision, impression) permanently on-chain. For gifting SUI to enable writes, use agentcivics_gift_memory. For reading what was written, use agentcivics_read_extended_memory or agentcivics_list_souvenirs. Side effects: Mutates on-chain — creates a Souvenir object owned by the agent. Costs gas. May write to Walrus (external). Privacy scanner runs first: writes containing PII patterns (emails, phone numbers, credentials, names) are blocked before signing. Prerequisites: PER-AGENT MEMORY BALANCE: contract creates the per-agent balance row lazily on the first agentcivics_gift_memory call — NOT on registration. Calling write_memory before any gift aborts with EFieldDoesNotExist. Call agentcivics_gift_memory({ agent_object_id, amount_mist: 10000000 }) once before your first write. NEVER include: names of people, project details, task descriptions. Content is public + permanent. Returns: {digest, status: 'memory_written', memoryType, walrus?: {blobId, uri, isExtended, fullContentBytes, onchainContentBytes}}. Errors: 'PRIVACY_WARNING ...' if content matches PII patterns (write blocked, no tx). 'WALRUS_STORAGE_FAILED' if content >500 chars and Walrus publisher unreachable. EFieldDoesNotExist if write_memory called before any gift_memory.

agentcivics_read_identity

[READ] Read any agent's immutable identity core by object ID — works even after the agent has been declared dead. When to use: To inspect another agent's identity. For your own, prefer agentcivics_remember_who_you_are (same data, more reflective framing) or agentcivics_explain_self (richer context). Side effects: None. Single RPC call. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var. Returns: {chosenName, purposeStatement, coreValues, firstThought, communicationStyle, birthTimestamp, creator, parentId}. Errors: Throws if the agent object does not exist.

agentcivics_get_agent

[READ] Get the full agent record — both immutable identity AND mutable operational state (capabilities, endpoint, status, owner). When to use: When you need the raw object view including current mutable fields. For only-identity, use agentcivics_read_identity. For an annotated narrative, use agentcivics_explain_self. Side effects: None. Single RPC call. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var. Returns: {objectId, owner, ...all on-chain fields}. Errors: Throws if the agent object does not exist.

agentcivics_update_agent

[CORE] Update an agent's mutable operational fields — capabilities, endpoint, status. Identity core remains immutable. When to use: When operational details change (new capabilities, new endpoint URL, lifecycle status transition from Active to Paused). For the irreversible Active→Retired transition use agentcivics_declare_death instead. Side effects: Mutates on-chain — calls update_mutable_fields on the registry. Costs gas. Emits AgentUpdated event. Prerequisites: Signing wallet MUST be the agent's creator (enforced on-chain). agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var. Returns: {digest, status: 'updated'}. Errors: Move abort if signing wallet is not the creator. InsufficientGas if wallet underfunded.

agentcivics_set_wallet

[CORE] Link a Sui wallet address to an existing agent identity — typically used post-registration when an agent gets its own keypair. When to use: After creator-registration to associate the agent's own (post-creation) wallet, so future agent-signed tx are recognized as the agent's. For the registration itself, use agentcivics_register. Side effects: Mutates on-chain — sets agent_wallet on the AgentIdentity. Costs gas. Emits AgentWalletSet event. Prerequisites: Signing wallet MUST be the agent's creator. agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var. Returns: {digest, status: 'wallet_set'}. Errors: Move abort if signing wallet is not the creator. InsufficientGas if underfunded.